VFP 类型对象

本页集中说明 Reader 返回的值对象。它们是普通 ArkTS 数据对象，不含文件句柄，也不拥有 ArkGraphics 资源。

VfpDocument

字段	类型	含义
majorVersion / minorVersion	number	容器版本。
fileSize	number	读取到的文件长度。
sourceHash	string	Header 中的 32 字节 hash 的十六进制形式。
directoryOffset / directoryLength	number	DIR0 范围。
generation	number	容器 generation。
sections	Array<VfpSection>	目录项。

方法为 findSection(tag, chunkId = -1)、entries(tag)、sectionTags()；它们只查询目录，不读取载荷。

VfpVoxelVolume

字段	类型	含义
gridSize	number	每轴体素网格大小。
chunkSize	number	VFP 数据分块边长。
solidVoxelCount	number	非零调色板索引总数。
voxels	ArrayBuffer	完整线性体素缓冲，0 为空；按索引访问时使用 new Uint8Array(voxels)。

它是编辑、导出或离线分析的对象；预览页面没有必要为了显示模型先调用 decodeVoxels()。

VfpInspection 与 VfpAuthoritativeValidation

VfpInspection 是轻量资产摘要，适合作品列表或导入提示；其缓存布尔值仅表示“存在”。VfpAuthoritativeValidation 则代表 authority 恢复和 source hash 已通过，适用于保存前检查和安全边界。

VoxelLoadResult 与 VoxelPreviewError

VoxelLoadResult 由 Controller 成功加载后返回，字段是 sourceName、sourceFormat、gridSize、voxelCount、surfaceCount、vfpCacheHit。VoxelPreviewError 是 code/message 错误数据模型；实际异步加载仍以抛出的 Error 报告失败，因此应用应捕获 Promise。

使用返回对象构建列表信息

function describeAsset(bytes: ArrayBuffer): string {
  const reader = VoxelKit.createVfpReader();
  const inspection = reader.inspect(bytes);
  const preview = inspection.hasThumbnail ? '有缩略图' : '无缩略图';
  return inspection.gridSize + '³ / ' + inspection.solidVoxelCount + ' 体素 / ' + preview;
}

不要把 VfpSection.offset 等数值当作跨文件永久标识：重编译、增量保存或缓存重建都可能改变目录布局。