在 Inertia Rails + React 中把…

当你在 Inertia.js + Rails + React 项目中使用 shadcn/ui，或从 Next.js 示例迁移 shadcn 组件时，按本经验替换 Next.js 专用依赖并接通 Inertia 导航、表单、Flash Toast 与暗色模式。

适用场景

解决思路

1. 使用前先审查 shadcn 示例：若使用 `react-hook-form` + `zod`，改为 Inertia `<Form>` 组件并为输入控件添加 `name` 属性；让 Inertia 处理 CSRF、错误、重定向和处理中状态，不要用 react-hook-form 对抗这些机制。
2. 若示例包含 `'use client'`，删除它；Inertia 没有 RSC，所有组件都是客户端组件。
3. 若示例使用 `next/link`、`next/head`、`useRouter()`，分别替换为来自 `@inertiajs/react` 的 Inertia `<Link>`、`<Head>`、`router`。
4. 对照替换 shadcn 的 Next.js 默认写法：`'use client'` 指令 -> 删除；`react-hook-form` + `zod` -> Inertia `<Form>`；`FormField`/`FormItem`/`FormMessage` -> 普通 `<Input name='...'>` + `errors.field`；`next-themes` -> CSS class 策略 + `@custom-variant`；Next 的 `useRouter()` -> 从 `@inertiajs/react` 导入 `router`；`next/link` -> 从 `@inertiajs/react` 导入 `<Link>`；`next/head` -> 从 `@inertiajs/react` 导入 `<Head>`。
5. 绝不使用 shadcn 的 `FormField`、`FormItem`、`FormLabel`、`FormMessage` 组件；它们内部依赖 react-hook-form 的 `useFormContext`，没有 react-hook-form 会崩溃。
6. 在 Inertia `<Form>` 内使用普通 shadcn `Input`/`Label`/`Select` 并设置 `name` 属性，从 render 函数的 `errors` 对象渲染错误。
7. 用普通组件 + 手动错误显示替换 shadcn 表单组件，例如：`<Label htmlFor='name'>Name</Label>`、`<Input id='name' name='name' />`，然后 `{errors.name && <p className='text-sm text-destructive'>{errors.name}</p>}`。
8. `<Select>` 必须添加 `name` 属性才能与 Inertia `<Form>` 集成，例如 `<Select name='role' defaultValue='member'>...</Select>`；shadcn 示例因为 react-hook-form 管理值而省略它。
9. 初始化 shadcn：运行 `npx shadcn@latest init`。
10. 如果 `tsconfig.json` 中没有 `@/` 解析别名，则添加它。
11. 不要把 `@/` 解析别名添加到 `vite.config.ts`；`vite-plugin-ruby` 已经提供这些别名。
12. Dialog 与 Inertia 导航集成：从 `@/components/ui/dialog` 导入 Dialog 相关组件，从 `@inertiajs/react` 导入 `router`；通过 `open` 和 `onOpenChange` 控制；当关闭时调用 `router.replaceProp('show_dialog', false)`。
13. Dialog 的 `onOpenChange` 写为：`onOpenChange={(isOpen) => { if (!isOpen) { router.replaceProp('show_dialog', false) } }}`。
14. Table 使用 shadcn `<Table>` 正常渲染；服务端排序通过 `router.get` 实现。
15. 排序处理：`const handleSort = (column: string) => { router.get('/users', { sort: column }, { preserveState: true }) }`。
16. 在 `TableHead` 上绑定点击排序：`onClick={() => handleSort('name')}`，加 `className='cursor-pointer'`，并根据 `sort` 显示箭头。
17. 行链接使用 `<Link>`（不要用 `<a>`）以保留 SPA 导航。
18. Toast 与 Flash 消息：flash 配置在 `inertia-rails-controllers`，flash 访问在 `inertia-rails-pages`；本技能只覆盖 toast UI 接线。
19. 用 Sonner 实现基于 flash 的 toast 时，必须完整阅读 `references/flash-toast.md`（约 80 行），其中包含完整 `useFlash` hook 和 Sonner toast provider；如果只读取 flash 值而没有 toast UI，不要加载它。
20. 关键坑：Rails initializer 中的 `flash_keys` 必须与 `FlashData` TypeScript 类型匹配；除非同时更新两处，否则不要使用 `success`/`error`。
21. 暗色模式不使用 `next-themes`；`npx shadcn@latest init` 会生成 light/dark 的 CSS 变量，以及 Tailwind v4 的 `@custom-variant dark (&:is(.dark *));`，变量本身无需额外设置。
22. 防止错误主题闪烁（FOUC）：Next.js 自动处理，Inertia 不会；在 `<head>` 中、样式表之前添加内联脚本，在 React hydrate 之前切换 `dark` class。
23. 内联脚本示例：在 `app/views/layouts/application.html.erb` 的 `<head>`、任何样式表之前，使用 `document.documentElement.classList.toggle('dark', localStorage.appearance === 'dark' || (!('appearance' in localStorage) && window.matchMedia('(prefers-color-scheme: dark)').matches))`。
24. 在 Inertia 入口点调用 `initializeTheme()`：在 `app/frontend/entrypoints/inertia.tsx` 中 `import { initializeTheme } from '@/hooks/use-appearance'`，并在 `createInertiaApp` 之前调用 `initializeTheme()`。
25. 使用 `useAppearance` hook（支持 light/dark/system 模式、localStorage 持久化、`matchMedia` 监听）替代 `next-themes`；通过 `<html>` 上的 `.dark` class 切换，无需 provider。
26. 故障排除：`FormField`/`FormMessage` 崩溃时，说明使用了依赖 react-hook-form 的 shadcn 表单组件；改用普通 `Input`/`Label` + `errors.field` 显示。
27. 故障排除：`Select` 值未提交时，缺少 `name` 属性；给 `<Select>` 添加 `name='field'`。
28. 故障排除：Dialog 意外关闭时，缺少或错误的 `onOpenChange` 处理器；使用 `onOpenChange={(open) => { if (!open) closeHandler() }}`。
29. 故障排除：主题闪烁时，缺少 `<head>` 内联脚本；在样式表之前添加暗色模式脚本。
30. 构建超出上述范围的 shadcn 组件（Accordion、Sheet、Tabs、DropdownMenu、AlertDialog 的 Inertia 模式）时，加载 `references/components.md`（约 300 行）。
31. 不要为基本 Form、Select、Dialog、Table 用法加载 `components.md`；上面的示例已足够。
32. 需要完整 `<Form>` API 时参考 `inertia-rails-forms`；需要 flash 配置参考 `inertia-rails-controllers`；需要 flash 访问参考 `inertia-rails-pages`；需要 URL 驱动对话框参考 `inertia-rails-pages` 的 `router.get` 模式。

适用边界 · 注意事项

• 不适用于 Next.js 项目：该技能是 Inertia Rails React 适配，Next.js 应使用原生 shadcn/ui 与 Next.js 默认写法。
• 不适用于没有 Inertia.js、Rails、React 或 shadcn/ui 的项目。
• 如果决定使用 react-hook-form + zod 管理表单，不要按本技能替换为 Inertia <Form> 的方式，否则两套机制会冲突。