konsta-ui

面向 Capacitor 的 Konsta UI

何时使用

在以下情况触发：

• 将 Konsta UI 添加到 Capacitor 应用，或选择它而非 Ionic
• 将 Konsta v3/v4（Tailwind v3 konstaConfig）升级到 v5（Tailwind v4）
• 组件没有样式、颜色被忽略、ios:/material: 类不起作用
• Navbar / Tabbar 位于状态栏或手势栏下方
• 主题应跟随平台（iPhone 上使用 ios，Android 上使用 material）

请勿用于：

• Ionic Framework 组件或主题：ionic-design
• 不涉及 Konsta 的 Tailwind 安装/配置：tailwind-capacitor
• Android SystemBars / 全屏显示原生配置：safe-area-handling
• 表单中的键盘遮挡问题：capacitor-keyboard

版本（2026 年 10 月）

Konsta	Tailwind	框架	配置方式
5.x（latest，5.5.0）	v4	React 19（ref 作为 prop）、Vue 3、Svelte 5（runes、snippets）	CSS：@import 'konsta/<fw>/theme.css' + @theme
4.x	v3	新增 Svelte 5 类型	JS：在 tailwind.config.js 中使用 konstaConfig()
3.x 及以下	v3		JS konstaConfig()

先检查：npm ls konsta tailwindcss react vue svelte。切勿将 v5 CSS 配置与 tailwind.config.js 中的 konstaConfig 包装器混用。

工作流

1. 检查版本、主 CSS 文件、tailwind.config.*、postcss.config.*、vite.config.*、index.html 视口 meta，以及是否同时引入了 Ionic。
2. 安装 / 升级（见下文）。对于现有的 Tailwind v3 项目，先迁移 Tailwind（tailwind-capacitor）。
3. 使用 App 包装应用（或与 Ionic/Framework7 搭配时使用 KonstaProvider）。
4. 构建界面时使用组件：references/components.md。
5. 验证（见下文）。

仅在涉及相应主题时加载参考资料。

设置（v5，示例使用 React；Vue/Svelte 使用 konsta/vue/theme.css / konsta/svelte/theme.css）

npm i konsta tailwindcss @tailwindcss/vite

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({ plugins: [react(), tailwindcss()] });

/* src/index.css */
@import 'tailwindcss';
@import 'konsta/react/theme.css';

@theme {
  --color-brand-primary: #007aff; /* only --color-brand-* drive component colors */
  --color-brand-red: #ff3b30;     /* use with class k-color-brand-red */
}

import { Capacitor } from '@capacitor/core';
import { App } from 'konsta/react';

const theme = Capacitor.getPlatform() === 'android' ? 'material' : 'ios';

export default function Root() {
  return (
    <App theme={theme} safeAreas>
      {/* pages */}
    </App>
  );
}

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

App 属性：theme（'ios' | 'material' | 'parent'，默认值为 material）、safeAreas（默认值为 true）、dark、iosHoverHighlight、materialTouchRipple（v5 新增的全局开关）。每个应用只能有一个 App。

Material 的 Roboto 字体需要自行添加（使用 Google Fonts 链接或自托管以支持离线使用）。iOS 使用系统字体。

从 v4 迁移到 v5

v4	v5
tailwind.config.js：module.exports = konstaConfig({...})	删除包装器；在 CSS 中添加 @import 'konsta/react/theme.css'
konstaConfig.colors.primary	@theme { --color-brand-primary: ... }
每个组件单独配置 ripple	优先使用全局 App materialTouchRipple；检查所安装版本中的组件类型
SegmentedButton strong rounded	已移除；使用 Segmented 的主题专属样式属性
Link navbar/toolbar/tabbar 属性	已移除；由上下文驱动
React forwardRef 用法 / innerRef 模式	ref 属性（React 19）
Svelte slots	{#snippet ...}

如果 Tailwind 本身仍为 v3，请运行 Tailwind v4 升级命令（npx @tailwindcss/upgrade）；参见 tailwind-capacitor。

注意事项

• 如果同一应用中同时使用 Ionic，请使用 KonstaProvider（而非 App），并选择一个安全区域管理方（Ionic 的 --ion-safe-area-* 或 Konsta 的 safe-areas），不要同时使用两者。
• Konsta v5 的深色模式基于 class（其 CSS 中的 @custom-variant dark (&:where(.dark, .dark *))）：在 <html> 上切换 dark，设置 App dark，并使用 SystemBars.setStyle 让原生系统栏保持一致。
• Konsta 自己的文档展示了 user-scalable=no, maximum-scale=1；为保证无障碍访问，建议允许缩放，并改用 16px 输入框来解决 iOS 输入框缩放问题。
• 非全屏的模态框/侧面板需要使用 no-safe-areas（或 no-safe-areas-top 等），以避免额外留白。
• Konsta 仅提供 UI：不包含路由器或页面转场。请搭配 React Router / Vue Router / SvelteKit，并使用 @capacitor/app 的 backButton 处理 Android 返回按钮。

验证

1. 运行 npm run build && npx cap sync，并在 iOS 和 Android 上运行。
2. 检查 <html>/根元素：存在 .k-ios 或 .k-material 类；ios:/material: 工具类生效。
3. Navbar 避开灵动岛；Tabbar 避开主屏幕指示条和 Android 手势栏（Android 15+ 全面屏显示）。
4. 切换深色模式；组件和状态栏图标同步切换。
5. 检查是否有残留：在 v5 中，grep -rn "konstaConfig\|konsta/config" . 不应返回任何结果。

错误处理

错误 / 现象	原因	修复方法
Cannot find module 'konsta/config'	v5 移除了 JS 配置	使用 CSS @import 'konsta/react/theme.css'
组件渲染时没有样式	未导入主题 CSS，或 Tailwind 未扫描到（没有 @tailwindcss/vite / @tailwindcss/postcss）	在 @import 'tailwindcss' 后导入主题；添加 Tailwind 插件
[postcss] It looks like you're trying to use tailwindcss directly as a PostCSS plugin	Tailwind v4 的 PostCSS 插件已迁移	使用 @tailwindcss/postcss 或 @tailwindcss/vite
品牌颜色未生效	变量名称不是 --color-brand-*，或定义在 @theme 之外	在 @theme 内重命名
ios: 类无效	缺少 App/KonstaProvider，因此没有 .k-ios 祖先元素	包裹应用
升级后出现关于 ref / forwardRef 的 React 警告	React 18 与 Konsta 5 不兼容	升级到 React 19，或继续使用 Konsta 4
顶部内边距重复	Konsta safeAreas 与 Ionic 或自定义 env() 内边距同时生效	只保留一方负责

资源

• Konsta UI：https://konstaui.com
• React 安装：https://konstaui.com/react/installation
• 安全区域：https://konstaui.com/react/safe-areas
• 颜色：https://konstaui.com/react/colors
• 更新日志：https://github.com/konstaui/konsta/blob/master/CHANGELOG.md