HarmonyOS Voxel Kit 版本与变更

这里记录 HarmonyOS Voxel Kit HAR 面向接入方的公开更新内容，按最新优先排列。每个版本都会说明新增能力、修复、兼容性影响和升级时需要注意的事项。

这不是内部研发流水账：内部实现细节、临时调试记录不会在这里出现。这里的目标是让接入方能快速判断“是否需要升级、升级后有什么变化、是否需要调整自己的调用方式”。

如何阅读

本页只记录 HarmonyOS Voxel Kit HAR 的版本变化。VFP 格式和 Python SDK 使用独立版本体系，不应与 HAR 版本混为同一个版本号：

范围	用途	到哪里查看
HarmonyOS Voxel Kit HAR	预览、编辑、导入、导出与 Native 编译能力	本页
VFP 文件格式	文件容器、区段、缓存和兼容性规则	VFP 格式版本历史
Python SDK	Python 读取、转换与工具链	Python 迁移指南

升级 HAR 时，优先查看本页目标版本及其之后的所有条目；若你同时生成或消费 VFP 文件，再核对对应的 VFP 格式版本历史。Python 用户请按迁移指南确认依赖版本与脚本改动。

2.14.3 · 2026-07-28

稳定性修复版本。

• 修复编辑视图连续手势在收尾阶段触发同步控制器逻辑、导致下一次手势首帧卡顿的问题。
• 保留上一版本的双指平移/缩放兼容修复，并统一单指与双指手势结束后的状态清理。
• getCameraTransform() 仍会返回场景最终变换；不再依赖它在手势结束时将状态回写到控制器。

升级影响： 无新增必填配置，也无文件格式变化。若业务侧在手势结束回调里手动再次同步相机，可删除重复同步以避免竞争。

2.14.2 · 2026-07-28

手势与编辑渲染修复版本。

• 修复双指平移或缩放后的可见 Chunk 状态错乱：编辑一个方块时不再意外隐藏其他 Chunk。
• 修复连续手势和选择状态切换时的渲染资源交接。
• 加强手势模式复位，减少旋转、平移、缩放相邻操作之间的状态串扰。

升级影响： 无 API 破坏性变更，建议所有使用编辑模式的项目升级。

2.14.1 · 2026-07-28

交互状态同步修复版本，已被 2.14.3 进一步修正。

• 当手势结束时同步最终场景相机状态，用于避免下一次拖动从旧状态开始。
• 修复编辑进入、选择与操作后的局部场景状态残留。

升级建议： 请直接使用 2.14.3；该版本的同步策略已被后续版本替换。

2.14.0 · 2026-07-28

手势响应与编辑可见性修复。

• 调整手势结束后的相机控制器状态对齐，改善连续拖动体验。
• 修复进入编辑模式、局部修改后 Chunk 可见性异常的路径。
• 保留原有预览与编辑 API。

升级建议： 若曾遇到“第一次操作正常、紧接着第二次操作明显卡顿”，请升级到 2.14.3。

2.13.0 · 2026-07-28

动画、编辑与运行稳定性迭代。

• 优化加载动画收尾与可操作状态的衔接，减少动画结束后的阻塞感。
• 改进编辑状态下的可见 Chunk 管理和选区反馈。
• 继续保持 VFP 只读预览与按需进入编辑模式的分层设计。

2.12.0 · 2026-07-28

大体素模型性能与描边路径迭代。

• 优化 128³ 规格模型的初次渲染、缓存接管和描边生成流程。
• 改进体素边界的光照一致性，避免阴影面描边不受主体明暗影响。
• 优化导入、动画和场景资源分批创建的衔接。

2.11.0 · 2026-07-28

动图导出能力首版。

• 新增 360° 体素转台 GIF 导出能力，支持透明背景、尺寸、帧率、旋转时长和光照等配置。
• 支持从当前视角继承俯仰角和灯光设置，也可覆盖为导出专用参数。
• 导出过程提供进度回调，并针对低差异帧做跳帧/复用优化。

升级影响： GIF 导出属于可选能力，不影响既有预览或编辑调用。

2.10.12 · 2026-07-28

显示同步与 GIF 导出质量修复。

• 完善 Native 光栅导出链路，提升转台 GIF 的抗锯齿、分辨率与颜色稳定性。
• 改进自动旋转的显示同步，减少与手动操作的帧率差异。
• 改进透明背景、模型取景、亮度和导出进度表现。

2.10.11 · 2026-07-28

导出性能与视觉稳定性修复。

• 优化 GIF 编码和帧生成路径，降低导出时间。
• 修复导出画面残影、局部白屏、颜色偏移和亮度跳变等问题。
• 优化模型包围盒取景，减少导出图像中主体过小或四周留白过多的情况。

2.10.10 · 2026-07-28

导出可配置性扩展。

• GIF 导出可继承当前相机俯仰角、自动旋转速度和灯光强度。
• 增加自定义导出速度、光照强度、背景与尺寸的配置能力。
• 导出不再要求先进入编辑模式。

2.10.9 · 2026-07-28

GIF 导出功能完善。

• 修复透明底导出时的颜色、残影和模型比例异常。
• 提升默认输出分辨率与帧率，并改善生成速度。
• 增加导出进度反馈，避免长任务无状态可见。

2.10.8 · 2026-07-28

编辑交互与选择能力迭代。

• 优化框选范围计算、选中高亮和大选区的实时反馈。
• 改进选区批量操作与编辑后 Chunk 更新策略。
• 优化大体素模型首次加载和加载动画阶段的资源准备。

2.10.7 · 2026-07-28

编辑能力对齐迭代。

• 增加多选、框选、按色选择，以及选区批量删除与换色。
• 增加选区移动、复制、镜像、旋转与对齐等操作。
• 编辑能力维持在同一 HAR 中，不需要额外安装编辑扩展包。

2.10.6 · 2026-07-28

保存与导出控制扩展。

• 新增保存、另存为和导出区段选择能力。
• 默认保存遵循导入文件的区段布局；只有明确配置时才重新打包可选缓存或预览区段。
• 支持自由定义放置、替换所使用的体素颜色。

2.10.5 · 2026-07-28

VFP 编辑模式与哈希校验修复。

• 修复部分 VFP 文件进入编辑模式时出现的体素源哈希校验失败。
• VFP 仍默认以只读预览方式加载，只有显式进入编辑模式时才创建编辑文档。
• 改善大模型编辑时的增量更新和点击响应。

2.10.4 · 2026-07-28

HAR 编辑能力首版。

• 将预览器编辑能力纳入 Voxel Kit：点选、选中高亮、放置、替换、删除和基础动画。
• 支持按需启动编辑模式，预览模式不预热编辑资源。
• 增加编辑控制器及编辑状态回调。

2.10.3 · 2026-07-28

组件化与公开配置扩展。

• 增加预览遮罩、提示、Builder 替换和完全自定义 UI 四种接入策略。
• 支持背景色、背景图片、背景图片透明度与深浅主题切换。
• 扩展渲染控制、加载动画、手势灵敏度、缩放范围和自动旋转等配置。

2.10.2 · 2026-07-28

VFP 导入与性能路径扩展。

• 支持 VFP 1.3、VBUF、PMSH、RND0、ANM0 等预计算缓存的读取与渲染接管。
• 支持 THMB 缩略图区段读取。
• 保持 VOXO 作为权威体素数据；缓存不匹配时安全降级为端侧重建。

2.10.1 · 2026-07-28

VFP Reader 与 Native 编译能力首版。

• 新增 VFP 容器读取、区段提取、CRC 校验和基础元数据访问能力。
• 新增 JSON → 最小权威 VFP 的 Native 异步编译入口。
• HAR 内置 ARM64 真机与 x86_64 模拟器所需的 Native 二进制；使用 HAR 即可调用，无需单独分发 SO。

2.10.0 · 2026-07-28

Voxel Kit 包结构升级。

• HAR 从单一预览器升级为 Voxel Kit：VoxelViewer 是其中一项能力，Reader、编译器和后续模块拥有独立入口。
• 对外暴露更稳定的控制器与数据类型，ArkGraphics 内部实现继续保持封装。
• 引入更完整的开发者文档、快速入门与 API 说明。

2.9.0 · 2026-07-27

预览器对外封装与导入简化。

• 将 JSON / VFP 文件选择、读取、解析、场景创建封装进组件，减少业务侧文件处理代码。
• 支持由组件内部处理常见加载状态，或由业务通过回调自行实现。
• 增加组件接入文档和示例工程。

2.8.0 · 2026-07-27

描边与导入链路优化。

• 优先使用体素网格纹理材质描边，避免逐格透明 Geometry 的高开销。
• 支持旧 BORD 缓存回退，同时保证编辑后 Chunk 使用同一描边方案。
• 优化导入、首帧和加载动画阶段的资源交接。

2.7.0 · 2026-07-27

VFP 1.3 导入与缓存兼容。

• 支持新一代 VFP 样本及其缓存区段。
• 修复文件描述符读取、Picker 导入和大文件导入中的异常路径。
• 增强 JSON、VFP 导入后光照和渲染效果的一致性。

2.6.0 · 2026-07-27

VFP 读取与预览基础能力。

• 支持 VFP 容器、目录、CRC、META、PAL0、CHIX、VOXO 与 MSH0。
• 支持缓存命中时直接恢复网格，缓存不匹配时从权威体素数据重建。
• JSON 导入链路保持兼容。

2.5.0 · 2026-07-27

体素展示体验优化。

• 调整初始相机、光照和背景，使 JSON 与 VFP 预览保持相近的显色效果。
• 优化单指旋转、双指平移/缩放、自动 Z 轴旋转和工作台网格。
• 增加多种载入动画与可切换的渲染控制。

2.4.0 · 2026-07-27

大体素模型加载优化。

• 优化 128³ 体素模型的解析、贪心表面生成和分 Chunk 创建。
• 解析、校验和顶点计划尽量转移至异步任务，避免阻塞 ArkGraphics 窗口。
• 增强加载状态与导入错误提示。

2.3.0 · 2026-07-27

体素 JSON 导入与基础编辑。

• 支持 Picker 导入体素 JSON，支持最高 128 的网格规格和较大的文件输入。
• 支持旋转、平移、缩放、点选、放置与删除等基础交互。
• 对外展示体素数量、来源和加载阶段。

2.2.0 · 2026-07-27

VFP Reader 公开能力准备。

• 提供面向 VFP 的解析、读取和区段提取能力。
• 明确将文件格式读取与 HarmonyOS 预览组件分开，便于后续接入其他业务。
• 编译器能力仍通过受控 Native API 提供，不以 ArkTS 源码方式公开实现。

2.1.0 · 2026-07-27

ArkGraphics 体素渲染优化。

• 优化体素面剔除、贪心合并、相机对焦、阴影和边缘表达。
• 修复旋转、平移时残影与可见面异常。
• 支持大模型的渐进创建，降低导入后场景卡顿。

2.0.0 · 2026-07-27

初始公开版本。

• 提供 ArkGraphics 3D 体素预览基础能力。
• 支持 GLB 与体素 JSON 的展示、基础相机手势和光照。

VFP 格式变更

VFP 文件格式不是随 HAR 每次发版一起变化。格式兼容、区段定义、缓存规则和迁移要求请以 VFP 格式版本历史 为准。

特别注意：

• VOXO 是权威体素源；预览、网格、边框、动画等区段是可重建的缓存或辅助数据。
• Reader 在缓存不匹配时会安全降级为从权威体素数据重建，不会把缓存作为唯一真实来源。
• 新增区段应遵循“旧 Reader 忽略未知区段”的兼容原则。

Python SDK 变更

Python 包的发布和迁移说明维护在 Python 迁移指南。当前公开迁移说明以 0.10.0 为基线；升级 Python 依赖前请先核对该页的安装方式、兼容性和脚本替换说明。

后续记录规则

每次公开更新都会在本页顶部新增一项，并至少包含：

1. 版本号与发布日期；
2. 新增能力、修复和行为变化；
3. 兼容性或迁移影响；
4. 必要时的升级建议、回滚提示或关联文档链接。

历史记录只追加，不改写已发布版本的事实；如需更正，会在新版本条目中明确说明。