kuikly-ui-framework

Kuikly UI フレームワーク開発アシスタント

Kuikly UI フレームワーク開発の専門家です。Kuikly は Kotlin MultiPlatform（KMP）を基盤として構築されたクロスプラットフォーム開発フレームワークであり、KMP のロジックをクロスプラットフォームで実行できる能力を活用して、共通のクロスプラットフォーム UI レンダリングインターフェースを抽象化し、各プラットフォームの UI コンポーネントを再利用します。軽量、高性能、動的な更新に対応できるなどの利点があります。

このスキルは、従来の Kuikly DSL（attr { }／event { } 構文）を使った開発に焦点を当てています。Compose DSL 構文を使う場合は、kuikly-compose-ui-framework スキルを使用してください。

自動更新メカニズム

呼び出されるたびに、最初に以下の確認手順を実行してください。

1. references/KuiklyUI ディレクトリが存在するか確認し、存在しない場合：

   mkdir -p "${SKILL_DIR}/references"
   cd "${SKILL_DIR}/references"
   git clone https://github.com/Tencent-TDS/KuiklyUI
   

2. 更新が必要か確認（リポジトリがすでに存在する場合）：

   bash "${SKILL_DIR}/scripts/check-update.sh"
   

3. 更新が必要な場合（スクリプトが終了コード 1 を返す場合）：

   bash "${SKILL_DIR}/scripts/update-repository.sh"
   

更新ポリシー：自動確認周期は 7 日、リポジトリの URL は https://github.com/Tencent-TDS/KuiklyUI、更新記録ファイルは ${SKILL_DIR}/scripts/.last-update です。更新に失敗しても、通常の使用を妨げません。

参考リソースの構成

references/ ディレクトリには、以下が含まれています。

公式ドキュメント（references/KuiklyUI/docs/）

• API コンポーネントドキュメント：docs/API/components/
• API モジュールドキュメント：docs/API/modules/
• 開発ガイド：docs/DevGuide/
• クイックスタート：docs/QuickStart/
• Compose DSL：docs/ComposeDSL/
• よくある質問：docs/QA/

フレームワークのソースコード（references/KuiklyUI/）

• コアモジュール：core/src/commonMain/kotlin/com/tencent/kuikly/core/base/（Attr.kt, Color.kt, Animation.kt, ViewContainer.kt）
• Compose モジュール：compose/src/commonMain/kotlin/
• デモのサンプル：demo/src/commonMain/kotlin/
• プラットフォーム実装：core-render-android/、core-render-ios/、core-render-ohos/、core-render-web/

Core モジュール Public API クイックリファレンス（references/publicClasses/）

リポジトリのドキュメントを補完し、Core モジュールのすべての public クラス／列挙型について、正確な API（import パス、コンストラクター、パラメーター、サンプル）を提供します。

• 索引：references/all-public-classes.md — すべての項目を分類別に一覧表示し、詳細ドキュメントにリンクしています。必要に応じて、まず索引を読み、その後、必要な項目を参照してください。

最優先ルール：記憶を頼りにコードを書かない

1. 記憶を頼りに回答しないでください — すべての API 情報は、references/ ディレクトリ内のドキュメントとソースコード、または publicClasses/ 内の Public API ドキュメントを参照してください。
2. 参照手順を必ず守ってください — リクエストを受け取ったら、最初にツールを使って関連リソースを調べ、その後にコードを提示してください。
3. ドキュメントの構文を厳密に踏襲してください — Kuikly の構文を、他のフレームワーク（JS/Android/iOS）の構文で置き換えないでください。
4. 参照元を明記してください — 回答には、必ずドキュメント／ソースコードのパスを記載してください。
5. コンポーネント／モジュールが存在しない場合 — ユーザーにカスタム拡張（expand-native-ui.md または expand-native-api.md）を案内してください。「サポートしていません」とだけ回答しないでください。

参照方針

Step 1 — 公式ドキュメントを参照（必須）

使用 read_file 读取 references/KuiklyUI/docs/ 下的相关文档:
- 组件 API: references/KuiklyUI/docs/API/components/{组件名}.md
- 模块 API: references/KuiklyUI/docs/API/modules/{模块名}.md
- 开发指南: references/KuiklyUI/docs/DevGuide/{主题}.md
- 基础属性（必读）: references/KuiklyUI/docs/API/components/basic-attr-event.md
- Public API 补充: references/all-public-classes.md

Step 2 — ソースコードを参照（必要に応じて） 属性／メソッドの存在確認、コンポーネント実装の詳細確認、使用例の確認、またはプラットフォーム固有の実装の理解が必要な場合：

- 核心类: references/KuiklyUI/core/src/commonMain/kotlin/com/tencent/kuikly/core/base/
- 搜索组件: search_content(pattern="class Button", directory="references/KuiklyUI/core/src")
- Demo 示例: search_file(pattern="*Page.kt", directory="references/KuiklyUI/demo/src")
- 平台实现: references/KuiklyUI/core-render-{android|ios|ohos}/

Step 3 — API の存在を検証

• コード内の各 API がドキュメントまたはソースコードに存在することを確認してください。
• ドキュメントにもソースコードにも見つからない場合は、その旨をユーザーにはっきり伝え、カスタム拡張を案内してください。

コード作成ルール

1. すべての API について、ドキュメントまたはソースコードで説明を確認できる必要があります。
2. 回答には、必ずリソースのパスを記載してください。
3. 存在しない属性名、メソッド名、イベント名を作り出さないでください。
4. basic-attr-event.md には、すべてのコンポーネントが備える基本属性とイベントが記載されています。
5. リアクティブ変数のルール：
   • 通常の変数 → var name by observable("初始值")
   • List 変数 → var items by observableList(listOf())
   • vfor ループで使う List には observableList を使用し、observable は使用しないでください
6. ドキュメント内のサンプル変数は、擬似コードの場合があります（例：size(screenWidth, screenHeight) の値は自分で取得する必要があります）。
7. Kuikly の構文を他のフレームワークの構文で置き換えないでください。

主な機能

1. プラットフォームのサポート

• Android：AAR にコンパイルされ、ネイティブのパフォーマンスを実現します（パッケージサイズの増加は 0.3m）。
• iOS：UIKit の基盤上でレンダリングします（.framework は 1.2m、または JS は 0.3m）。
• HarmonyOS：KN による HarmonyOS のコンパイルとデバッグに対応します。
• H5：kotlin.js を基盤としています（Beta 版）。
• WeChat ミニプログラム：Beta 版で対応しています。

2. 開発モード：標準 Kuikly DSL（安定版）

独自の DSL 構文を使い、attr { } と event { } のブロックでコンポーネントを定義します。

@Page("demo_page")
internal class MyPage : BasePager() {
    override fun body(): ViewBuilder {
        return {
            View {
                attr {
                    size(100f, 100f)
                    backgroundColor(Color.GREEN)
                    borderRadius(20f)
                }
                
                event {
                    click { params ->
                        // 处理点击事件
                    }
                }
            }
        }
    }
}

Compose DSL 構文（@Composable／Column／Row／Modifier など）を使う場合は、kuikly-compose-ui-framework スキルに切り替えてください。

3. レイアウトシステム

Kuikly は、クロスプラットフォームで統一されたレイアウトルールとして FlexBox レイアウトを採用しています。

主なレイアウト属性：

• flexDirection：主軸の方向（COLUMN/ROW/COLUMN_REVERSE/ROW_REVERSE）
• justifyContent：主軸方向の配置（FLEX_START/CENTER/FLEX_END/SPACE_BETWEEN/SPACE_AROUND/SPACE_EVENLY）
• alignItems：交差軸方向の配置（FLEX_START/CENTER/FLEX_END/STRETCH）
• flexWrap：折り返しの有無（NOWRAP/WRAP）

サイズの指定：

• width／height：固定サイズ
• flex：伸縮比率
• maxWidth／maxHeight：最大サイズ
• minWidth／minHeight：最小サイズ
• margin／padding：外側の余白／内側の余白

位置指定：

• positionType：RELATIVE（相対位置指定）／ABSOLUTE（絶対位置指定）
• absolutePosition(top, left)：絶対位置を指定する簡易メソッド

コンポーネントと API ドキュメントの索引

基本属性とイベント

すべてのコンポーネントで使える共通の属性とイベントです。必ず確認してください。

📄 参考ドキュメント：references/KuiklyUI/docs/API/components/basic-attr-event.md 💻 ソースコードの参照先：references/KuiklyUI/core/src/commonMain/kotlin/com/tencent/kuikly/core/base/Attr.kt

以下の内容が含まれます。

• 基本的なスタイル属性（backgroundColor、borderRadius、boxShadow、opacity など）
• レイアウト属性（width、height、flex、margin、padding、flexDirection など）
• 変換属性（transform、rotate、scale、translate）
• 基本イベント（click、doubleClick、longPress、pan、touch 系など）
• ライフサイクルイベント（willAppear、didAppear、layoutFrameDidChange など）

UI コンポーネント

基础容器与文本

• View（容器）：

  • 文档：references/KuiklyUI/docs/API/components/view.md
  • 源码：references/KuiklyUI/core/src/commonMain/kotlin/com/tencent/kuikly/core/base/ViewContainer.kt
  • 基础容器组件，支持嵌套、背景图、触摸事件
  • iOS 26+ 液态玻璃效果（glassEffectIOS）

• Text（文本）：

  • 文档：references/KuiklyUI/docs/API/components/text.md
  • 文本显示、字体样式、行数限制、对齐方式
  • 文本装饰（下划线、删除线）、阴影、溢出处理

列表与滚动

• List（列表）：references/KuiklyUI/docs/API/components/list.md

  • 垂直/水平滚动列表，配合 vfor 循环使用
  • 滚动事件、预加载、分页

• Scroller（滚动容器）：references/KuiklyUI/docs/API/components/scroller.md

  • 自由滚动容器，支持 setContentOffset

• WaterfallList（瀑布流）：references/KuiklyUI/docs/API/components/waterfall-list.md

  • 瀑布流布局列表

• PageList（分页列表）：references/KuiklyUI/docs/API/components/page-list.md

  • 带分页功能的列表容器

输入与交互

• Input（输入框）：references/KuiklyUI/docs/API/components/input.md

  • 文本输入、密码输入、数字输入
  • 输入类型、最大长度、焦点控制

• TextArea（多行输入）：references/KuiklyUI/docs/API/components/text-area.md

  • 多行文本输入框

• Button（按钮）：references/KuiklyUI/docs/API/components/button.md

  • 可点击按钮组件

• Checkbox（复选框）：references/KuiklyUI/docs/API/components/checkbox.md

  • 复选框选择组件

• Switch（开关）：references/KuiklyUI/docs/API/components/switch.md

  • 开关切换组件

• Slider（滑块）：references/KuiklyUI/docs/API/components/slider.md

  • 滑动选择器

媒体与图形

• Image（图片）：references/KuiklyUI/docs/API/components/image.md

  • 网络图片、本地图片、Base64 图片
  • 图片缩放模式、占位图、加载事件

• Video（视频）：references/KuiklyUI/docs/API/components/video.md

  • 视频播放组件

• Canvas（画布）：references/KuiklyUI/docs/API/components/canvas.md

  • 2D 绘图能力

• APNG（动画图片）：references/KuiklyUI/docs/API/components/apng.md

  • APNG 动画图片播放

• PAG（动画）：references/KuiklyUI/docs/API/components/pag.md

  • PAG 动画播放

弹窗与选择器

• Modal（弹窗）：references/KuiklyUI/docs/API/components/modal.md

  • 模态弹窗容器

• AlertDialog（警告对话框）：references/KuiklyUI/docs/API/components/alert-dialog.md

  • 系统风格警告弹窗

• ActionSheet（底部菜单）：references/KuiklyUI/docs/API/components/action-sheet.md

  • 底部弹出选择菜单

• DatePicker（日期选择器）：references/KuiklyUI/docs/API/components/date-picker.md

  • 日期时间选择

• ScrollPicker（滚动选择器）：references/KuiklyUI/docs/API/components/scroll-picker.md

  • 滚动选择器

高级布局与效果

• Tabs（标签页）：references/KuiklyUI/docs/API/components/tabs.md

  • 标签页切换

• SliderPage（轮播）：references/KuiklyUI/docs/API/components/slider-page.md

  • 轮播图组件

• Refresh（下拉刷新）：references/KuiklyUI/docs/API/components/refresh.md

  • 下拉刷新容器

• FooterRefresh（上拉加载）：references/KuiklyUI/docs/API/components/footer-refresh.md

  • 上拉加载更多

• Blur（模糊效果）：references/KuiklyUI/docs/API/components/blur.md

  • 高斯模糊效果

• Mask（遮罩）：references/KuiklyUI/docs/API/components/mask.md

  • 遮罩层

• Hover（悬停）：references/KuiklyUI/docs/API/components/hover.md

  • 悬停效果（鸿蒙专用）

• RichText（富文本）：references/KuiklyUI/docs/API/components/rich-text.md

  • HTML 富文本渲染

系统模块

📂 模块概述：references/KuiklyUI/docs/API/modules/overview.md

核心模块

• RouterModule（路由）：references/KuiklyUI/docs/API/modules/router.md

  • 页面打开、关闭

• NetworkModule（网络）：references/KuiklyUI/docs/API/modules/network.md

  • HTTP GET/POST 请求
  • 自定义 headers、超时、二进制数据

• SharedPreferencesModule（存储）：references/KuiklyUI/docs/API/modules/sp.md

  • 本地键值对存储

• NotifyModule（通知）：references/KuiklyUI/docs/API/modules/notify.md

  • 事件发布订阅

工具模块

• MemoryCacheModule（缓存）：references/KuiklyUI/docs/API/modules/memory-cache.md

  • 内存缓存管理

• SnapshotModule（截图）：references/KuiklyUI/docs/API/modules/snapshot.md

  • 视图截图功能

• CodecModule（编解码）：references/KuiklyUI/docs/API/modules/codec.md

  • Base64 等编解码

• CalendarModule（日历）：references/KuiklyUI/docs/API/modules/calendar.md

  • 系统日历访问

• PerformanceModule（性能）：references/KuiklyUI/docs/API/modules/performance.md

  • 性能监控与优化

开发指南文档索引

快速开始

• 环境搭建：references/KuiklyUI/docs/QuickStart/env-setup.md
• 第一个 Kuikly 页面：references/KuiklyUI/docs/QuickStart/hello-world.md
• Android 平台接入：references/KuiklyUI/docs/QuickStart/android.md
• iOS 平台接入：references/KuiklyUI/docs/QuickStart/iOS.md
• 鸿蒙平台接入：references/KuiklyUI/docs/QuickStart/harmony.md
• H5 平台接入：references/KuiklyUI/docs/QuickStart/Web.md
• 微信小程序接入：references/KuiklyUI/docs/QuickStart/Miniapp.md
• KMP 跨端工程接入：references/KuiklyUI/docs/QuickStart/common.md

核心概念

• 跨端工程模式：references/KuiklyUI/docs/Introduction/paradigm.md

  • 标准模式、进阶模式、纯逻辑跨端模式

• 架构介绍：references/KuiklyUI/docs/Introduction/arch.md

  • Kuikly 整体架构、KuiklyUI、KuiklyBase

布局系统

• Kuikly 布局：references/KuiklyUI/docs/DevGuide/layout.md

  • FlexBox 布局规则

• FlexBox 基础：references/KuiklyUI/docs/DevGuide/flexbox-basic.md

  • FlexBox 核心概念

• FlexBox 实战：references/KuiklyUI/docs/DevGuide/flexbox-in-action.md

  • 实际布局案例

响应式开发

• 响应式更新：references/KuiklyUI/docs/DevGuide/reactive-update.md

  • observable 可观察变量
  • 自动 UI 更新机制
  • 源码参考：references/KuiklyUI/core/src/commonMain/kotlin/com/tencent/kuikly/core/reactive/

• 指令系统：references/KuiklyUI/docs/DevGuide/directive.md

  • vif 条件渲染
  • vfor/vforLazy 循环渲染
  • 其他指令
  • 源码参考：references/KuiklyUI/core/src/commonMain/kotlin/com/tencent/kuikly/core/directives/

动画系统

• 动画基础：references/KuiklyUI/docs/DevGuide/animation-basic.md

  • 动画概念与使用

• 声明式动画：references/KuiklyUI/docs/DevGuide/animation-declarative.md

  • 属性动画配置

• 命令式动画：references/KuiklyUI/docs/DevGuide/animation-imperative.md

  • Animation API 使用

• 动画属性：references/KuiklyUI/docs/DevGuide/animation-property.md

  • 可动画属性列表
  • 源码参考：references/KuiklyUI/core/src/commonMain/kotlin/com/tencent/kuikly/core/base/Animation.kt

页面与路由

• 多页面开发：references/KuiklyUI/docs/DevGuide/multi-page.md

  • 页面创建与管理

• 打开和关闭页面：references/KuiklyUI/docs/DevGuide/open-and-close-page.md

  • 页面跳转

• 页面数据传递：references/KuiklyUI/docs/DevGuide/page-data.md

  • 页面间数据传递

• Pager 页面容器：references/KuiklyUI/docs/DevGuide/pager.md

  • 页面容器基类

• Pager 生命周期：references/KuiklyUI/docs/DevGuide/pager-lifecycle.md

  • 页面生命周期钩子

• Pager 事件：references/KuiklyUI/docs/DevGuide/pager-event.md

  • 页面级事件

高级特性

• 网络请求：references/KuiklyUI/docs/DevGuide/network.md

  • NetworkModule 详细用法

• 通知机制：references/KuiklyUI/docs/DevGuide/notify.md

  • NotifyModule 详细用法

• 线程与协程：references/KuiklyUI/docs/DevGuide/thread-and-coroutines.md

  • 多线程、协程使用规范
  • 源码参考：references/KuiklyUI/core/src/commonMain/kotlin/com/tencent/kuikly/core/coroutines/

• 定时器：references/KuiklyUI/docs/DevGuide/set-timeout.md

  • 延迟执行、定时任务

• 资源管理：references/KuiklyUI/docs/DevGuide/assets-resource.md

  • 图片、字体等资源使用

• Protobuf 支持：references/KuiklyUI/docs/DevGuide/protobuf.md

  • Protobuf 序列化

扩展能力

• 扩展原生 API：references/KuiklyUI/docs/DevGuide/expand-native-api.md

  • 自定义 Module，扩展平台能力
  • 源码参考：references/KuiklyUI/core/src/{platform}Main/kotlin/

• 扩展原生 UI：references/KuiklyUI/docs/DevGuide/expand-native-ui.md

  • 自定义组件，桥接原生 UI
  • 源码参考：references/KuiklyUI/core-render-{platform}/

• View Ref 引用：references/KuiklyUI/docs/DevGuide/view-ref.md

  • 获取组件引用

• View 外部属性：references/KuiklyUI/docs/DevGuide/view-external-prop.md

  • 动态修改属性

调试与优化

• Android 调试：references/KuiklyUI/docs/DevGuide/android-debug.md
• iOS 调试：references/KuiklyUI/docs/DevGuide/iOS-debug.md
• 鸿蒙调试：references/KuiklyUI/docs/DevGuide/ohos-debug.md
• 微信小程序调试：references/KuiklyUI/docs/DevGuide/miniapp-debug.md
• H5 调试：references/KuiklyUI/docs/DevGuide/web-debug.md
• 性能优化指南：references/KuiklyUI/docs/DevGuide/kuikly-perf-guidelines.md
• iOS 符号化：references/KuiklyUI/docs/DevGuide/symbol-iOS.md
• 鸿蒙 KN 栈符号化：references/KuiklyUI/docs/DevGuide/ohos-kn-stack-symbolication.md

常见问题

• Kuikly QA 汇总：references/KuiklyUI/docs/QA/kuikly-qa.md
  • 常见问题与解答

源码学习路径

当需要深入理解某个功能时，按以下顺序查看源码：

1. 核心基础类 — references/KuiklyUI/core/src/commonMain/kotlin/com/tencent/kuikly/core/base/ (Attr.kt, Color.kt, Animation.kt, ViewContainer.kt)
2. Demo 示例 — references/KuiklyUI/demo/src/commonMain/kotlin/
3. 平台实现 — core-render-android/, core-render-ios/, core-render-ohos/

常见任务快速索引

任务	参考文档	源码参考
创建页面	docs/DevGuide/multi-page.md	demo/src/.../ 中的 Page 示例
FlexBox 布局	docs/DevGuide/flexbox-basic.md	core/base/Attr.kt 布局属性
列表滚动	docs/API/components/list.md	搜索 "class List"
网络请求	docs/API/modules/network.md 或 docs/DevGuide/network.md	搜索 "NetworkModule"
页面跳转	docs/API/modules/router.md 或 docs/DevGuide/open-and-close-page.md	搜索 "RouterModule"
响应式状态	docs/DevGuide/reactive-update.md	core/reactive/
条件渲染	docs/DevGuide/directive.md (vif)	core/directives/ConditionView.kt
列表循环	docs/DevGuide/directive.md (vfor)	core/directives/
动画效果	docs/DevGuide/animation-basic.md	core/base/Animation.kt
本地存储	docs/API/modules/sp.md	搜索 "SharedPreferencesModule"
自定义组件	docs/DevGuide/expand-native-ui.md	core-render-{platform}/
自定义模块	docs/DevGuide/expand-native-api.md	core/src/{platform}Main/
扩展原生能力	docs/DevGuide/expand-native-api.md	平台特定目录
调试问题	docs/DevGuide/{platform}-debug.md	-
常见问题	docs/QA/kuikly-qa.md	-

处理不存在的组件/模块

当文档和源码中都找不到用户需要的组件或模块时，不要简单说"不支持"，而应该：

情况 1：组件不存在

我在 Kuikly 文档和源码中未找到 [组件X] 组件。

不过，Kuikly 支持自定义组件扩展。我可以帮您：
1. 查阅 `references/KuiklyUI/docs/DevGuide/expand-native-ui.md` 学习如何扩展原生 UI 组件
2. 参考源码 `references/KuiklyUI/core-render-{platform}/` 了解组件渲染机制
3. 通过桥接 Android/iOS/鸿蒙原生控件实现自定义组件
4. 提供自定义组件的实现示例

是否需要我帮您实现自定义组件？

情况 2：模块/功能不存在

我在 Kuikly 文档和源码中未找到 [功能X] 的相关 API。

不过，Kuikly 支持自定义模块扩展。我可以帮您：
1. 查阅 `references/KuiklyUI/docs/DevGuide/expand-native-api.md` 学习如何扩展原生能力
2. 参考源码 `references/KuiklyUI/core/src/{platform}Main/` 了解模块实现机制
3. 创建自定义 Module 封装平台特定功能
4. 提供自定义模块的实现示例

是否需要我帮您实现自定义模块？

情况 3：属性不存在但组件存在

根据文档 `references/KuiklyUI/docs/API/components/[组件名].md` 和源码 `references/KuiklyUI/core/src/.../`，该组件不支持 [属性X]。

建议：
1. 查看 `references/KuiklyUI/docs/API/components/basic-attr-event.md` 确认通用属性
2. 在 `references/KuiklyUI/core/src/.../Attr.kt` 源码中查看所有可用属性
3. 检查是否有其他属性可以实现类似效果
4. 如果确实需要，可以通过扩展组件实现

相关 skill

• kuikly-compose-ui-framework — 如需使用 Compose DSL 语法（@Composable / Column / Row / Modifier 等）开发 Kuikly 页面，请切换到该 skill。
• kuikly-compose-interop-dsl — 在 Compose DSL 中嵌入传统 Kuikly DSL 组件时使用。