Reader API 概览

VfpPackageReader 是 Voxel Kit 中独立于 ArkGraphics 的 VFP 读取器。它适合放在文件信息页、导入前检查、资产目录、分享流程或未来格式工具中：即使页面没有挂载 VoxelViewer，也可以读取 VFP 的版本、目录、META、已附带的 GLB 预览和资源卡片缩略图。

Reader 能做什么

任务	Reader 提供的能力
判断一份字节是否为支持的 VFP	Header、最终 Footer、DIR0、版本、范围和目录 CRC 解析
检查文件在传输后是否完整	validate() 校验每个存储态区段的 CRC
展示资产概要	VfpDocument 提供版本、generation、source hash、区段目录
读取 META 或其他文本区段	extractTextByTag()、readManifestText()
取得原始区段	extractSection()、extractByTag() 返回独立的 ArrayBuffer
取得已有预览模型	extractPreviewGlb() 验证并返回 PRVW 内嵌 GLB 2.0
取得资产卡片缩略图	extractThumbnail() 验证并返回 THMB 内嵌 PNG、像素尺寸和独立字节

Reader 不做什么

Reader 只处理容器和存储态区段。它不会解码 VOX0、不会解析 PAL0 语义、不会重算 source hash，也不会从体素数据生成 GLB 或写回 VFP。因此“validate() 成功”表示目录与每个已存区段没有 CRC 损坏，不是“模型的权威体素内容已经被完整验证”。

这项边界让 Reader 能保持轻量，也避免业务代码误把预览缓存当作编辑源。详细原因见 VFP 可信边界。

与 VoxelViewer 如何配合

你的页面目标	推荐组合
只展示 3D 模型	仅用 VoxelViewerController.loadUri()
先展示文件版本、META、区段，再由用户点击预览	Reader 读取 URI，再按需用 Viewer 载入同一 URI
在 Picker 导入后做完整性检查再允许分享	readUri() → validate() → 业务保存/分享
取出嵌入 GLB 交给业务文件服务	Reader；不需要 Viewer
在作品列表显示 VFP 自带封面	Reader 提取 THMB；不需要 Viewer

parseUri() / validateUri() 只返回目录，不保留原始文件字节。如果下一步要提取区段，应先使用 readUri() 保存返回的 ArrayBuffer，再多次调用解析/提取方法。

最小示例

import { VoxelKit, VfpPackageReader } from 'voxel-kit';

const reader: VfpPackageReader = VoxelKit.createVfpReader();
const bytes = await reader.readUri(uri);
const document = reader.validate(bytes);

console.info(`VFP ${document.majorVersion}.${document.minorVersion}`);
console.info(`区段：${document.sectionTags().join(', ')}`);
console.info(reader.readManifestText(bytes));

if (document.findSection('THMB')) {
  const thumbnail = reader.extractThumbnail(bytes);
  console.info(`缩略图：${thumbnail.width}×${thumbnail.height}`);
}

THMB 只用于文件列表、最近文件或资产详情卡片。VoxelViewer 在导入模型时刻意不读取它， 因此缩略图的存在、缺失或损坏都不影响 PMSH/VOX0 正式预览的首帧。

接下来请阅读 VFP Reader API。该页会逐项说明所有公开方法的输入、返回、校验范围、抛错条件及可直接复制的组合示例。