GearUI Kit

使用 Kotlin Multiplatform（KMP）UI 框架 GearUI Kit，为 iOS、Android、Web 和 HarmonyOS 打造精美的 iOS 风格界面。

发布信息

坐标：com.gearui:gearui-kit:1.0.0
可从 Maven Central 获取；首个公开版本 1.0.0-beta1 发布于 2026-08-15
已发布产物：Android、iOS（arm64 / 模拟器 arm64 / x64）、JS（浏览器）
另可通过独立配置构建鸿蒙（ohosArm64）；未发布到 Maven Central
官网：https://gearui.com
License：Apache License 2.0

作者信息

作者：zoujiaqing
邮箱：[email protected]

界面截图

在 iPhone 17 Pro Max 模拟器（iOS 26.2）上运行 sample 截取。

首页（中文）	首页（英文）	设置页（亮色）	设置页（暗色）

语言与主题都在设置页运行时切换，所有组件自动跟随，无需逐屏适配。

组件一览

90 个组件，分 6 类，每一个在 sample 里都有对应演示页。

分类	组件
基础（12）	`Button`、`ButtonGroup`、`FabMenu`、`Icon`、`Link`、`SuggestionChips`、`CloseButton`、`PressableFeedback`、`Text`、`Tag`、`Badge`、`Divider`
表单（23）	`Input`、`Checkbox`、`AgreementCheckbox`、`Radio`、`InputOTP`、`ComboBox`、`NumberField`、`ToggleButton`、`InputGroup`、`Switch`、`Slider`、`Stepper`、`Textarea`、`Rate`、`Select`、`Picker`、`DatePicker`、`Upload`、`Form`、`Cascader`、`ListBox`、`Questionnaire`、`ColorPicker`
导航（8）	`NavBar`、`BottomNavBar`、`Tabs`、`Drawer`、`Steps`、`IndexBar`、`Segmented`、`Toolbar`
数据展示（25）	`List`、`Card`、`Cell`、`CellGroup`、`Table`、`Image`、`ImageViewer`、`Avatar`、`ScrollShadow`、`Collapse`、`Progress`、`Empty`、`Skeleton`、`Timeline`、`Calendar`、`Format`、`Watermark`、`Meter`、`User`、`Code`、`CodeBlock`、`Reasoning`、`ToolCallCard`、`AgentTrace`、`Kbd`
反馈（15）	`SwipeCell`、`ActionSheet`、`Toast`、`Dialog`、`Tooltip`、`ContextMenu`、`Loading`、`Alert`、`NoticeBar`、`Notification`、`Snackbar`、`Popup`、`Popover`、`Result`、`Tour`
布局（7）	`Grid`、`Swiper`、`SearchBar`、`PullRefresh`、`LoadMore`、`BottomSheet`、`BackTop`

各组件用途

基础

组件	中文名	用途
`Button`	按钮	用于触发操作
`ButtonGroup`	按钮组	相连按钮组与分体按钮
`FabMenu`	浮动按钮菜单	浮动按钮展开一组操作
`Icon`	图标	图标展示
`Link`	链接	文本链接与链接按钮
`SuggestionChips`	推荐问题	快捷回复与推荐问题
`CloseButton`	关闭按钮	统一的关闭/移除按钮
`PressableFeedback`	按压反馈	任意可点区域的缩放与高亮
`Text`	文本	文本展示
`Tag`	标签	标记和分类
`Badge`	徽标	消息数量提示
`Divider`	分割线	内容分隔

表单

组件	中文名	用途
`Input`	输入框	文本输入
`Checkbox`	复选框	多选操作
`AgreementCheckbox`	协议勾选	协议与隐私同意
`Radio`	单选框	单选操作
`InputOTP`	验证码输入	分格验证码输入
`ComboBox`	输入选择器	输入筛选的下拉选择
`NumberField`	数字输入	可输入可步进的数字字段
`ToggleButton`	切换按钮	保持按下状态的按钮与按钮组
`InputGroup`	输入框组	带前后附加块的输入框
`Switch`	开关	开关选择
`Slider`	滑块	数值选择
`Stepper`	步进器	数字增减
`Textarea`	多行输入	多行文本输入
`Rate`	评分	评分操作
`Select`	下拉选择	下拉选择器
`Picker`	选择器	多列选择
`DatePicker`	日期选择	日期时间选择
`Upload`	上传	文件上传
`Form`	表单	表单容器
`Cascader`	级联选择	级联选择器
`ListBox`	选项列表	在页面里直接列出的单选/多选
`Questionnaire`	问卷提问	逐题提问，单选/多选/自由输入，AI 澄清与向导
`ColorPicker`	颜色选择	色板、色域平面与十六进制输入

导航

组件	中文名	用途
`NavBar`	导航栏	通用页面导航栏
`BottomNavBar`	底部导航栏	应用底部主导航
`Tabs`	选项卡	内容切换
`Drawer`	抽屉	侧滑抽屉
`Steps`	步骤条	步骤指示
`IndexBar`	索引栏	通讯录字母索引
`Segmented`	分段控制	分段选择
`Toolbar`	工具栏	一组相关操作，窄屏自动换行

数据展示

组件	中文名	用途
`List`	列表	列表展示
`Card`	卡片	卡片容器
`Cell`	单元格	列表单元组件
`CellGroup`	单元格组	成组的列表行
`Table`	表格	数据表格
`Image`	图片	图片展示
`ImageViewer`	图片预览	图片预览查看
`Avatar`	头像	用户头像
`ScrollShadow`	滚动渐隐	滚动区域边缘渐隐
`Collapse`	折叠面板	内容折叠
`Progress`	进度条	进度展示
`Empty`	空状态	空数据提示
`Skeleton`	骨架屏	加载占位
`Timeline`	时间轴	时间线展示
`Calendar`	日历	日历展示
`Format`	本地化格式	万亿缩写、相对时间、农历
`Watermark`	水印	页面水印
`Meter`	计量值	已知上下限的计量值
`User`	用户摘要	头像、名称与说明的身份摘要
`Code`	代码块	行内代码与可复制的代码块
`CodeBlock`	代码块	行号、复制、diff、超长截断
`Reasoning`	思考过程	思考中展开，结束后收起
`ToolCallCard`	工具调用	Agent 的一次工具调用：参数与结果
`AgentTrace`	执行步骤	Agent 执行步骤与状态
`Kbd`	快捷键标记	Web 与外接键盘的按键提示

反馈

组件	中文名	用途
`SwipeCell`	滑动单元格	滑动操作单元格
`ActionSheet`	动作面板	底部动作面板
`Toast`	轻提示	消息提示
`Dialog`	对话框	模态对话框
`Tooltip`	文字提示	文字提示
`ContextMenu`	上下文菜单	上下文菜单
`Loading`	加载	加载状态
`Alert`	警示框	页面内状态提示
`NoticeBar`	公告栏	滚动公告栏
`Notification`	通知	全局通知
`Snackbar`	消息条	底部消息
`Popup`	弹出层	弹出内容
`Popover`	气泡	气泡提示
`Result`	结果	操作结果反馈
`Tour`	引导	功能引导

布局

组件	中文名	用途
`Grid`	栅格	栅格布局
`Swiper`	轮播	内容轮播
`SearchBar`	搜索栏	搜索输入
`PullRefresh`	下拉刷新	列表下拉刷新
`LoadMore`	加载更多	列表分页加载
`BottomSheet`	底部抽屉	底部弹出
`BackTop`	回到顶部	返回顶部

上表由 scripts/gen_component_index.py 从 sample/.../config/ComponentConfig.kt 生成；表过期时 CI 会失败。

快速接入

1. 发布版依赖（推荐）

已发布到 Maven Central。只需声明根坐标一行——Gradle 会读 module metadata，按当前编译目标自动解析到对应平台包（-android、-js、-iosarm64 …）。那些带后缀的坐标不要手写。

GearUI Kit 依赖 KuiklyUI，而 KuiklyUI 2.x 发布在腾讯 Maven 镜像而不是 Maven Central，所以还要加上这个仓库，否则依赖解析不到。

repositories {
    mavenCentral()
    maven("https://mirrors.tencent.com/nexus/repository/maven-tencent/")  // KuiklyUI 2.x
}

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("com.gearui:gearui-kit:1.0.0")
        }
    }
}

2. 本地联调依赖（mavenLocal）

先在 gearui-kit 工程发布到本地仓库：

./gradlew :gearui-kit:publishToMavenLocal

然后在业务工程引入：

repositories {
    mavenLocal()
    mavenCentral()
    maven("https://mirrors.tencent.com/nexus/repository/maven-tencent/")  // KuiklyUI 2.x
}

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("com.gearui:gearui-kit:1.0.0")
        }
    }
}

3. 同仓库模块依赖（开发期）

dependencies {
    implementation(project(":gearui-kit"))
}

基础使用

@Page("MainPage")
class MainPage : View() {
    @Composable
    // View mounts the App root (theme, i18n, overlays, safe area) for you.
    // Override themeMode() / themeSpec() to change it; do not call App() here.
    override fun Content() {
        MainPageContent()
    }
}

@Composable
private fun MainPageContent() {
    val colors = Theme.colors

    Column(
        modifier = Modifier
            .fillMaxSize()
            .background(colors.background)
            .padding(16.dp)
    ) {
        Button(
            text = I18n.strings.buttonConfirm,
            theme = ButtonTheme.PRIMARY,
            onClick = {}
        )
    }
}

Android 宿主：渲染线程栈

Kuikly 在自己的 context 线程上做组合、测量与布局，该线程用平台默认栈（约 1 MB）。布局放置每一层递归一次，页面层级深时会栈溢出——debuggable 构建最先出现，因为 ART 对它关闭了优化。在第一个页面打开前把它设成与主线程相同的 8 MB：

KuiklyRenderAdapterManager.krThreadAdapter = object : IKRThreadAdapter {
    private val executor = Executors.newCachedThreadPool()
    override fun executeOnSubThread(task: () -> Unit) = executor.execute(task)
    override fun stackSize(): Long = 8L * 1024 * 1024
}

sample 的做法见 SampleThreadAdapter。

平台支持

平台	最低版本	已验证到	尚未验收
Android	minSdk 21（compileSdk 36）	真机交互（小米 12 Pro，Android 16）；CI 跑单测与 lint	低端机性能
iOS	15.0	模拟器交互（iOS 18.2 与 27.0）；CI 在模拟器上跑 Kotlin 测试	Kit 本身的真机验收
Web（H5）	Chromium 内核浏览器	示例每个页面在明暗两种主题下加载、滚动、缩放正常（Playwright，Chromium）	键盘操作与焦点顺序；Safari/WebKit
HarmonyOS	—	端到端构建通过（Kit、NAPI 胶水、HAP）	真机或模拟器运行

工具链：Kotlin 2.1.21（必须与 KuiklyUI 一致）、KuiklyUI 2.30.0、Compose Multiplatform 1.7.3。

有限支持（各处说法一致）：

不支持从右到左（RTL）语言。 KuiklyUI 不传递布局方向。
iOS 不跟随系统动态字体。 KuiklyUI 在 iOS 上关闭了字体缩放；Android 的字号设置会跟随。
HarmonyOS 仅到构建级。 在真机上跑起来之前，界面上的一切都未经验证。
模糊效果默认关闭，等上游修复四个渲染器差异（见 docs/VISUAL_SPEC.md §5）。
Android 系统键盘跟随系统的明暗设置，而不是 App 的——平台没有提供设置接口。

点击区在所有平台都是 44 × 44。 这是遵循 Apple 规范的有意选择；Android 规范是 48 dp。控件的点击区不会与相邻控件重叠。

鸿蒙已支持，且全链路可构建——Kotlin/Native → CMake NAPI 胶水 → ArkTS → 一个包含 libshared.so 与 libkuikly_entry.so 的可安装 HAP。它无法作为常规构建的一个 target：带 ohosArm64 的 KuiklyUI 产物是基于 Kotlin 2.0.21-KBA-010 发布的，因此鸿蒙使用一套并行构建配置，通过 -c settings.ohos.gradle.kts 显式驱动：

./gradlew -c settings.ohos.gradle.kts :sample:linkSharedDebugSharedOhosArm64

HAP 尚未在真机或模拟器上启动过，因此鸿蒙上关于 UI 的一切都未经验证——安装还需要模拟器镜像和已签名的包，两者都要华为开发者账号。构建步骤与确切的剩余项见 sample/ohosApp/README.zh-Hans.md。

工程说明

组件层位于：gearui-kit/src/commonMain/kotlin/com/gearui/components
Sample 工程：sample/

组件收敛策略

导航类只保留核心入口：Tabs（内容切换）。
手风琴模式统一并入：Collapse.Accordion（不再单独维护 Accordion 组件）。
不保留同义包装组件，避免重复 API 和重复示例页面。

文档入口

架构总览：ARCHITECTURE.md
文档入口：docs/ARCHITECTURE.zh-Hans.md——设计系统、多语言、视觉规范、组件规范、覆盖对比与质量状态
Web 宿主：sample/jsApp/README.md
鸿蒙宿主：sample/ohosApp/README.md

文档以英文为主，*.zh-Hans.md 为对应中文版。代码注释一律英文—— 执行该约定的检查是 scripts/ci/check_english_comments.sh（见 docs/COMPONENT_SPEC.zh-Hans.md §8）。

开发命令

# 分平台编译库
./gradlew :gearui-kit:compileDebugKotlinAndroid
./gradlew :gearui-kit:compileKotlinIosSimulatorArm64
./gradlew :gearui-kit:compileKotlinJs

# 运行 sample
./gradlew :sample:installDebug                    # Android
./gradlew :sample:jsApp:jsBrowserDevelopmentRun   # Web，然后打开 http://localhost:8081/

# 鸿蒙走并行构建配置（尚未构建通过 —— 见 sample/ohosApp/README.md）
./gradlew -c settings.ohos.gradle.kts :sample:linkSharedDebugSharedOhosArm64

# 架构护栏 —— 脚本清单以 docs/COMPONENT_SPEC.zh-Hans.md §8 为准，全部可本地运行
for f in scripts/ci/check_*.sh; do "$f"; done

许可证

Apache License 2.0，详见 LICENSE 与 NOTICE。

gearui/gearui-kit

实测星标增长

关于

README.zh-Hans.md