在 Capacitor 移动应用中使用 Tailwind…

当需要在 Capacitor 混合移动应用里用 Tailwind CSS 做移动优先样式、处理刘海/Home 指示条安全区、触控友好交互、深色模式与性能优化时使用。

适用场景

解决思路

1. 安装依赖：运行 `npm install -D tailwindcss postcss autoprefixer`，再运行 `npx tailwindcss init -p` 生成配置。
2. 配置 `tailwind.config.js` 的 `content` 为 `['./index.html', './src/**/*.{js,ts,jsx,tsx,vue,svelte}']`，并在 `theme.extend` 中扩展移动端 spacing：`safe-top`/`safe-bottom`/`safe-left`/`safe-right` 分别映射到 `env(safe-area-inset-*)`，同时扩展 `minHeight.touch` 与 `minWidth.touch` 为 `44px`。
3. 在 `src/index.css` 中引入 `@tailwind base; @tailwind components; @tailwind utilities;`，并在 `@layer base` 里为 `html` 设置 `-webkit-text-size-adjust: 100%`、`scroll-behavior: smooth`、`overscroll-behavior: none`；为 `body` 设置 `-webkit-user-select: none`、`user-select: none`、`-webkit-touch-callout: none`、`position: fixed`、`width: 100%`、`height: 100%`、`overflow: hidden`；为 `input, textarea` 恢复 `-webkit-user-select: text` 与 `user-select: text`。
4. 在 `tailwind.config.js` 的 `theme.extend.padding` 中增加 `safe`/`safe-t`/`safe-b`/`safe-l`/`safe-r` 映射到对应 `env(safe-area-inset-*)`，并在 `theme.extend.margin` 中增加 `safe`/`safe-t`/`safe-b` 映射。
5. 在组件中使用安全区工具类：Header 用 `fixed top-0 left-0 right-0 pt-safe-t`，Footer 用 `fixed bottom-0 left-0 right-0 pb-safe-b`，Main 用 `pt-safe-t pb-safe-b h-screen overflow-y-auto overscroll-none`。
6. 触控目标至少 44x44：按钮使用 `min-h-[44px] min-w-[44px] px-4 py-3 flex items-center justify-center active:bg-gray-100 rounded-lg`；图标按钮使用 `h-11 w-11 flex items-center justify-center rounded-full active:bg-gray-100`，图标本身可小于触控区域。
7. 在 `index.css` 的 `@layer utilities` 中定义 `.touch-feedback`：`@apply transition-colors duration-75;`，并定义 `.touch-feedback:active` 为 `@apply bg-black/5 dark:bg-white/5;`，在按钮上使用 `touch-feedback p-4 rounded-lg`。
8. 在 `tailwind.config.js` 中设置 `future: { hoverOnlyWhenSupported: true }` 以在触屏设备禁用 hover；或用 `@media (hover: hover)` 包裹 `.hover-only:hover` 样式。
9. 深色模式：在 `tailwind.config.js` 中设置 `darkMode: 'media'`（跟随系统）或 `darkMode: 'class'`（手动控制）。
10. 手动深色模式：用 `@capacitor/preferences` 的 `Preferences.set({ key: 'theme', value: theme })` 保存主题；当主题为 `system` 时用 `window.matchMedia('(prefers-color-scheme: dark)').matches` 判断并 `document.documentElement.classList.toggle('dark', prefersDark)`，否则按 `theme === 'dark'` 切换；同时监听 `window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', ...)`，若当前主题为 `system` 则根据 `e.matches` 切换 `dark` 类。
11. 深色模式组件写法：容器用 `bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-xl shadow-sm dark:shadow-none`，标题用 `text-gray-900 dark:text-white`，正文用 `text-gray-600 dark:text-gray-400`。
12. 下拉刷新容器：使用 `h-full overflow-y-auto overscroll-contain touch-pan-y`。
13. 底部弹层：背景遮罩用 `fixed inset-0 bg-black/50 transition-opacity duration-300` 并根据 `isOpen` 切换 `opacity-100` 或 `opacity-0 pointer-events-none`；弹层用 `fixed left-0 right-0 bottom-0 bg-white dark:bg-gray-900 rounded-t-2xl pb-safe-b transition-transform duration-300 ease-out` 并根据 `isOpen` 切换 `translate-y-0` 或 `translate-y-full`；顶部加 `flex justify-center py-2` 的把手，内部为 `w-10 h-1 bg-gray-300 rounded-full`。
14. 滑动操作项：外层 `relative overflow-hidden`，背景操作区 `absolute inset-y-0 right-0 flex items-center bg-red-500 px-4` 内放 `text-white` 的 Delete；前景内容 `relative bg-white dark:bg-gray-800 transform transition-transform active:cursor-grabbing`。
15. 固定模糊头部：使用 `fixed top-0 left-0 right-0 pt-safe-t bg-white/80 dark:bg-gray-900/80 backdrop-blur-lg border-b border-gray-200/50 z-50`，内部 `h-14 px-4 flex items-center`。
16. 性能优化：在 `tailwind.config.js` 中保持 `content` 精确、`safelist` 仅放动态类；动画使用 `transform transition-transform duration-200 hover:scale-105 will-change-transform` 以启用 GPU 加速；避免布局抖动，优先用固定尺寸如 `w-full h-48` 而非 `w-full h-auto`。
17. 移动列表项：用 `w-full flex items-center gap-4 px-4 py-3 min-h-[60px] active:bg-gray-50 dark:active:bg-gray-800 text-left`，图片 `w-12 h-12 rounded-full object-cover`，文本容器 `flex-1 min-w-0`，标题 `font-medium text-gray-900 dark:text-white truncate`，副标题 `text-sm text-gray-500 truncate`，尾部图标 `w-5 h-5 text-gray-400`。
18. 移动按钮：基础类 `w-full min-h-[48px] px-6 py-3 font-semibold rounded-xl transition-colors duration-75 disabled:opacity-50`；变体 primary 为 `bg-blue-500 text-white active:bg-blue-600`，secondary 为 `bg-gray-100 text-gray-900 active:bg-gray-200`，danger 为 `bg-red-500 text-white active:bg-red-600`。
19. 移动输入框：label 内 span 用 `text-sm font-medium text-gray-700 dark:text-gray-300 mb-1 block`；input 用 `w-full px-4 py-3 text-base bg-gray-50 dark:bg-gray-800 border rounded-xl placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-blue-500`，错误时 `border-red-500`，否则 `border-gray-200 dark:border-gray-700`；错误提示用 `text-sm text-red-500 mt-1 block`；`text-base` 用于防止 iOS 缩放。

适用边界 · 注意事项

• 不适用于非 Capacitor 的纯 Web 项目（安全区、overscroll、长按行为等移动端处理可能不需要）。
• 不适用于未使用 Tailwind CSS 的项目。
• 不适用于需要桌面端 hover 交互为主、且不打算做触屏适配的场景。