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 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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

모든 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일