更新记录

1.0.0（2026-08-28）

• 支持 Android / iOS / HarmonyOS NEXT 三端设备端本地目标检测，图片不出端
• 基于 ONNX Runtime 1.18.0（Android / iOS）与 MindSpore Lite（HarmonyOS NEXT）推理
• 兼容 YOLO11n / YOLOv8n 模型（模型文件由使用方提供，非插件内置），支持基于 YOLO11n / YOLOv8n 架构训练的自定义模型
• 提供 initModel / detect / releaseModel 三个核心 API
• 支持配置输入尺寸、CPU 线程数、GPU/NNAPI 硬件加速
• 支持自定义置信度阈值与 NMS IoU 阈值
• 内置 COCO 80 类标签，未传 labels 时按输出通道数自动匹配
• 动态解析 YOLO 标准输出张量 [1, 4 + C, N]，坐标自动还原至原图尺寸
• 统一跨平台错误码与错误消息（JonYoloError）

平台兼容性

uni-app(3.8.2)

jon-yolo

YOLO 目标检测 UTS 插件，基于 ONNX Runtime（Android / iOS）与 MindSpore Lite（HarmonyOS NEXT）实现设备端本地推理，兼容 YOLO11n / YOLOv8n 模型。模型文件由使用方提供（非插件内置），插件负责加载与推理，无需联网。

特性

• 三端覆盖：Android、iOS、HarmonyOS NEXT 一套代码调用，均为设备端本地推理，图片不出端
• 模型外置：插件不内置模型，模型文件由使用方提供，放入工程即可运行
• 标准 YOLO 输出解析：支持动态输出张量 [1, 4 + C, N] 解析，自动适配 80 类（COCO）及自定义类别
• 内置后处理：置信度阈值过滤 + 同类目标 NMS（非极大值抑制），坐标自动还原到原图像素尺寸
• 参数可调：输入尺寸、CPU 线程数、GPU/NNAPI 硬件加速、置信度阈值、IoU 阈值均可配置
• 统一错误体系：跨平台统一错误码与错误消息（JonYoloError）
• 资源自动管理：重复初始化自动释放旧会话，推理结束自动回收 Bitmap / PixelMap 内存

平台兼容性

Web / 小程序平台不支持本地神经网络推理，调用接口将直接抛出 NOT_INITIALIZED 或由业务侧拦截。

环境要求

• HBuilderX 3.6.8+（鸿蒙平台需 HBuilderX 4.22+）
• uni-app Vue3 工程（Vue2 未验证）
• App 平台需在真机或自定义基座中运行（依赖原生三方库，标准基座不含）

安装

1. 将 jon-yolo 目录放入工程的 uni_modules/ 目录下（或从 DCloud 插件市场直接导入）
2. 工程 manifest.json 中勾选需要的 App 模块（默认即可，无需额外配置）

快速开始

import { initModel, detect, releaseModel } from '@/uni_modules/jon-yolo';

// 1. 初始化模型（Android/iOS 传物理绝对路径，鸿蒙传 rawfile 相对路径或沙箱绝对路径）
const success = await initModel({
    modelPath: '/storage/emulated/0/Android/data/.../models/yolo11n.onnx',
    labels: [],        // 不传或传空数组时，80 类模型自动匹配内置 COCO 标签
    inputSize: 640,    // 可选，默认 640
    numThreads: 4,     // 可选，默认 4
    useGpu: false      // 可选，默认 false（Android 下尝试开启 NNAPI 加速）
});

// 2. 执行检测
const result = await detect({
    imagePath: '/storage/emulated/0/.../test.jpg',
    threshold: 0.25,      // 可选，置信度阈值，默认 0.25
    iouThreshold: 0.45    // 可选，NMS IoU 阈值，默认 0.45
});

// result.items 为检测到的目标列表
result.items.forEach((item) => {
    console.log(item.label, item.score, item.box); // 例如 person 0.92 {x1,y1,x2,y2}
});

// 3. 页面/组件销毁时释放模型内存
releaseModel();

API 文档

initModel(options): Promise<boolean>

初始化并加载模型。重复调用会自动释放上一次的模型会话。

成功返回 true；失败抛出 JonYoloError。

detect(options): Promise<DetectResult>

对指定图片执行目标检测，必须先 initModel。

DetectResult

DetectItem

DetectBox

releaseModel(): void

释放模型与推理引擎资源，建议在页面 onUnmounted / onHide 中调用。

错误码

统一错误类为 JonYoloError（继承 UniError，errSubject 为 jon-yolo），可通过 err.errCode / err.errMsg 获取详情。

模型准备

Android / iOS（ONNX）

1. 准备 YOLO11n / YOLOv8n 模型并导出为 ONNX 格式（推荐导出时固定输入尺寸，如 640x640）
2. 将 .onnx 文件放入工程 static/models/ 目录
3. 运行 / 打包时通过 plus.io.convertLocalFileSystemURL() 将相对路径转换为物理绝对路径后传入 initModel

HarmonyOS NEXT（MindSpore Lite）

1. 使用 MindSpore Lite 转换工具将 ONNX 模型转为 .ms 格式
2. 将 .ms 文件放入鸿蒙资源目录 harmony-configs/entry/src/main/resources/rawfile/models/
3. 直接传入相对路径（如 models/yolo11n.ms）即可，插件首次加载会自动提取到应用沙箱缓存目录

自定义模型

• 自定义模型须基于 YOLO11n / YOLOv8n 架构训练并导出，不支持 YOLOv5 等其他 YOLO 架构
• 按训练时 data.yaml 中的类别顺序填写 labels 数组（索引必须与 classId 对应）
• 插件按输出通道数 C 自动推导类别数量，支持任意类别数
• 输出张量需满足 YOLO 标准格式 [1, 4 + C, N]（N 为预测框数量，如 8400）

性能建议

• 本插件面向 YOLO11n / YOLOv8n（nano 尺寸） 模型设计，建议直接使用官方预训练权重或在其基础上训练
• numThreads 建议 4，高端设备可尝试 8
• 高帧率场景可降低 inputSize（如 320）或开启 useGpu 加速
• 推理时图片路径请使用物理绝对路径，避免二次 IO 开销

更新日志

详见 changelog.md。

许可证

请遵循插件市场发布时声明的授权协议。商用请保留插件版权信息。