更新记录
1.0.1(2026-11-20)
- 新增从系统文件选择器或 App 可读路径导入 Cubism 模型 ZIP,在应用私有目录解压并识别
.model3.json入口。 - 新增双宿主「模型」标签的 ZIP 导入入口。单模型自动加载,多模型可按目录选择。
- 优化接入文档的 ZIP 示例和参数说明,精简代码块中闭合符号的中文注释。
1.0.0(2026-11-20)
- 新增标准 Cubism 模型加载、切换和卸载,加载后返回模型的动作组、表情、触摸区和可用参数。
- 新增动作播放、自动眨眼、表情切换和恢复,以及点击命中与拖动视线。
- 新增本地 PCM16 WAV 播放、暂停、继续和停止,嘴型随播放时钟和声音强弱变化。
- 新增 Android、iOS 与 HarmonyOS NEXT 的原生视图接入源码及原生构建检查,平台验收范围见说明。
- 新增 uni-app 和 uni-app x 示例,提供动作、表情、语音、模型四个标签及 Vapor TypeScript 接法。
- 新增手机与宽屏布局,以及浅色、深色和跟随系统的外观设置。
- 新增模型事件读取、脱敏诊断报告、完整与分段复制。
平台兼容性
uni-app(5.34)
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|
| - | √ | × | × | - | √ | √ | - | - |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| × | × | × | × | × | × | × | × | × | × | × | × |
uni-app x(5.34)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| × | × | √ | - | - | × |
其他
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| × | √ | √ | √ |
lizhao-avatar2d Live2D 角色渲染与互动
介绍
面向 uni-app 和 uni-app x,在 App 页面内导入 ZIP、加载标准 Cubism 模型,展示动作、表情、眨眼、触摸互动和本地语音嘴型。三端使用同一套业务 API,当前平台验收范围见「注意事项」。
功能特色
| 功能 | 使用方式 | 可观察结果 |
|---|---|---|
| 模型加载与切换 | 对已挂载的视图发送 load 或 unload |
读取本地 .model3.json 及关联资源,返回当前模型的能力清单 |
| ZIP 模型导入 | 调用 importAvatarZip,或在「模型」标签选择「从 ZIP 导入」 |
解压到应用私有目录并识别 .model3.json。示例自动加载包内唯一的模型,有多份时供用户选择 |
| 动作播放 | motion 指定模型清单中的动作组及组内索引 |
播放指定动作,可读取开始、结束和被替换事件 |
| 表情与眨眼 | expression 切换或恢复表情,blink 设置自动眨眼 |
模型具备对应参数或表情时可见效果 |
| 触摸与视线 | 点按人物或拖过画布,用 readAvatarEvents 读取触摸事件 |
返回归一化坐标和命中区名称。拖动可驱动模型已有的视线参数 |
| 语音嘴型 | 用 playWav 播放本地 PCM16 WAV,可暂停、继续和停止 |
模型声明 LipSync 时,嘴部随声音强弱开合 |
| 双宿主演示 | 按「动作、表情、语音、模型」四个标签操作 | 可切换虹色Mao、Haru 或使用自己的本地模型 |
| 宽屏与外观 | 示例按窗口大小排版,右上角切换外观 | 手机单栏、宽屏双栏,支持浅色、深色和跟随系统 |
| 诊断 | 调用 getAvatarDiagnostics,或在示例底部使用完整、分段复制 |
查询当前视图状态、错误码和近期命令,便于定位失败原因 |
适合哪些场景
| 场景 | 推荐接法 | 接入边界 |
|---|---|---|
| App 内虚拟助手、互动讲解 | 先 load,按 hit 事件触发动作或播放台词 |
命中区由模型声明,按每个模型的能力清单绑定 |
| 模型预览与验收 | 切换不同模型路径,检查动作组、表情及参数 | 使用已导出的 .model3.json、.moc3 和对应贴图 |
| 角色对话或 TTS 播报 | 将已合成的台词保存为本地 PCM16 WAV,再用 playWav 播放 |
嘴型由响度驱动。实时音频推流、录音采集和音素口型属于另外的能力 |
| 手机与平板交互展示 | 按示例布局调整画布与操作面板,保持同一 view-id |
宿主负责自己的导航、配色和容器尺寸 |
| 导入客户模型包、离线展示 | 通过系统文件选择器选 ZIP,或直接传 App 可读的本地 ZIP 路径 | ZIP 应包含完整导出目录,保持清单、模型与贴图的原相对路径 |
下载与导入
| 宿主 | 示例代码位置 |
|---|---|
| uni-app | uni_modules/lizhao-avatar2d/example/uniapp/native.nvue(Android、iOS),uni_modules/lizhao-avatar2d/example/uniapp/index.vue(HarmonyOS NEXT) |
| uni-app x | uni_modules/lizhao-avatar2d/example/uniappx/index.uvue |
从基础到进阶:按业务模块使用
基础示例
用 HBuilderX 5.34 导入插件,准备平台原生库并制作匹配的自定义基座。用自有模型时,保留原目录结构并将示例代码中的清单地址换成自己的本地路径。已取得官方素材的开发者可在项目根目录执行下列命令准备 Haru、虹色Mao 和演示音频。两个配对工程的物料位置都是 static/avatar2d-demo/(由开发者准备)。
# 将占位目录换成已解压的 Cubism Native SDK,脚本将模型文件复制到当前工程。
node scripts/prepare-avatar2d-example.cjs "<本机 Cubism SDK 目录>"
uni-app x 基础页面可复制到已注册的 .uvue 页面,使用 Vapor TypeScript。视图挂载后点「加载模型」。若首次回报视图未就绪,待绘图表面就绪后重试。
<!-- 声明最小的人物预览页。 -->
<template>
<!-- 给画布和页面控制留出可用空间。 -->
<view>
<!-- 固定视图标识,给原生画布明确的宽高,并监听挂载结果。 -->
<lizhao-avatar2d view-id="basic-avatar" style="width: 300px; height: 340px;" @ready="viewReady" @error="viewError"></lizhao-avatar2d>
<!-- 等待组件挂载,或上次加载完成后再允许点击。 -->
<button :disabled="!ready || loading" @click="loadModel">加载模型</button>
<!-- 将当前状态显示在页面上。 -->
<text>{{ status }}</text>
</view>
</template>
<!-- 下面是页面的 TypeScript 逻辑。 -->
<script setup lang="ts">
import { ref } from 'vue' // 导入响应式变量,用于更新按钮和状态。
import { controlAvatar } from '@/uni_modules/lizhao-avatar2d' // 从插件根目录导入命令接口。
const ready = ref(false) // 组件尚未挂载时关闭加载入口。
const loading = ref(false) // 防止快速连点重复提交。
const status = ref('等待人物视图') // 记录用户可见状态。
function viewReady(): void { ready.value = true; status.value = '可以加载模型' } // 接到组件就绪通知后开启按钮。
function viewError(message: string): void { status.value = message } // 显示组件绑定失败的字符串。
function loadModel(): void { // 点击后提交一次加载请求。
loading.value = true // 关闭按钮直到收到完成回调。
controlAvatar({ // 下列字段组成一条人物命令。
viewId: 'basic-avatar', // 必须与组件的 view-id 相同。
action: 'load', // 请求加载模型。
value: '/static/avatar2d-demo/Haru/Haru.model3.json', // 换成自己的清单路径。
success: result => { status.value = '已加载,表情数量:' + (result.model?.expressions.length ?? 0) }, // 读取真实能力结果。
fail: error => { status.value = error.errCode + ' ' + error.errMsg }, // 显示失败码和原因。
complete: () => { loading.value = false } // 成功和失败都会恢复操作按钮。
})
}
</script>
传统 uni-app Vue3 基础页面在 Android、iOS 放进 .nvue 页面,在 HarmonyOS NEXT 放进 .vue 页面。两个页面的业务代码相同,编译时选对应组件。传统组件通过 ready 通知挂载,加载失败由 API 的 fail 返回。
<!-- 声明传统 uni-app 的最小人物界面。 -->
<template>
<!-- 让画布和按钮纵向排列。 -->
<view>
<!-- Android 与 iOS 选择传统原生页面分支。 -->
<!-- #ifdef APP-PLUS -->
<!-- 在 nvue 中挂载原生人物组件。 -->
<lizhao-avatar2d-view view-id="basic-avatar" style="width: 300px; height: 340px;" @ready="viewReady"></lizhao-avatar2d-view>
<!-- #endif -->
<!-- HarmonyOS NEXT 选择 Vue 页面分支。 -->
<!-- #ifdef APP-HARMONY -->
<!-- 在鸿蒙 Vue 页面使用 embed 封装组件。 -->
<lizhao-avatar2d view-id="basic-avatar" style="width: 300px; height: 340px;" @ready="viewReady"></lizhao-avatar2d>
<!-- #endif -->
<!-- 组件就绪后才允许送出加载命令。 -->
<button :disabled="!ready || loading" @click="loadModel">加载模型</button>
<!-- 显示结果或错误。 -->
<text>{{ status }}</text>
</view>
</template>
<!-- 下方脚本使用 Vue3 的写法。 -->
<script setup lang="ts">
import { ref } from 'vue' // 导入用于状态展示的响应式变量。
import { controlAvatar } from '@/uni_modules/lizhao-avatar2d' // 使用插件的公开根入口。
const ready = ref(false) // 记录组件是否已经挂载。
const loading = ref(false) // 等待回执时避免重复点击。
const status = ref('等待人物视图') // 初始化页面状态。
function viewReady(): void { ready.value = true; status.value = '可以加载模型' } // 接到挂载通知后开启按钮。
function loadModel(): void { // 提交本地模型加载。
loading.value = true // 将加载按钮置为忙碌。
controlAvatar({ // Android、iOS、鸿蒙使用相同的命令结构。
viewId: 'basic-avatar', // 与当前平台实际渲染的组件标识一致。
action: 'load', // 指定加载命令。
value: '/static/avatar2d-demo/Haru/Haru.model3.json', // 填写 App 可访问的清单地址。
success: result => { status.value = '已加载,动作组数量:' + (result.model?.motions.length ?? 0) }, // 展示返回的动作组数。
fail: error => { status.value = error.errCode + ' ' + error.errMsg }, // 展示真实错误。
complete: () => { loading.value = false } // 一次请求结束后恢复按钮。
})
}
</script>
高级示例
标准模型加载成功后,从 success 返回的 model 读取选项。将下面的方法放到任一宿主的 TypeScript 页面中。在界面选择动作组、编号或表情后分别调用对应方法。动作索引默认为 0,调用者可省略第三个参数,或传入从 0 开始的组内编号。
import { controlAvatar } from '@/uni_modules/lizhao-avatar2d' // 导入两种宿主共用的命令接口。
import type { AvatarFailure, AvatarModelInfo } from '@/uni_modules/lizhao-avatar2d' // 导入错误对象和模型能力的类型。
function showActionFailure(error: AvatarFailure): void { console.warn(error.errSubject, error.errCode, error.errMsg) } // 输出错误主体、错误码和原因。
function playMotion(viewId: string, model: AvatarModelInfo, groupName: string, index: number = 0): void { // 接收当前模型、动作组和索引。
const group = model.motions.find(item => item.group === groupName) // 以模型返回的组名查找配置。
if (group == null || !Number.isInteger(index) || index < 0 || index >= group.count) return // 缺少分组或编号超出范围时结束。
controlAvatar({ viewId, action: 'motion', value: group.group, index, fail: showActionFailure }) // 使用真实分组名和零基索引播放。
}
function switchExpression(viewId: string, model: AvatarModelInfo, name: string): void { // 用当前视图和模型所含的表情做切换。
if (name !== '' && !model.expressions.includes(name)) return // 除了恢复用的空字符串,其余名称必须出现在模型清单里。
controlAvatar({ viewId, action: 'expression', value: name, fail: showActionFailure }) // 传表情名称切换,传空字符串恢复。
}
function setAutoBlink(viewId: string, model: AvatarModelInfo, enabled: boolean): void { // 将界面的开关状态映射为眨眼命令。
if (model.eyeBlinkIds.length === 0) return // 模型未提供眼睛参数时不发送该命令。
controlAvatar({ viewId, action: 'blink', value: enabled ? 'on' : 'off', fail: showActionFailure }) // 传 'on' 开启,传 'off' 关闭。
}
进阶示例
完整工程中,把示例路由放入各自的 pages.json。如需示例自己的返回栏和外观按钮,已有路由的 style 应使用 navigationStyle: "custom"。复制完整示例至其他工程时,应把直接打开页面时的返回路径 /pages/index/index 改为工程的首页。
为 uni-app x 启用与本示例一致的 Vapor 字节码配置,在 manifest.json 合并下面的字段。保留项目原有的应用标识、签名和其他设置。
{ // 以下为 uni-app x 的 manifest.json 片段,请合并进现有根对象。
"uni-app-x": { // 此节点保存 uni-app x 的视图层配置。
"vapor": true, // 以蒸汽模式编译 .uvue 页面。
"vapor-render-target": "bytecode", // 选用本示例验证过的字节码构建。
"vapor-default-script-lang": "ts", // 页面未单独声明时按 TypeScript 处理。
"styleIsolationVersion": "2" // 使用示例工程的样式隔离配置。
}
}
传统 uni-app 使用 Vue3。下面是传统宿主 manifest.json 中与本插件 Android、iOS 的 nvue 组件有关的片段。鸿蒙使用上面演示过的 .vue 页面。
{ // 以下为传统 uni-app 的 manifest.json 片段,请合并进现有根对象。
"vueVersion": "3", // 用 Vue3 编译示例中的 script setup 写法。
"app-plus": { // 仅为传统 Android 和 iOS 的 App 运行容器配置。
"usingComponents": true, // 允许页面使用自定义原生组件。
"nvueStyleCompiler": "uni-app", // 使用 uni-app 的 nvue 样式编译器。
"compilerVersion": 3 // 采用配对工程中实际使用的组件编译配置。
}
}
以双宿主示例的标题栏设置为例,可给文档中的基础和完整示例路由保留系统标题栏。复制带自定义标题栏的项目示例时,合并对应的路由样式。不要将下面的根对象覆盖整个 pages.json。
{ // 在工程原有 pages 数组中加入相应页面的记录。
"pages": [ // 下例注册 uni-app x 的项目示例路由。
{ // 用一项配置描述该演示页面。
"path": "uni_modules/lizhao-avatar2d/example/uniappx/index", // 不加扩展名,传统宿主改填对应的示例路径。
"style": { // 设置页面的导航和首屏背景。
"navigationStyle": "custom", // 由示例自己的标题栏负责返回、角色名和外观。
"navigationBarTitleText": "Live2D 角色", // 作为页面标题。
"navigationBarTextStyle": "black", // 设置初次打开时的系统文字色。
"backgroundColor": "#f7f4ef" // 与示例浅色模式的背景一致。
}
}
]
}
下面是 uni-app x 控制画布布局与外观的最小逻辑。可将 frame.stage、frame.preview 分别绑定到画布宽高,单位为逻辑像素,并以 isDark 切换页面样式。完整的双宿主窗口和主题逻辑已写入「下载与导入」中的页面。
import { ref } from 'vue' // 导入响应式变量。
import { onReady, } from '@dcloudio/uni-app' // 在页面首次就绪和窗口改变时同步布局。
import { avatarLayout } from '@/uni_modules/lizhao-avatar2d/example/frontend/layout.ts' // 引用示例中共享的尺寸计算。
const frame = ref(avatarLayout(375, 667)) // 页面测量前先用一个手机尺寸占位。
const isDark = ref(false) // 保存当前页面的深色开关。
function refreshStage(): void { // 读取当前窗口并更新大小。
const windowInfo = uni.getWindowInfo() // 获取的是逻辑像素,可直接用于布局。
frame.value = avatarLayout(windowInfo.windowWidth, windowInfo.windowHeight) // 自动选择单栏或双栏。
isDark.value = uni.getDeviceInfo().osTheme === 'dark' // 按系统外观选择业务页面的颜色。
}
onReady(() => refreshStage()) // 首次测量窗口。
(() => refreshStage()) // 旋转或分屏时重新计算,不改变视图标识。
完整示例
以下页面可单独使用。uni-app x 保存为 .uvue,传统 Android、iOS 保存为 .nvue,鸿蒙的传统宿主保存为 .vue。在工程内注册页面,准备 Haru 及演示 WAV 后依次点击加载、动作、表情、语音和卸载。组件随页面自动释放,所以离页时只需停止页面的事件轮询。
<!-- 完整演示的页面模板。 -->
<template>
<!-- 将人物与操作放进同一个页面容器。 -->
<view>
<!-- 传统 Android、iOS 使用原生 nvue 视图分支。 -->
<!-- #ifdef APP-PLUS && !UNI_APP_X -->
<!-- 固定视图标识和画布尺寸,监听挂载事件。 -->
<lizhao-avatar2d-view :view-id="viewId" style="width: 300px; height: 300px;" @ready="viewReady"></lizhao-avatar2d-view>
<!-- #endif -->
<!-- uni-app x App 与传统鸿蒙使用标准组件分支。 -->
<!-- #ifdef (APP && UNI_APP_X) || APP-HARMONY -->
<!-- 绑定同一个实例标识,让下面的命令发往这块画布。 -->
<lizhao-avatar2d :view-id="viewId" style="width: 300px; height: 300px;" @ready="viewReady"></lizhao-avatar2d>
<!-- #endif -->
<!-- 原生视图准备好后即可加载示例角色。 -->
<button :disabled="!ready || busy" @click="send('load', modelPath)">加载 Haru</button>
<!-- 播放 Haru 清单里的身体动作组首个动作。 -->
<button :disabled="!loaded || busy" @click="send('motion', 'TapBody', 0)">播放动作</button>
<!-- 切换到 Haru 的 F01 表情。 -->
<button :disabled="!loaded || busy" @click="send('expression', 'F01')">切换表情</button>
<!-- 当前模型支持嘴型时才允许播放这一段 WAV。 -->
<button :disabled="!canLip || busy" @click="send('playWav', wavPath)">播放语音</button>
<!-- 可随时卸载已经加载的人物。 -->
<button :disabled="!loaded || busy" @click="send('unload')">卸载模型</button>
<!-- 显示最近一次成功或失败。 -->
<text>{{ status }}</text>
</view>
</template>
<!-- 下面是跨宿主的 TypeScript 页面脚本。 -->
<script setup lang="ts">
import { ref } from 'vue' // 导入用于按钮和状态展示的响应式变量。
import { onShow, onHide, onUnload } from '@dcloudio/uni-app' // 导入页面的显示、隐藏和退出回调。
import { controlAvatar, readAvatarEvents, getAvatarDiagnostics } from '@/uni_modules/lizhao-avatar2d' // 导入插件全部公开业务接口。
const viewId = 'complete-avatar' // 此页面内的唯一视图标识。
const modelPath = '/static/avatar2d-demo/Haru/Haru.model3.json' // 要加载的 Haru 模型清单。
const wavPath = '/static/avatar2d-demo/Haru/sounds/haru_Info_14.wav' // 由素材准备脚本写入的演示音频。
const ready = ref(false) // 记录视图是否已挂载。
const loaded = ref(false) // 记录角色是否已加载。
const busy = ref(false) // 一次只让界面提交一条命令。
const canLip = ref(false) // 记录声明了 LipSync 的模型能力。
const status = ref('等待人物视图') // 存放给用户看的操作结果。
let active = true // 页面退出后忽略迟到的回执。
let timer = 0 // 保存用于读取事件的计时器编号。
function viewReady(): void { ready.value = true; status.value = '可以加载模型' } // 打开模型操作入口。
function send(action: string, value: string = '', index: number = 0): void { // 封装演示页复用的命令入口。
if (!ready.value || busy.value) return // 避免视图未挂载或仍有请求时提交。
busy.value = true // 进入忙碌态直到收到 complete。
controlAvatar({ // 将命令发送给已经挂载的视图。
viewId, // 传入组件使用的唯一标识。
action, // 传入所选操作名称。
value, // 加载和播放语音用文件路径,表情用名称。
index, // 仅播放动作时使用,默认从组内第一个开始。
success: result => { // 成功后读取或更新该视图的状态。
if (!active) return // 离开页面后不再改界面。
if (result.model != null) { // 只有加载成功时才会带模型能力。
loaded.value = true // 开启已加载角色的按钮。
canLip.value = result.model.lipSyncIds.length > 0 // 读取是否可播放语音嘴型。
}
if (result.action === 'unload') { loaded.value = false; canLip.value = false } // 卸载后关闭人物相关操作。
status.value = result.viewId + ' 已接受 ' + result.action // 命令回执与动画或音频结束事件分开显示。
},
fail: error => { // 采集真实失败信息。
if (!active) return // 避免页面销毁后更新响应式状态。
status.value = error.action + ' 失败,' + error.errCode + ' ' + error.errMsg // 显示失败动作、错误码和原因。
if (error.errCode === 9387010) console.warn(getAvatarDiagnostics(viewId)) // 桥接超时先看诊断再决定如何处理。
},
complete: () => { if (active) busy.value = false } // 成功或失败都解除当前命令的忙碌状态。
})
}
function stopPolling(): void { // 停止读取此页面的事件。
if (timer !== 0) { clearInterval(timer); timer = 0 } // 取消已有计时器并重置编号。
}
onShow(() => { // 页面获得可见性后开启事件读取。
if (timer !== 0) return // 防止重复注册。
timer = setInterval(() => { // 每隔 200 毫秒取出视图积累的事件。
if (!ready.value) return // 视图未挂载时等待下一轮。
for (const event of readAvatarEvents(viewId)) console.log(event.type, event.name, event.x, event.y) // 打印事件类型、名称和坐标。
}, 200) // 设定轮询间隔,单位为毫秒。
})
onHide(stopPolling) // 页面不可见时暂停读取。
onUnload(() => { active = false; stopPolling() }) // 离页后忽略迟到回执,组件销毁时释放原生视图。
</script>
实际演示页按业务分组,并共用同一人物视图。切换标签仅改变展示的面板,保留模型、输入、播放状态和诊断报告。
| 分类或公共区域 | 对应能力 | 测试方法 |
|---|---|---|
| 动作 | motion |
选组后点编号。界面编号 1 对应 API 索引 0,点击「输入索引」可指定任意组内编号 |
| 表情 | expression、blink |
选择和恢复表情,观察自动眨眼开关 |
| 语音 | playWav、pauseVoice、resumeVoice、stopVoice |
填写本地 PCM16 WAV 路径并操作播放控制 |
| 模型 | load、unload |
选择虹色Mao、Haru,或填写 App 能访问的清单地址 |
| 人物画布与标题栏 | readAvatarEvents、窗口布局与外观 |
点按头部、身体,拖动画布,再切换浅色、深色和跟随系统 |
| 公共诊断区 | getAvatarDiagnostics 和示例报告 |
展开诊断日志,尝试一键复制、分段复制和完整报告 |
模块示例
下列代码可以按需放进 uni-app Vue3 或 uni-app x 页面。模块接受已挂载视图的标识。语音、动作和表情在模型加载成功后使用。
加载自有模型
manifestPath 是应用实际保存的 .model3.json 路径。可传已有清单,也可传 ZIP 导入成功结果中某个 models 条目的 path。
import { controlAvatar } from '@/uni_modules/lizhao-avatar2d' // 从插件根入口使用统一接口。
export function loadLocalModel(viewId: string, manifestPath: string): void { // 传入组件的标识和实际文件路径。
controlAvatar({ // 请求把模型加载进指定视图。
viewId, // 与已挂载组件的 view-id 一致。
action: 'load', // 选择加载操作。
value: manifestPath, // 填写清单文件地址。
success: result => { console.log(result.model) }, // 返回与新模型对应的能力清单。
fail: error => { console.warn(error.errSubject, error.errCode, error.errMsg) }, // 输出错误主体、错误码和失败原因。
complete: () => { console.log('本次加载已结束') } // 可在这里清理自己的加载状态。
})
}
导入 ZIP 并加载模型
在视图就绪后,把 importModelArchive 绑定到「从 ZIP 导入」按钮。省略 zipPath 时打开系统文件选择;若 App 已保存 ZIP,则传实际可读路径。示例的 showChoices 用于渲染候选,用户点选后调用 loadImportedAvatar。对于内容不完整的包,load 会返回具体错误。
import { controlAvatar, importAvatarZip } from '@/uni_modules/lizhao-avatar2d' // 使用插件根入口导入模型与视图接口。
import type { AvatarZipOptions, AvatarZipModel, AvatarZipResult, AvatarZipFailure, AvatarResult, AvatarFailure } from '@/uni_modules/lizhao-avatar2d' // 导入两次请求各自的结果类型。
export function loadImportedAvatar(viewId: string, model: AvatarZipModel, showStatus: (message: string) => void): void { // 传入已挂载的视图以及要加载的候选。
controlAvatar({ // 将导入得到的清单加载到当前画布。
viewId, // 使用视图组件的 view-id。
action: 'load', // 加载标准 Cubism 模型。
value: model.path, // 使用导入结果中的绝对清单路径。
success: (result: AvatarResult) => { showStatus('已加载 ' + model.name + ',视图 ' + result.viewId) }, // 加载完成后更新页面状态。
fail: (error: AvatarFailure) => { showStatus(error.errCode.toString() + ' ' + error.errMsg) } // 失败时显示模型错误,画布保留已加载人物。
})
}
export function importModelArchive(viewId: string, showChoices: (models: Array<AvatarZipModel>) => void, showStatus: (message: string) => void, zipPath: string | null = null): void { // 传入候选列表和状态更新方法,zipPath 可省略。
showStatus('等待选择或解压 ZIP') // 先向用户反馈正在处理。
const options: AvatarZipOptions = { // 配置导入请求,无需传视图标识。
success: (result: AvatarZipResult) => { // 此时 ZIP 已解压并识别了模型入口。
if (result.models.length == 1) { // 只有一个候选时直接加载。
loadImportedAvatar(viewId, result.models[0], showStatus) // 加载完成以 controlAvatar 的回执为准。
} else { // 包含多个模型时由用户选一个。
showChoices(result.models) // 可显示 name 与 relativePath,点选后调用 loadImportedAvatar。
showStatus('请选择要加载的模型') // 给出下一步操作提示。
}
},
fail: (error: AvatarZipFailure) => { showStatus(error.errCode == 9387008 ? '已取消选择' : error.errCode.toString() + ' ' + error.errMsg) }, // 单独处理主动取消。
complete: () => { console.log('ZIP 导入请求已完成') } // 可在此恢复文件选择按钮。
}
if (zipPath != null) options.zipPath = zipPath // 已有本地 ZIP 时跳过系统选择。
importAvatarZip(options) // 交给插件选取、解压和扫描。
}
按触摸区互动
在页面里选择一个事件消费者。已经有轮询时,在原来的轮询中调用下列方法,免得另一个消费者先取走同一批事件。
import { controlAvatar, readAvatarEvents } from '@/uni_modules/lizhao-avatar2d' // 导入读事件和执行动作的方法。
import type { AvatarModelInfo } from '@/uni_modules/lizhao-avatar2d' // 使用加载成功回调返回的模型能力类型。
export function respondToTouch(viewId: string, model: AvatarModelInfo): void { // 对当前视图及已加载模型做一次事件处理。
for (const event of readAvatarEvents(viewId)) { // 取走该视图待处理的事件。
if (event.type === 'tap') console.log('点击坐标', event.x, event.y) // 记录左上角为原点的画布归一化坐标。
if (event.type !== 'hit' || event.name !== 'Body') continue // 只处理名为 Body 的命中区。
const group = model.motions.find(item => item.group === 'TapBody' && item.count > 0) // 确认当前模型确实有可用的身体动作。
if (group == null) continue // 允许模型没有此动作组。
controlAvatar({ viewId, action: 'motion', value: group.group, fail: error => console.warn(error.errCode, error.errMsg) }) // 省略索引时播放组内第一条。
}
}
控制 WAV 与嘴型
将以下四个函数分别绑定到播放、暂停、继续和停止按钮。播放使用本地小端 PCM16 WAV,前置条件是模型返回的 lipSyncIds 非空。界面根据回执更新状态,音频自然结束时使用 voiceEnd 事件更新。
import { controlAvatar } from '@/uni_modules/lizhao-avatar2d' // 导入角色控制接口。
import type { AvatarFailure } from '@/uni_modules/lizhao-avatar2d' // 导入类型,让错误处理可读取实际字段。
function onVoiceFailure(error: AvatarFailure): void { console.warn(error.action, error.errCode, error.errMsg) } // 输出失败所在的音频操作以及错误详情。
export function playAvatarWav(viewId: string, path: string = '/static/avatar2d-demo/Haru/sounds/haru_Info_14.wav'): void { // 可传自有 WAV 路径,省略时播放演示文件。
controlAvatar({ viewId, action: 'playWav', value: path, fail: onVoiceFailure }) // 启动播放并按声音强弱驱动嘴型。
}
export function pauseAvatarVoice(viewId: string): void { // 在播放中调用暂停。
controlAvatar({ viewId, action: 'pauseVoice', fail: onVoiceFailure }) // 保留当前位置。
}
export function resumeAvatarVoice(viewId: string): void { // 在暂停状态调用继续。
controlAvatar({ viewId, action: 'resumeVoice', fail: onVoiceFailure }) // 从保留的位置恢复。
}
export function stopAvatarVoice(viewId: string): void { // 在播放或暂停时停止。
controlAvatar({ viewId, action: 'stopVoice', fail: onVoiceFailure }) // 结束当前声音并释放播放资源。
}
诊断与复制
下面的 showManualText 由页面传入,可把文字绑定到可选择的文本区域。项目完整示例在这段插件诊断之外还会记录当前页面操作、宿主环境和固定快照编号,支持分段复制。
import { getAvatarDiagnostics } from '@/uni_modules/lizhao-avatar2d' // 使用插件根入口读取诊断。
export function copyAvatarDiagnostics(viewId: string, showManualText: (text: string) => void): void { // 传入当前视图和手动复制回退方法。
const report = getAvatarDiagnostics(viewId) // 保存这次实际获取的诊断文本。
uni.setClipboardData({ // 交给宿主的剪贴板接口。
data: report, // 使用原始诊断文本作为复制内容。
success: () => { uni.showToast({ title: '已复制诊断', icon: 'none' }) }, // 只在系统复制成功后给出提示。
fail: () => { showManualText(report) } // 失败时把同一份文本交给页面手动复制。
})
}
API 用途速查
| 公开 API | 用途 | 返回或回调 |
|---|---|---|
controlAvatar(options) |
向已挂载的人物视图发送命令 | 返回 void,异步触发一次 success 或 fail,随后触发 complete |
importAvatarZip(options) |
选取或指定本地 ZIP,解压并识别模型入口 | 返回 void。success 返回导入目录和候选模型,之后可向视图发送 load |
readAvatarEvents(viewId) |
取走指定视图当前积累的事件 | AvatarEvent[],没有待取事件时返回空数组 |
getAvatarDiagnostics(viewId) |
读取指定视图快照和近期命令 | string,可供排查和复制 |
页面组装与组件配置
| 参数 | 类型 | 必填 | 说明 | 默认值 | 可选参数 |
|---|---|---|---|---|---|
| view-id | string | 是 | 组件实例标识。与 API 中的 viewId 一致,实例存活期间保持稳定 |
无 | 长度 1 至 96 的自定义标识。同屏实例各不相同 |
| style 或外层容器 | 页面样式 | 是 | 宿主为画布提供明确宽高,避免画布尺寸为零 | 由宿主决定 | 定高、受控布局、宽屏双栏 |
| @ready | () => void | 建议 | 视图组件已绑定。绘图表面稍晚可用时,加载可能先回报 9387002 |
无 | 允许加载,或按失败码做有限重试 |
| @error | (message: string) => void | 否 | uni-app x 组件的绑定失败消息。具体命令失败使用 fail |
无 | 自定义提示 |
| navigationStyle | string | 否 | 仅在使用完整示例的自定义标题栏时设置页面路由 | 宿主默认 | custom 或由宿主提供系统标题栏 |
controlAvatar 选项
| 参数 | 类型 | 必填 | 说明 | 默认值 | 可选参数 |
|---|---|---|---|---|---|
| viewId | string | 是 | 要操作的组件实例,也用于 readAvatarEvents 和 getAvatarDiagnostics |
无 | 长度 1 至 96 |
| action | string | 是 | 操作名称,区分大小写 | 无 | 见下表 |
| value | string | 按操作 | 文件路径、组名、表情名称或眨眼状态,最长 4096 | 空字符串 | 见下表 |
| index | number | 否 | motion 的组内索引,整数且从 0 开始 |
0 | 大于等于 0 且小于当前组的 count |
| success | (result: AvatarResult) => void | 否 | 操作成功。执行动作或开始播放的回执在效果结束之前返回 | 无 | 单次回调 |
| fail | (error: AvatarFailure) => void | 否 | 命令失败、取消或超时 | 无 | 单次回调 |
| complete | () => void | 否 | 成功或失败回调之后执行,不接收参数 | 无 | 可用于关闭加载提示 |
| action | value | index | 行为 |
|---|---|---|---|
load |
App 可读的本地 .model3.json 路径 |
省略 | 加载或切换模型,成功返回能力清单 |
motion |
清单中的动作组名 | 默认 0 | 播放组内指定动作 |
expression |
清单中的表情名,或空字符串 | 省略 | 切换表情,空字符串恢复 |
blink |
on 或 off |
省略 | 开启或关闭自动眨眼 |
playWav |
App 可读的本地 PCM16 WAV 路径 | 省略 | 播放并驱动嘴型 |
pauseVoice |
省略 | 省略 | 暂停当前播放 |
resumeVoice |
省略 | 省略 | 从暂停位置继续 |
stopVoice |
省略 | 省略 | 停止本次音频 |
unload |
省略 | 省略 | 卸载当前模型及相关音频,可在该视图再次加载 |
importAvatarZip 选项
| 参数 | 类型 | 必填 | 说明 | 默认值 | 可选参数 |
|---|---|---|---|---|---|
| zipPath | string | 否 | 指定 App 可读取的本地 ZIP 路径,最长 4096 个字符。传空字符串报参数错误 | 省略时打开系统文件选择器 | App 私有文件的绝对路径或本地 file:// URI。Android 也支持已有读取授权的 content:// URI |
| success | (result: AvatarZipResult) => void | 否 | 解压并找到模型入口后回调。模型文件的完整性和渲染能力由 load 检查 |
无 | 单次回调 |
| fail | (error: AvatarZipFailure) => void | 否 | 文件选择取消或导入失败时回调 | 无 | 单次回调 |
| complete | () => void | 否 | 在成功或失败回调后执行 | 无 | 可用于恢复导入按钮 |
返回值、能力清单与事件字段
| 类型 | 字段 | 含义 |
|---|---|---|
AvatarResult |
viewId、action |
本次回执对应的视图和操作 |
AvatarResult |
model |
AvatarModelInfo。仅加载成功时有值,其他操作为 null |
AvatarFailure |
errSubject、errCode、errMsg |
错误主题、数字错误码和说明文字 |
AvatarFailure |
viewId、action |
对应的失败命令和视图 |
AvatarZipResult |
directory |
本次解压到的应用私有目录绝对路径 |
AvatarZipResult |
models |
AvatarZipModel[],按 ZIP 内相对路径排序,至少一个 |
AvatarZipModel |
name、path、relativePath |
入口文件基础名、供 load 使用的绝对路径、用于区分同名候选的 ZIP 内相对路径 |
AvatarZipFailure |
errSubject、errCode、errMsg |
导入错误主题、数字错误码和说明文字 |
AvatarModelInfo |
motions |
AvatarMotionGroup[],可生成分组选项 |
AvatarMotionGroup |
group、count |
传给 motion 的实际组名及组内动作数量 |
AvatarModelInfo |
expressions |
该模型可用的表情名列表 |
AvatarModelInfo |
hitAreas |
可用于业务映射的点击命中区名称列表 |
AvatarModelInfo |
eyeBlinkIds |
模型声明的自动眨眼参数 ID 列表 |
AvatarModelInfo |
lipSyncIds |
模型声明的嘴型参数 ID 列表 |
AvatarEvent |
type、name |
事件类型和对应名称,具体见下表 |
AvatarEvent |
x、y |
触摸时相对画布的归一化坐标,左上为原点。非触摸事件两值均为 0 |
| type | name 内容 | 用途 |
|---|---|---|
loaded、unloaded |
空字符串 | 模型加载或卸载状态 |
motionStart、motionEnd、motionCanceled |
动作标识 | 判断动作开始、自然完成或被替换 |
motionEvent |
模型动作资源中配置的事件值 | 处理时间轴自定义事件 |
expression |
表情名称,恢复时为空字符串 | 同步当前表情 |
tap、hit |
点击时为空字符串,命中时为模型的命中区名称 | 业务触摸互动 |
voiceEnd |
空字符串 | 自然播放结束,可用于恢复播放按钮 |
error |
文本形式的错误码 | 处理渲染或播放等异步问题 |
voiceStart、voiceStop |
空字符串 | iOS 当前实现额外上报的事件,跨平台界面以命令回执更新开始和停止状态 |
错误码说明
errSubject 固定为 lizhao-avatar2d。每次调用最多收到一次成功或失败回执,之后执行 complete。controlAvatar 等待原生回执超过 60 秒会返回 9387010,原操作结果此时未知。importAvatarZip 会等待用户完成或关闭系统文件选择器。
| 错误码 | 含义 | 处理 |
|---|---|---|
| 9387001 | 标识、动作、索引、文件类型或参数无效 | 核对模型清单扩展名、命令、ZIP 路径及参数 |
| 9387002 | 视图或模型未就绪,当前播放状态不可操作,或已有一次 ZIP 导入在处理 | 等待布局或当前操作完成,再重试 |
| 9387003 | 本地文件不可读、资源越界或超限 | 保持原始文件层级,检查路径、缺失资源与大小 |
| 9387004 | 模型格式、MOC 版本、一致性或配置无效 | 重新导出并使用兼容 Core |
| 9387005 | 动作、表情或模型参数等能力缺失 | 从实际能力清单选取 |
| 9387006 | 图形上下文、纹理或首帧提交失败 | 重建视图,检查 GPU、资源和平台日志 |
| 9387007 | WAV 或音频输出错误 | 核对 PCM 参数与音频输出状态 |
| 9387008 | 关闭了系统文件选择器,或视图销毁、操作被替换导致取消 | 保留当前页面状态。需要继续时重新选择或挂载视图 |
| 9387009 | 当前平台或对应原生依赖不可用 | 检查平台和打包入基座的私有产物 |
| 9387010 | 桥接异常、回执格式错误或等候超时 | 收集完整诊断。超时后先核当前状态 |
| 9387011 | ZIP 格式损坏、不支持或内容校验失败 | 重新导出普通 ZIP,使用存储或 Deflate,不加密 |
| 9387012 | ZIP 大小或数量超限,或包含不安全的路径或条目 | 检查包大小和文件数量,移除符号链接、异常路径及重复文件名 |
| 9387013 | ZIP 中未找到 .model3.json |
检查压缩包是否包含完整的 Cubism 导出文件 |
注意事项
平台兼容性
示例以 HBuilderX 5.34.2026102909 核验,插件最低工具与宿主声明为 5.34 系列。符号按插件市场定义,√ 为支持,× 为不支持,– 为待确认。完整记录与 uni_modules/lizhao-avatar2d/package.json 中的平台声明对应。 DCloud 平台兼容字段
uni-app
| Vue2 | Vue3 | Chrome | Safari | App-vue | App-nvue | Android | iOS | HarmonyOS NEXT |
|---|---|---|---|---|---|---|---|---|
| – | √ | × | × | – | √ | √ | – | – |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ 小程序 | 飞书小程序 | 小红书小程序 | 华为快应用 | 联盟快应用 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| × | × | × | × | × | × | × | × | × | × | × | × |
Android、iOS 的传统接入使用 App-nvue。App-vue 的渲染入口仅用于 HarmonyOS NEXT。腾讯云、阿里云、支付宝云端均不提供原生渲染入口。
uni-app x
| Chrome | Safari | Android | iOS | HarmonyOS NEXT | 微信小程序 | 支付宝小程序 |
|---|---|---|---|---|---|---|
| × | × | √ | – | – | × | × |
Chrome 可看示例静态预览。Web、小程序调用有效的渲染或 ZIP 导入命令会收到 9387009。Vapor TypeScript 示例使用字节码目标,其他 uni-app x 渲染模式需单独确认。
其他兼容性
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| ×,示例文案为简体中文 | √,浅色、深色、跟随系统 | √,按逻辑窗口宽高切换单双栏 | √,uni-app x Vapor TypeScript 字节码 |
| 设置 | 真实表现 |
|---|---|
| 主题色 | 示例初次跟随系统,标题栏右上角可以循环切换并记住上次选择。只改变页面、画布背景和控件配色,项目业务页面自行定义主题样式 |
| 双栏规则 | 可用宽度 ≥ 720 逻辑像素,或宽度 ≥ 540 且宽大于高时,人物和操作区左右排列。其他使用单栏。内容区宽度上限为 1240 逻辑像素 |
| 两种宽屏验收 | 1680×1140 和 2364×1672 是实体像素尺寸。设备像素比为 2 时,完整屏幕约为 840×570 和 1182×836 逻辑像素,实际页面要再考虑系统栏与安全区。两套宿主的 Web 布局及 Android 原生虚拟画布均用这两种尺寸检查,实体平板待验 |
三端功能对照
三端共用 4 个业务 API、9 个视图操作、模型能力字段与错误码。ZIP 通过各平台系统文件选择器获取,三个平台共用解压与入口识别逻辑。动作组和表情由模型文件决定。音频由各系统播放器驱动,声音自然结束用 voiceEnd。只在播放中提交暂停,在暂停后提交继续,以命令回执更新界面。暂停后声音驱动停止,角色动作仍可影响嘴部。
| 平台 | 原生接入与系统要求 | 当前验证 |
|---|---|---|
| Android | OpenGL ES,插件 minSdkVersion 24(Android 7.0),随包提供 arm64-v8a、x86_64 | ZIP 已在 Xiaomi MI 8 的独立 APK 验证系统选取、单模型加载、多模型点选和取消。双宿主生成物完成 Kotlin 联编,集成 ZIP 的完整宿主基座待验 |
| iOS | 默认使用 EAGLContext、CAEAGLLayer 和 AVAudioPlayer。当前 Cubism Core 要求 iOS 26.2 或更新。含设备 arm64 和模拟器 arm64、x86_64 静态切片 | ZIP 原生桥已随双宿主资源导出,静态库三种架构通过 C 接口检查。Apple 最终链接、签名和 iPhone 选择与加载待验 |
| HarmonyOS NEXT | ArkUI XComponent、OpenGL ES 和 OHAudio。两个宿主联编使用 HarmonyOS 6.0/API 20 作为最低目标,提供 arm64-v8a、x86_64 | 双宿主 ZIP 接口通过 ArkTS 编译与 HAP 联编。首帧、动作、表情、触摸及嘴型在 HarmonyOS 5.0.4/API 16 的 x86_64 独立原生壳中完成模拟器验证。鸿蒙设备上的系统选取和 ZIP 加载待验 |
Android 原有模型交互已在 Xiaomi MI 8 的 uni-app x 自定义基座及独立 APK 上验证。传统 Vue3 的公开 API 已使用真实 DCloud Android 运行库联编,并在独立壳验收。完整 App-nvue 宿主页面待验。
资源规格、配置和基座
| 项目 | 要求 |
|---|---|
| 模型包 | 本地标准 .model3.json、当前 Core 支持的 .moc3、PNG 贴图和清单引用资源。清单相对路径保持原层级且不能跳至父目录。入口清单上限 4 MiB,单个模型资源上限 64 MiB,部分资源类型有更小的读取上限。旧版 .moc 请重新导出 |
| 外部压缩包 | 通过 importAvatarZip 选择或读取本地 ZIP,保留文件的相对层级。支持存储、Deflate 和 UTF-8 文件名。禁止加密、分卷、ZIP64、符号链接及路径越界 |
| ZIP 大小和数量 | 原包最多 128 MiB,解压合计 256 MiB,单项 64 MiB,模型清单 4 MiB。最多 2048 个条目、32 份清单,目录深度最多 20 层。压缩包内单个相对路径最多 512 字节 |
| 导入后的文件 | 每次成功导入都有独立的应用私有目录,便于以后加载。卸载视图只释放渲染与音频资源。若宿主需要清理导入文件,可先卸载相关模型,再管理 directory 指向的目录 |
| 本地音频 | 小端有符号 PCM16 WAV、单声道或立体声、8–192 kHz、文件不超过 64 MiB。实际采样率还须被设备播放器接受。嘴型按约 10 ms 音频响度窗口计算,其他动作也可能影响嘴部 |
| Android 平台配置 | uni_modules/lizhao-avatar2d/utssdk/app-android/config.json 中 minSdkVersion 为 24,dependencies 没有附加 Gradle 仓库依赖。原生产物在 uni_modules/lizhao-avatar2d/utssdk/app-android/libs/(由用户准备) |
| iOS 平台配置 | uni_modules/lizhao-avatar2d/utssdk/app-ios/config.json 中 deploymentTarget 为 26.2,frameworks 链接 UIKit、UniformTypeIdentifiers、OpenGLES、GLKit、QuartzCore、AVFoundation、libc++、libz、Metal、MetalKit。默认制品用 uni_modules/lizhao-avatar2d/utssdk/app-ios/Frameworks/Avatar2DGL.xcframework(由用户准备) |
| 鸿蒙平台配置 | uni_modules/lizhao-avatar2d/utssdk/app-harmony/config.json 的 dependencies 将 @lizhao/avatar2d 指向 uni_modules/lizhao-avatar2d/utssdk/app-harmony/libs/lizhao-avatar2d.har(由用户准备) |
| 权限与诊断 | 系统文件选择器只授权选中的 ZIP。读取 App 可访问的本地文件与播放本地音频无需全盘访问、麦克风、相机或联网授权。诊断记录导入来源、数量和错误码,复制前对路径等信息脱敏 |
| 自定义基座 | 首次接入及更新原生 UTS、SO、HAR、XCFramework 时使用重新编译的匹配基座。业务代码或资源可在运行时选择另一个已解压模型 |
下表说明插件从 Cubism 导出的模型清单里读取哪些字段。接入时可打开模型清单核对,字段内容以实际导出结果为准。
| 模型清单字段 | 对应能力 |
|---|---|
Version |
清单格式应为 3 |
FileReferences.Moc、FileReferences.Textures |
必备的模型文件和 PNG 贴图列表,路径相对清单所在目录 |
FileReferences.Motions |
动作组与资源。组内的顺序决定 motion 的索引 |
FileReferences.Expressions |
表情名称与资源。expression 使用清单里的名称 |
FileReferences.Physics、FileReferences.Pose、Layout |
可选的物理、姿态和模型布局设置 |
HitAreas |
点击命中区,hit 回传清单中的区名 |
Groups |
用 Name 为 EyeBlink 或 LipSync 的分组及对应 Ids 提供眼部和嘴部参数 |
已取得许可的开发者可在项目根目录执行下面的原生产物检查。需要从官方 SDK 私有构建时,按注释更换本机路径,保留 SDK 与生成物的合法使用范围。
# 校验插件目录中三端已有的架构和原生文件摘要。
python uni_modules/lizhao-avatar2d/native/check_package.py
# 用指定 SDK、NDK、CMake 和输出目录构建 Android 产物。
node uni_modules/lizhao-avatar2d/native/android/build-libs.cjs --sdk "<SDK目录>" --ndk "<NDK目录>" --cmake "<CMake目录>" --out "<仓外 Android 输出目录>" --abis "arm64-v8a,x86_64"
# 用指定 SDK 和 DevEco Studio 构建鸿蒙 HAR,并选择实际需要的 ABI。
node uni_modules/lizhao-avatar2d/native/harmony/build-har.cjs --sdk "<SDK目录>" --studio "<DevEco Studio 目录>" --out "<仓外鸿蒙输出目录>" --abis "arm64-v8a,x86_64"
将 Android 构建结果按 ABI 放入上表的 libs 目录,鸿蒙 HAR 放到配置指向的位置。iOS 的默认私有构建入口是 uni_modules/lizhao-avatar2d/native/ios-gles/build-private.py,供已有授权 SDK 的开发者使用。本项目保留的可选 Metal 构建入口为 uni_modules/lizhao-avatar2d/native/ios/build-xcframework.sh。
# 用本机的授权 SDK 及编译工具生成默认 iOS 静态 XCFramework。
python uni_modules/lizhao-avatar2d/native/ios-gles/build-private.py --sdk "<SDK目录>" --zig "<Zig 可执行文件>" --cmake-bin "<含 CMake 和 Ninja 的目录>" --ndk "<NDK目录>" --build "<仓外中间件目录>" --output "<仓外输出目录>/Avatar2DGL.xcframework"
SDK 与素材
Cubism SDK 可用于符合官方条款的开发验证。可复用中间件、插件市场分发和终端应用发行需按实际产品与 Live2D 确认许可。虹色Mao、Haru 及示例录音归 Live2D Inc. 所有。工程准备脚本只使用开发者提供的 SDK 目录。 Live2D SDK 许可 · 示例素材条款
作者系列 UTS 插件
| 插件 | 能力方向 | 插件市场 |
|---|---|---|
lizhao-alipay-kit |
支付宝授权登录、App 支付与脱敏诊断 | 查看插件 |
lizhao-app-keepalive |
应用保活、唤醒、自愈与报告 | 查看插件 |
lizhao-apple-iap |
苹果内购、交易恢复、订阅管理与服务端验签参考 | 查看插件 |
lizhao-apple-login |
苹果授权登录、凭证状态与撤销监听 | 查看插件 |
lizhao-bg-audio |
背景音频播放、队列、倍速与事件 | 查看插件 |
lizhao-ble |
BLE 扫描、连接、读写、通知与自动重连 | 查看插件 |
lizhao-call-kit |
电话、短信、通讯录原生能力 | 查看插件 |
lizhao-camera-pro |
原生相机、拍照录像、水印与媒体保存 | 查看插件 |
lizhao-cast-screen |
DLNA 投屏、AirPlay 路由入口 | 查看插件 |
lizhao-choose-file |
原生文件选择、上传、进度与取消 | 查看插件 |
lizhao-device-id |
设备标识、隐私策略与诊断 | 查看插件 |
lizhao-dingtalk |
钉钉授权登录、内容分享与回执诊断 | 查看插件 |
lizhao-doc-corrector |
文档扫描、矫正、增强与识别 | 查看插件 |
lizhao-douyin-kit |
抖音授权登录、内容分享与回执诊断 | 查看插件 |
lizhao-emu-detect |
模拟器环境检测、风险评分与证据 | 查看插件 |
lizhao-float-window |
悬浮窗、画中画、权限与诊断 | 查看插件 |
lizhao-gallery-pro |
相册媒体分页、筛选、缩略图与导出 | 查看插件 |
lizhao-google-login |
Google 授权登录、会话管理与脱敏诊断 | 查看插件 |
lizhao-hce-card |
NFC 虚拟卡、APDU 交互与 NDEF 标签模拟 | 查看插件 |
lizhao-health |
健康数据授权、查询、统计与写入 | 查看插件 |
lizhao-http-server |
本地 HTTP 服务、文件传输与实时通信 | 查看插件 |
lizhao-icon-pro |
SVG 图标组件、多主题与缓存 | 查看插件 |
lizhao-id-photo |
证件照制作、尺寸换算、换底色与模板换装 | 查看插件 |
lizhao-img-eraser |
图片去水印、局部修复与原生编辑器 | 查看插件 |
lizhao-live-activity |
实时活动、系统胶囊与普通通知降级 | 查看插件 |
lizhao-live-photo |
实况照片选取、展示预览与原件处理 | 查看插件 |
lizhao-map |
高德地图、定位、地点搜索、路线规划与导航 | 查看插件 |
lizhao-meta |
Facebook 登录分享、应用事件与深链 | 查看插件 |
lizhao-nfc-pro |
NFC 标签读写、NDEF、IsoDep 与诊断 | 查看插件 |
lizhao-notify-pro |
本地通知、点击动作、进度与定时提醒 | 查看插件 |
lizhao-novel-reader |
原生小说阅读、仿真翻页与段落评论 | 查看插件 |
lizhao-office-view |
Office 与 PDF 文件预览、进度与缓存管理 | 查看插件 |
lizhao-pdf-pro |
PDF 阅读、签批、真实写回与页面处理 | 查看插件 |
lizhao-play-billing |
Google Play 商品购买、订阅、恢复与确认消耗 | 查看插件 |
lizhao-qq-share |
QQ 授权码登录、QQ 与 QQ 空间分享 | 查看插件 |
lizhao-qrcode |
二维码生成、Logo 与样式配置、批量生成及导出 | 查看插件 |
lizhao-scan-pro |
原生扫码、连续扫码、相册识别 | 查看插件 |
lizhao-serial-port |
路径串口、USB 串口、多会话收发与诊断 | 查看插件 |
lizhao-share-plus |
系统分享、远程文件下载后分享 | 查看插件 |
lizhao-smart-tts |
系统 TTS、云端合成、听书方案 | 查看插件 |
lizhao-sqlite-pro |
原生 SQLite、迁移、备份与诊断 | 查看插件 |
lizhao-sse-pro |
SSE、Line、JSONL 与 Raw 流式请求 | 查看插件 |
lizhao-tcp-pro |
TCP 客户端、服务端、多连接与诊断 | 查看插件 |
lizhao-usb-storage |
U 盘、移动硬盘文件浏览、读写与批量复制 | 查看插件 |
lizhao-video-editor |
视频裁剪、压缩、取帧与 FFmpeg/FFprobe | 查看插件 |
lizhao-video-feed |
短视频上下滑、短剧选集与分页加载 | 查看插件 |
lizhao-video-player |
原生视频播放器、清晰度与播放交互 | 查看插件 |
lizhao-video-thumb |
视频封面、批量取帧与 Base64 返回 | 查看插件 |
lizhao-vpn-pro |
企业 VPN、IKEv2、安全接入与脱敏诊断 | 查看插件 |
lizhao-wechat-kit |
微信登录、分享、支付、小程序与客服 | 查看插件 |
lizhao-wecom |
企业微信授权登录、内容分享与脱敏诊断 | 查看插件 |
lizhao-xhs-share |
小红书图文视频分享与回执诊断 | 查看插件 |

收藏人数:
购买源码授权版(
试用
赞赏(0)
下载 6486
赞赏 5
下载 12777488
赞赏 1960
赞赏
京公网安备:11010802035340号