更新记录

0.1.0（2026-06-30） 下载此版本

• 初始版本发布
• 提供 runBackground、runQueue、runMain 三个基础调度 API
• 支持 Android、iOS、Harmony 三端
• Android 使用 Kotlin 混编实现后台线程、串行队列和主线程回切
• iOS 使用 Swift 混编实现后台线程、串行队列和主线程回切
• Harmony 提供轻量异步回调兼容实现
• 内置 pages/demo/demo.uvue 示例页面用于功能验证与展示

平台兼容性

uni-app x(5.14)

其他

uninext-worker

最小线程管理插件，提供 后台线程、串行队列、主线程 三种执行入口。

适合在 uni-app x 项目里把 socket、协议解析、数据组装这类重活放到后台或串行队列，再在最终更新页面时切回主线程。

插件信息

• 插件类型：UTS API 插件
• 支持平台：Android、iOS、Harmony（uni-app x）
• 当前版本：0.1.0
• 许可协议：MIT
• Harmony 说明：不提供真实多线程，使用轻量异步回调与串行队列兼容实现

特性

• 支持 Android、iOS、Harmony
• API 极简，只保留 3 个方法
• Android / iOS 使用原生混编
• Harmony 不引入复杂线程模型，使用最小异步实现

API

useUninextWorker()

获取 worker 实例。

import { useUninextWorker } from '@/uni_modules/uninext-worker'

const worker = useUninextWorker()

runBackground(task)

在后台执行任务。

• Android：新建后台线程执行
• iOS：DispatchQueue.global 执行
• Harmony：setTimeout(..., 0) 异步执行

worker.runBackground(() => {
  console.log('background task')
})

runQueue(task)

在串行队列中执行任务，适合需要保证顺序的场景。

• Android：单线程 Executor
• iOS：串行 DispatchQueue
• Harmony：最小串行任务队列

worker.runQueue(() => {
  console.log('queue task 1')
})

worker.runQueue(() => {
  console.log('queue task 2')
})

runMain(task)

切回主线程执行任务，适合页面状态更新、uni.showToast、uni.navigateTo 这类 UI 操作。

• Android：Handler(Looper.getMainLooper())
• iOS：DispatchQueue.main
• Harmony：直接执行

worker.runMain(() => {
  console.log('main task')
})

Demo

插件内已内置示例页面：pages/demo/demo.uvue

• 导入到宿主工程后，HBuilderX 会根据 pages_init.json:1 提示是否合并路由
• 合并后可直接打开 uni_modules/uninext-worker/pages/demo/demo
• 示例页包含 3 个按钮，分别验证后台任务、串行任务、主线程回切

如果未自动合并页面，也可以手动在宿主工程 pages.json 中加入：

{
  "pages": [
    {
      "path": "uni_modules/uninext-worker/pages/demo/demo",
      "style": {
        "navigationBarTitleText": "Uninext Worker Demo"
      }
    }
  ]
}

推荐用法

1. service 层做线程切换

建议把线程边界统一放在 service 层：

• socket 插件层：只负责收发
• service 层：决定任务跑后台、串行还是主线程
• page 层：只消费结果

import { useUninextWorker } from '@/uni_modules/uninext-worker'

const worker = useUninextWorker()

function parseVehicleMessage(buffer : ArrayBuffer, done : (result : string) => void) : void {
  worker.runBackground(() => {
    const length = buffer.byteLength
    const text = 'message length: ' + length
    worker.runMain(() => {
      done(text)
    })
  })
}

2. 串行执行 TCP / DoIP 解析

如果你的任务必须按顺序执行，建议用 runQueue：

import { useUninextWorker } from '@/uni_modules/uninext-worker'

const worker = useUninextWorker()

function handleDiagnosticTask(taskName : string) : void {
  worker.runQueue(() => {
    console.log('start:', taskName)
    worker.runMain(() => {
      console.log('finish:', taskName)
    })
  })
}

3. 适合放到后台的逻辑

• socket 收包后的协议解析
• 十六进制字符串转换
• 正则匹配
• 粘包拆包
• 数据聚合
• 非 UI 的日志整理

4. 适合切回主线程的逻辑

• 页面响应式状态更新
• onProgress 回调到页面
• uni.showToast
• uni.navigateTo
• uni.reLaunch
• 其他直接触发 UI 的调用

使用建议

• 不要在 runMain 里做大计算
• 不要每条消息都频繁回主线程更新 UI
• 多条消息可以先在后台聚合，再一次性 runMain
• 需要严格顺序时优先使用 runQueue

目录结构

uninext-worker/
├─package.json
├─README.md
└─utssdk/
  ├─interface.uts
  ├─unierror.uts
  ├─app-android/
  │ ├─index.uts
  │ └─UninextWorkerNative.kt
  ├─app-ios/
  │ ├─index.uts
  │ └─UninextWorkerNative.swift
  └─app-harmony/
    └─index.uts

当前版本

当前版本提供最小能力，不包含：

• 任务取消
• 返回值封装
• 线程池大小配置
• 延迟任务
• 定时任务

如果后续你要把它继续扩展成通用调度器，可以在此基础上再加任务 ID、取消、结果回调和错误回调。