# ComposeDesktopUI

**Repository Path**: notar_development_group/compose-desktop-ui

## Basic Information

- **Project Name**: ComposeDesktopUI
- **Description**: NativeUI for Compose Multiplatform
- **Primary Language**: Kotlin
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 0
- **Created**: 2021-09-28
- **Last Updated**: 2026-08-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Kotlin

## README

# NativeUI Compose Multiplatform

NativeUI 是一个面向 Compose Multiplatform 的组件库，目标是在 Compose 生态中复刻 Naive UI 的组件语义、视觉语言和文档体验。当前源码与本地发布验证版本为 `v0.4`；该版本尚未发布到 Maven Central。

[English README](README-en.md)

## Demo预览

![NativeUI 浅色主题预览](rmimg/compose-nativeui-light.png)

![NativeUI 深色主题预览](rmimg/compose-nativeui-black.png)

## 模块

- `nativeui`：组件库主体，包含组件实现、主题 token、默认 i18n 和多平台底座。
- `nativeui-debug`：可选的 Inspector、组件树、布局/组合统计、主题查看和 DevTools 面板。
- `nativeui-desktop-window`：Desktop 专用无边框窗口、NativeUI 标题栏和窗口控制。
- `nativeXIcons`：xicons 资源包，供 demo 与组件示例使用。
- `nativeTwemoji`：Twemoji 资源包。
- `demoShared`：三端共享的完整文档页面、路由、示例代码、API 表、i18n 和平台 bridge。
- `desktopDemo`：Desktop 宿主入口，附加启动页、系统托盘和原生窗口能力。
- `androidDemo`：Android 宿主入口，展示与 Desktop 相同的完整组件文档。
- `webDemo`：Web/Wasm 宿主入口，展示与 Desktop 相同的完整组件文档。

## 当前状态

`v0.4` 是当前的 Compose Multiplatform artifact 版本，已完成实现并按发布候选流程验证，但尚未发布到 Maven Central。Desktop 仍是视觉和交互的完整参考目标，三端共享组件实现与完整 demo 文档。

v3 多端适配分支已经完成基础链路验证：`nativeui` 主体组件与完整 demo 文档已经迁入 common source set，并通过 Desktop、Android 和 Web/Wasm 编译/打包链路验证。三端共用 `demoShared` 中的真实文档页面和路由，不再维护独立的缩水版 Web/Android 文档框架。少数依赖宿主能力的功能仍按平台降级，例如 Android 平台原生取色器、Android 打开所在文件夹和部分日期/时区格式化。

Desktop demo 的系统通知与托盘兼容 Windows、macOS 和 Linux。托盘在 Linux 按 AppIndicator、Dorkbox、AWT 顺序降级，在 Windows/macOS 按 Dorkbox、AWT 顺序降级；通知在 Linux 优先 `notify-send`，macOS 优先 `osascript`，Windows 使用 AWT，均保留 AWT fallback。最终可用性仍取决于系统桌面环境。

当前没有独立接入的 Naive 入口：

- `Equation`：暂不实现。KaTeX DOM/HTML 的选择、复制和 CSS 兼容语义难以在 Compose Desktop 中等价还原。
- `config-consumer`：语义并入 Config Provider 与本地配置 API。
- `legacy-grid`、`legacy-transfer`：属于 Naive 旧兼容入口，不纳入 v0.4 现代组件面。

组件用法、API 和 Compose 差异说明以 demo 组件页与 Dokka API 文档为准。

## 版本变化

- `v0.4`（v4）：89 个可见组件已按真实结构接入强类型 part 样式、自定义交互和 Inspector；R7 新增 Native DevTools、库内组合/布局/绘制统计、`NativeReorderableList`、`rememberNativeImagePainter` 共享缓存，以及独立的 `nativeui-desktop-window`。自动化三端门禁、本地发布与独立消费者验证纳入发布流程；跨平台像素、触摸、IME、窗口管理器与辅助功能按 [v4 目视验收手册](docs/V4_MANUAL_VISUAL_ACCEPTANCE.md) 留存证据。
- `v0.3`：升级为 Compose Multiplatform，三端共享组件和完整 demo。API：三个根坐标可解析 Desktop、Android、Web/Wasm 变体；系统通知增加 `permission()` / `requestPermission()` 和平台 bridge，既有 Desktop 调用保持兼容。
- `v0.2`：补充自适应布局和 Desktop 系统通知。API：新增 `NativeBreakpoint`、`NativeResponsiveMode`、`NativeAdaptiveInfo`、`LocalNativeAdaptiveInfo`、`nativeBreakpointForWidth`；`notify` 签名不变。
- `v0.1`：首个 Compose Desktop 发布，提供组件、主题、i18n、资源包和交互式文档。API：初始公开 API。

## 环境要求

当前源码分支使用以下环境构建并验证：

| 项目 | 版本 |
| --- | --- |
| Kotlin | `2.3.20` |
| Compose Multiplatform | `1.11.0` |
| JVM / JDK | `21` |
| Gradle Wrapper | `9.4.1` |

建议下游 Compose Multiplatform 项目使用不低于上述版本的 Kotlin、Compose Multiplatform 和 JDK。由于 Kotlin Multiplatform artifact 带有 Kotlin metadata，过低的 Kotlin 编译器版本可能无法解析依赖。

## 快速开始

发布到 Maven Central 后，在 Gradle 项目中添加仓库和组件依赖：

```kotlin
repositories {
    mavenCentral()
}

dependencies {
    implementation("xyz.labmem.compose:nativeui:0.4.0")
    implementation("xyz.labmem.compose:nativeui-debug:0.4.0") // 可选：Inspector 与 DevTools
    implementation("xyz.labmem.compose:nativexicons:0.4.0") // 可选：xicons 资源
    implementation("xyz.labmem.compose:nativetwemoji:0.4.0") // 可选：Twemoji 资源
}
```

Desktop source set 如需 NativeUI 无边框窗口，再单独添加：

```kotlin
kotlin {
    sourceSets.desktopMain.dependencies {
        implementation("xyz.labmem.compose:nativeui-desktop-window:0.4.0")
    }
}
```

在本仓库内开发 demo 或组件时，也可以继续使用 `implementation(project(":nativeui"))`。

`nativeui`、`nativeui-debug`、`nativexicons` 和 `nativetwemoji` 都配置为独立的 Kotlin Multiplatform 发布坐标，并已在 Maven Local 验证。Compose Desktop、Android 与 Web/Wasm 项目依赖根坐标即可，Gradle 会自动选择对应平台变体；不要在普通应用中直接依赖 `*-desktop` 变体。`nativeui-desktop-window` 是独立 JVM/Desktop artifact，只能放在 Desktop source set。

资源包平台说明：

| 模块 | Desktop | Android | Web/Wasm |
| --- | --- | --- | --- |
| `nativeui` | 完整参考目标。 | common 组件可编译，Android demo 可打包；图片加载、轻量预览和下载可通过 Android bridge 接入，外链、系统通知与 Upload 文件选择也走 Android bridge；Upload 默认打开支持 `content://` 与 http(s)，默认保存可把 `content://`、`file:` 和本地路径写入 Downloads/NativeUI，平台原生取色、图片分享、精细阴影等宿主能力仍存在降级。 | common 组件可编译，Wasm demo 可生成分发包；图片位图通过浏览器 fetch/decode 加载，SVG 通过 Skiko 栅格化，图片轻量预览可用；ColorPicker 预览块可调用浏览器原生取色器，Upload 可使用浏览器 input 选择文件，默认保存触发浏览器下载，默认打开会新开标签。 |
| `nativeui-debug` | Inspector、边界高亮和 DevTools 可用。 | 同一公共协议和 DevTools；触摸选择使用 Compose pointer input。 | 同一公共协议和 DevTools；不会替代浏览器开发者工具。 |
| `nativeui-desktop-window` | 无边框窗口、标题栏、控制按钮和边缘 resize；系统 snap、阴影和 Wayland 行为由窗口管理器决定。 | 不适用。 | 不适用。 |
| `nativexicons` | 打包 SVG registry 与 painter 完整可用。 | 打包 SVG registry 可用；painter 通过 AndroidSVG 异步栅格化，首次组合可能短暂为空。 | 打包 SVG registry 可用；painter 通过 Compose resources 读取 bundle，并用 Skiko SVGDOM 异步渲染。 |
| `nativetwemoji` | 打包 Twemoji SVG registry 与 painter 完整可用。 | 打包 Twemoji registry 可用；painter 通过 AndroidSVG 异步栅格化，首次组合可能短暂为空。 | 打包 Twemoji registry 可用；painter 通过 Compose resources 读取 bundle，并用 Skiko SVGDOM 异步渲染。 |

应用入口建议包一层 `NativeTheme` 或 `NativeConfigProvider`：

```kotlin
import xyz.labmem.compose.nativeui.components.NativeButton
import xyz.labmem.compose.nativeui.components.NativeButtonType
import xyz.labmem.compose.nativeui.theme.NativeTheme

NativeTheme {
    NativeButton(
        text = "保存",
        type = NativeButtonType.Primary,
        onClick = { /* save */ },
    )
}
```

读取当前组件版本：

```kotlin
import xyz.labmem.compose.nativeui.core.NativeUiVersion

println(NativeUiVersion.DISPLAY_VERSION) // v0.4
```

## 文档

启动 Desktop demo：

```bash
bash ./gradlew :desktopDemo:run --console plain
```

启动 Web demo：

```bash
bash ./gradlew :webDemo:wasmJsBrowserDevelopmentRun --console plain --no-configuration-cache
```

构建或安装 Android demo：

```bash
bash ./gradlew :androidDemo:assembleDebug --console plain
bash ./gradlew :androidDemo:installDebug --console plain
```

Android Debug APK 输出到 `androidDemo/build/outputs/apk/debug/androidDemo-debug.apk`。

打包 Desktop demo 安装包：

```bash
bash ./gradlew :desktopDemo:packageDistributionForCurrentOS --console plain
```

Compose Desktop 原生安装包需要在对应系统上构建：Linux 生成 `.deb`，Windows 生成 `.msi`，macOS 生成 `.dmg`。支持 RPM 的 Linux 环境可以额外传入 `-PnativeuiDemoEnableRpm=true` 生成 `.rpm`。

生成 `nativeui` 的 Dokka API 文档（HTML 与 GitHub Flavored Markdown）：

```bash
bash ./gradlew :nativeui:dokkaGenerate --console plain
```

只生成适合放到 GitHub 仓库中直接浏览的 Markdown 文档：

```bash
bash ./gradlew :nativeui:dokkaGeneratePublicationGfm --console plain
```

输出位置：

```text
nativeui/build/dokka/html/index.html
nativeui/build/dokka/gfm/index.md
```

发布 Markdown 时请复制或提交整个 `nativeui/build/dokka/gfm/` 目录，目录内页面使用相对链接，不能只上传 `index.md`。

## 给 AI 使用的文档

下游项目如果希望让 AI 准确使用 NativeUI，请优先把 [docs/AI_USAGE_GUIDE.md](docs/AI_USAGE_GUIDE.md) 提供给 AI。它是机器可读的上手指南，集中说明了导入方式、主题、状态模式、controller API、弹层/滚动/路由规则和 Compose 与浏览器语义差异。