tencent-tds/kuiklyui-ai

kuikly-coroutines-threading

Kuikly 协程与多线程编程助手。指导如何在 Kuikly 中进行异步编程,包括 Kuikly 内建协程、kotlinx 协程、kuiklyx 协程库。当用户在 Kuikly 中需要执行异步任务、切换线程、使用协程、回到 Kuikly 线程更新 UI、排查线程安全问题时使用。

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/tencent-tds/kuiklyui-ai --skill kuikly-coroutines-threading

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

Kuikly 协程与多线程编程

核心规则

  • Kuikly 线程约束:所有 Kuikly UI 操作(View、Attr、Event、observable、Module 方法、setTimeout 等)只能在 Kuikly 线程调用,Kuikly UI 相关类非线程安全。
  • 异步任务完成后必须回到 Kuikly 线程才能更新 UI 或访问响应式属性。
  • 动态化场景不支持 kotlinx 协程(js 目标平台不支持多线程),只能使用 Module 机制或 Kuikly 内建协程。

协程实现方式对比

特性回调(无协程)Kuikly 内建协程kotlinx 协程
动态化支持✅ 支持✅ 支持❌ 不支持
依赖库包增量无无kotlinx 协程库
线程安全不涉及自动保障需要考虑

三种协程 API

1. Kuikly 内建协程(推荐用于简单异步)

框架自带,始终在 Kuikly 线程执行,无线程切换开销,支持动态化。

API 入口:

  • GlobalScope.launch { ... } — 全局作用域
  • lifecycleScope.launch { ... } — 绑定 Pager 生命周期(推荐)
  • async { ... } / await() — 并发获取结果

import:

kotlin
import com.tencent.kuikly.core.coroutines.GlobalScope
import com.tencent.kuikly.core.coroutines.launch
import com.tencent.kuikly.core.coroutines.async
import com.tencent.kuikly.core.coroutines.delay

注意: Kuikly 内建协程 API 本身非线程安全,不能在 Kuikly 线程外调用。

2. kotlinx.coroutines 库

Kotlin 官方协程库,支持多线程调度器(Dispatchers.Default/IO/Main 等),不支持动态化。

接入方式:

gradle
// iOS & Android
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:$KOTLINX_COROUTINES_VERSION")
// 鸿蒙
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:$KOTLINX_COROUTINES_OHOS_VERSION")

3. kuiklyx.coroutines 库(切换到 Kuikly 线程)

提供 Dispatchers.Kuikly 调度器和 KuiklyContextScheduler 回调 API,用于从非 Kuikly 线程切回 Kuikly 线程。

接入方式:

gradle
// iOS & Android
implementation("com.tencent.kuiklyx:coroutines:$KUIKLYX_COROUTINES_VERSION")
// 鸿蒙
implementation("com.tencent.kuiklyx:coroutines:$KUIKLYX_COROUTINES_OHOS_VERSION")

协程方式 API:

kotlin
// 启动协程,在 Kuikly 线程执行
GlobalScope.launch(Dispatchers.Kuikly[ctx]) { ... }
// 在协程中切换到 Kuikly 线程
withContext(Dispatchers.Kuikly[ctx]) { ... }

回调方式 API:

kotlin
KuiklyContextScheduler.runOnKuiklyThread(pagerId) { cancel ->
    if (cancel) return  // pager 已销毁
    // 在 Kuikly 线程执行
}

场景选择决策树

根据需求选择合适的异步编程方式:

需要异步编程?
├── 只需简化回调,无多线程诉求?
│   └── → 方式1:Kuikly 内建协程
├── 需要执行耗时任务 + 支持动态化?
│   └── → 方式2:Module 机制(可配合内建协程)
├── 需要多线程 + 不需要动态化?
│   └── → 方式3:kotlinx 协程 + kuiklyx 协程
└── Compose DSL 页面?
    └── → 方式4:LaunchedEffect + withContext
⚠️ 一致性原则:选择方案时,还需关注当前项目或模块中已有的异步编程方式,应优先保持一致,避免在同一模块中混用多套异步方案。

详细场景示例和代码:见 SCENARIOS.md


Compose DSL 中的协程

Compose DSL 页面(继承 ComposeContainer)使用 kotlinx 协程体系:

kotlin
@Composable
fun MyContent() {
    var data by remember { mutableStateOf("") }
    LaunchedEffect(Unit) {
        // 默认在 Kuikly 线程执行(ComposeDispatcher)
        val result = withContext(Dispatchers.IO) {
            // 在 IO 线程执行耗时任务
            fetchData()
        }
        // 自动回到 Kuikly 线程
        data = result
    }
    Text(text = data)
}

关键点:

  • LaunchedEffect 默认运行在 Kuikly 线程(通过 ComposeDispatcher 调度)
  • 使用 withContext(Dispatchers.IO) 切换到 IO 线程执行耗时任务
  • withContext 返回后自动回到 Kuikly 线程
  • viewModelScope 也绑定到 Kuikly 线程,ViewModel 销毁时自动取消

Dispatchers.IO 跨平台定义:

kotlin
// commonMain 中声明 expect
internal expect val Dispatchers.IO: CoroutineDispatcher

// androidMain / appleMain / ohosArm64Main
internal actual val Dispatchers.IO: CoroutineDispatcher
    get() = Dispatchers.IO  // 使用平台原生 IO 调度器

// jsMain(不支持多线程)
internal actual val Dispatchers.IO: CoroutineDispatcher
    get() = Dispatchers.Default

线程安全

线程安全规则

  • Kuikly UI 相关类(View、Attr、Event、ObservableProperties、GlobalFunctions、Module 方法、Layout 等)非线程安全,只能在 Kuikly 线程访问

线程安全验证机制

详细用法和示例:见 THREAD_SAFETY.md

kotlin
override fun willInit() {
    super.willInit()
    Pager.VERIFY_THREAD = true              // 开启线程校验
    Pager.VERIFY_REACTIVE_OBSERVER = true   // 开启 observable 校验
    Pager.verifyFailed { exception ->       // 自定义验证失败处理
        println("线程安全验证失败: ${exception.message}")
        throw exception
    }
}

常见陷阱与正确做法

❌ 错误做法✅ 正确做法
在非 Kuikly 线程直接更新 observable通过 Dispatchers.Kuikly 或 KuiklyContextScheduler 切回 Kuikly 线程
在非 Kuikly 线程调用 Module 方法Module 的 acquireModule / toNative 等方法需在 Kuikly 线程调用
在动态化场景使用 kotlinx 协程使用 Kuikly 内建协程或 Module 机制
在 Kuikly 线程外调用内建协程 API内建协程 API 只能在 Kuikly 线程调用
忘记处理 Pager 销毁后的回调KuiklyContextScheduler 回调检查 cancel 参数
在 verifyFailed 回调中操作 UI验证失败通常发生在非 Kuikly 线程,不能调用 UI API
Compose 中在 IO 线程更新 State使用 withContext 回到默认调度器后再更新 State

来自同一仓库

更多 Skills

全部 Skills
tencent-tds
社区

kuikly-animation

Kuikly DSL 动画开发助手(Kuikly DSL)。指导使用声明式和命令式两种方式实现 transform、opacity、backgroundColor、frame 等属性动画,涵盖串行/并行编排与动画取消。当用户需要实现动画效果时使用。

1小时安装量
1
GitHub Stars
137
最近更新
8月10日
tencent-tds
社区

kuikly-compose-interop-dsl

Compose DSL 混用 Kuikly DSL 完整开发助手。指导如何在 Compose DSL 页面中嵌入 Kuikly DSL 组件(DeclarativeBaseView / ViewContainer)及在 Compose 中调用 Kuikly Module。当用户需要在 Compose 页面中复用 Kuikly DSL 组件、封装原生 View 为 Composable、在 Compose 中调用 Kuikly Module时使用。

1小时安装量
1
GitHub Stars
137
最近更新
8月10日
tencent-tds
社区

kuikly-expand-api

Kuikly 自定义 Module 开发助手。指导如何创建自定义 Module,扩展原声API。覆盖完整开发流程:Kuikly 侧 Module 定义、Pager/ComposeContainer 注册、各平台 Native 侧实现、Module 注册,及使用。当用户需要自定义 Module、扩展原生 API、实现 Kuikly 与 Native 双向通信、在各平台实现 Module 的 Native 侧逻辑时使用。

1小时安装量
1
GitHub Stars
137
最近更新
8月10日
tencent-tds
社区

kuikly-expand-view

Kuikly 自定义 View 开发助手。指导如何创建自定义 UI 组件,将原生 View 暴露给 Kuikly 侧使用。覆盖完整开发流程:Kuikly 侧组件定义、各平台 Native 侧实现(Android/iOS/鸿蒙ArkTS/H5/小程序)及使用。当用户需要自定义扩展 UI 组件时使用。

1小时安装量
1
GitHub Stars
137
最近更新
8月10日