# silkui_cj

**Repository Path**: tianbin0912/silkui_cj

## Basic Information

- **Project Name**: silkui_cj
- **Description**: 仓颉语言，arkts通用组件库
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-11-15
- **Last Updated**: 2026-03-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

### 介绍

SilkUI 是一个面向 HarmonyOS NEXT 仓颉（Cangjie）的移动端组件库，参考 Vant 的设计理念，提供轻量、可靠、易拓展的 UI 组件，帮助你快速构建高质量应用界面。

### 特性

- 参考 Vant 的交互与视觉规范，统一 API 设计
- 基于仓颉语言开发，契合 HarmonyOS NEXT 组件模型
- 支持主题定制与按需组合能力
- 提供示例 App（`entry` 模块）与文档站（`docs-vue`）

### 目录结构

```text
cangjieSilkui/
├─ entry/                               # 示例应用（演示各组件用法）
│  └─ src/main/cangjie/src/
│     ├─ pages/                         # 示例页面（button、cell、toast 等）
│     ├─ components/                    # 示例通用组件（导航、标题等）
│     └─ index.cj                       # 示例首页与路由入口
├─ libs/
│  └─ silkui/                           # 组件库主体模块
│     └─ src/main/cangjie/src/
│        ├─ components/                 # 具体组件实现
│        │  ├─ action_sheet/
│        │  ├─ badge/
│        │  ├─ button/
│        │  ├─ calendar/
│        │  ├─ cell/
│        │  ├─ collapse/
│        │  ├─ dialog/
│        │  ├─ highlight/
│        │  ├─ icon/
│        │  ├─ image/
│        │  ├─ loading/
│        │  ├─ picker/
│        │  ├─ popup/
│        │  ├─ rate/
│        │  └─ toast/
│        ├─ constants/                  # 组件常量（配色、尺寸等）
│        ├─ utils/                      # 工具方法（动画、日志、曲线等）
│        ├─ types/                      # 公共类型定义
│        └─ index.cj                    # 公共能力导出（边框/内边距/渐变等）
├─ docs-vue/                            # 文档站（基于 Vite + Vue）
│  └─ src/                              # 组件文档与演示配置
├─ AppScope/、entry/resources、libs/silkui/resources 等 # 工程资源
└─ hvigorfile.ts、oh-package.json5 等             # 构建与依赖配置
```

### 组件一览

- ActionSheet、Badge、Button、Calendar、Cell、Collapse
- Dialog、Highlight、Icon、Image、Loading
- Picker、Popup、Rate、Toast

> 后续将持续补充更多组件，保持与移动端常见场景对齐。

### 公共类型能力

库内提供了常用 UI 能力的数据结构，便于在组件与业务中复用：

- `SilkUIBorderOptions`：边框宽度、颜色、样式
- `SilkUIPaddingOptions`：统一或分别设置上下左右内边距
- `SilkUILinearGradientOptions`：线性渐变的角度、颜色组与方向
- `SilkUIBorderRadiuses`：四角圆角半径

### 快速开始

#### 环境准备

- DevEco Studio（HarmonyOS NEXT 开发环境）
- HarmonyOS NEXT SDK 与 Cangjie Toolchain

#### 运行示例 App（推荐）

1. 使用 DevEco Studio 打开工程根目录 `cangjieSilkui`
2. 选择运行模块为 `entry`
3. 直接运行到模拟器或真机，首页可进入各组件演示页面

#### 在你的工程中使用组件库

1. 将 `libs/silkui` 作为本地模块引入到你的工程（在 DevEco Studio 中添加模块依赖）
2. 在页面中按需引入组件并使用

示例（以按钮为例）：

```cangjie
import silkui.components.button.SilkButton
import silkui.components.button.SilkButtonOptions
import silkui.components.button.SilkButtonType

@Entry
@Component
class DemoView {
  func build() {
    Column() {
      SilkButton(
        props: SilkButtonOptions(
          buttonType: SilkButtonType.PRIMARY,
          text: "主要按钮"
        )
      )
    }.width(100.percent).height(100.percent)
  }
}
```

更多示例可参考 `entry/src/main/cangjie/src/pages/` 目录下各页面（如 `button.cj`）。

### 主题定制

- 通过组件 `props` 设置颜色、大小、圆角、渐变等（如 `SilkButtonOptions.color`、`linearGradient`）
- 通过资源覆盖调整主题：
  - 参考 `libs/silkui/src/main/resources/base/element/color.json`、`float.json`
  - 在业务 `AppScope` 或模块资源中提供自定义 `@r(app.color.xxx)` 即可全局替换

### 文档站

文档站位于 `docs-vue`：

```bash
cd docs-vue
npm install
npm run dev
# 浏览器访问控制台输出的本地地址
```

### 约束与兼容

- 面向 HarmonyOS NEXT 与 Cangjie 语法
- 推荐用法：可选内容使用 `Option` 处理构建器与可选 UI 片段（见库内部分组件用法）

### 贡献

欢迎通过 Issue 与 PR 参与共建。代码风格与语法注意：

- 优先使用 `Option<(CustomView) -> ViewBuilder>` 接收可选 UI 构建器，使用 `isSome/getOrThrow` 判断与取值 [[memory:4016026]]

### 开源协议

本项目采用 Apache-2.0 许可证，详见根目录 `LICENSE`。