HarmonyOS Voxel Kit 版本与变更

2.17.0 — 连续放置与本地优化（2026-09-10，本地候选）

• 新增 ADD_BRUSH，或在 ADD 中启用 addBrushEnabled；按笔撤销、固定源表面防止自堆叠、双指相机交接。
• 新增 19 类结构/颜色一键优化，可设置参数、按选区处理、锁定颜色、先计算候选后应用，以及撤销/重做。
• 修复地面网格异步重复创建造成关闭残留；关闭脱挂、打开复用。
• 批量优化按受影响 Chunk 同步，避免逐体素渲染更新。未修改 VFP 标准、Native ABI 和编译器闭源边界。
• 详见 使用指南 与 API。本版本未在本次任务中发布 OHPM/部署真机，不能将本地构建记录视为线上可安装状态。

这里记录 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.16.4 · 2026-08-12

修复缓存 VFP 的批量改色闪烁。

• 首次编辑会建立完整可编辑 Chunk 代际并退休 PMSH 预览基线，避免旧颜色与新颜色在同一深度平面随视角交替出现。
• 后续编辑仍只更新受影响 Chunk。首次实际编辑需要一次性建立 Chunk 资源，建议在真机确认该首次成本。

2.16.3 · 2026-08-12

增强默认工作室的正反面辅光。

• 默认 fill/rim 辅光提高，改善模型正面和背面暗部的可读性。
• 环境底色、曝光和主光不变，仍保留顶部及侧面的明暗层次。

2.16.2 · 2026-08-12

修复单指上下 Orbit 方向。

• 手指向下拖动现在对应相机俯仰正向移动；预览、编辑及 SELECT_BRUSH 空白起手完全一致。
• 横向旋转、双指相机、自动旋转和编辑选择策略没有变化。

2.16.1 · 2026-08-06

对齐刷选、自动旋转与相机横向手感。

• SELECT_BRUSH 只在首指按下命中可见体素表面时开始；从空白画布起手的单指拖动恢复为普通相机环绕，不会修改选区或写入编辑历史。
• 预览、编辑与 SELECT_BRUSH 空白起手统一横向 yaw 方向。
• 自动 Z 旋转在任意单指、双指或框选触摸期间暂停；所有触点结束或取消后从当前角度恢复，autoRotate 开关值保持不变。

兼容性： 不需要修改现有 API 调用；升级后空白画布拖动不再可能误建刷选笔画。

2.16.0 · 2026-08-06

SELECT_BRUSH 可选手势桥接。

• 新增 VoxelSelectionGestureOptions、VoxelSelectionGesturePhase 和 VoxelSelectionGestureState，以及 Controller 的设置、读取和复位方法。
• 显式开启后，单指刷选会经 BRUSHING 状态进入；第二根手指会同步完成当前笔画后进入 CAMERA，可分别控制双指平移、缩放和旋转。
• 新增 VoxelGestureLockOptions.twoFingerRotation 末位参数；rotation=true 同时锁定单指和桥接双指旋转，已有五参数调用保持可用。

兼容性： 默认桥接关闭，已有 SELECT_BRUSH、双指平移/缩放和 Editor 配置均不变。只有需要状态回调或双指旋转的页面才需要显式创建并传入 VoxelSelectionGestureOptions。

2.15.1 · 2026-08-05

Viewer 显示区域圆角改为显式配置，默认直角。

• 新增 VoxelViewerOptions.cornerRadius，默认 0。默认 Viewer 不再为 ArkGraphics Surface 应用内部圆角裁剪。
• 设置正数时，模型、背景与 HAR 内置遮罩会使用同一裁剪半径；宿主不需要通过外层 .borderRadius() / .clip() 尝试覆盖组件内部行为。
• VoxelLoadOverlayStyle.borderRadius 保持只影响加载提示卡片，不会改变模型显示区域。

兼容性： 这是一次默认视觉边界调整。此前依赖隐式 20vp 圆角的页面，请显式设置 options.cornerRadius = 20；其他调用无需修改。

2.15.0 · 2026-08-05

编辑滑选与屏幕拾取公开能力。

• 新增 VoxelEditMode.SELECT_BRUSH：用户单指滑过可见表面时连续选择体素。路径采样、单笔去重和逐帧高亮合并均在组件内完成。
• VoxelEditorOptions 新增 selectBrushAppend（默认 true）与 onSelectBrushHit(x, y, z)。前者控制每笔是否保留已有选区，后者可用于宿主的轻量反馈。
• 新增 VoxelEditorController.pickVoxelAt(screenX, screenY)，供宿主以 Viewer 本地像素坐标进行只读表面拾取。
• 统一滑选、框选与双指手势的交接：第二根手指落下会结束当前选区手势，再进入双指平移/缩放；rotation 锁仍只影响单指旋转。

兼容性： 完全向前兼容。SELECT 保持“单击切换选中”的原语义，未启用 SELECT_BRUSH 的现有接入不需要改动。升级后若要使用宿主屏幕拾取，坐标必须传入 Viewer 内容区域内的本地像素值。

2.14.15 · 2026-07-29

VFP Orientation Profile v1 对齐。

• Native Compiler 的 META 与 SCNE 现在明确写入 axisConvention：+Z 向上、+Y 向前、右手系；这补齐了仅有 coordinateSystem='Z_UP' 时无法确定前后方向的问题。
• SCNE.camera.yaw=0 在 Viewer 中统一为从模型源空间 +Y 正前方朝向 Pivot；正 yaw 从 +Y 向 +X 旋转，正 pitch 向 +Z 抬升。
• VfpPackageReader.readAxisConvention() 与 VfpAxisConvention 可供业务读取该约定。GLTI 内嵌 VFP 扩展也同步携带 source-axis 元信息。

兼容性： 向前兼容。Header、目录、VOX0、sourceHash 与既有 ArkTS 加载 API 不变；未携带 axisConvention 的历史 VFP 1.3 按相同默认值解释。显式但不完整或不支持的方向对象会被拒绝，避免静默镜像或从背面取景。

2.14.14 · 2026-07-29

VFP 编辑缓存接管优化。

• 对携带并命中有效 VBUF/PMSH 的 VFP，enterEdit() 保留 PMSH 的完整预览基线，不再为了进入编辑预热全量占用 Chunk。
• 第一次编辑只创建受影响的 16³ 局部覆盖层；未修改区域持续由原始 PMSH 基线显示，避免全模型接管带来的进入编辑等待。
• JSON、缓存缺失或缓存未命中的路径仍会按需准备编辑 Chunk，确保编辑数据与可见表面一致。

兼容性： 向前兼容。公开 ArkTS API、VFP 1.3 权威数据和保存语义均未改变；接入方仍必须 await enterEdit()，不得根据 chunkSize 自行判断编辑已就绪。

2.14.8 · 2026-07-29

GLTI 展示交付扩展。

• VoxelGltiExportOptions 新增 embedEditableVfp，默认 true，保持既有 GLTI 内嵌原始 VFP、可由 GltiPackageReader 恢复的行为。
• 显式设为 false 时，输出仍包含 H.264/MP4 与标准 GLB，但不含 CHARACTECH_voxel_vfp 私有扩展或原始体素工程；适用于保存到相册、公开分享和作品展示。
• 展示专用文件被 GltiPackageReader.extractVfp() 拒绝是预期行为，不能通过视频或 GLB 反推出可编辑工程。

升级影响： 没有破坏性变更。已有 GLTI 调用无需修改；当业务策略要求不保留编辑源时，显式设置 embedEditableVfp = false。系统相册保存和用户授权仍由宿主应用负责。

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. 必要时的升级建议、回滚提示或关联文档链接。

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