@amazon/vinyl-xml

中文文档
5.0.0发布于 2026/11/16Apache-2.0TypeScriptESM + CJS构建来源已验证近 30 天下载 2671

SAX XML 解析器

中文使用文档
文档目录10 节
  1. 安装
  2. 概览
  3. 命名空间
  4. 合并Schemas
  5. 字符串
  6. 元素排序
  7. 限制
  8. 父引用
  9. 名称冲突
  10. 许可证

@amazon/ vinyl-xml (中文(简体) )

Website npm size

快速的 SAX XML 解析器, 生成一个类型安全对象 XSD 衍生规则集 。 设计用于解析大型图案重度文档,如 DASH显示的是强烈的静态打字和精确源错误报告.

安装

npm install @amazon/vinyl-xml

概览

要创建用于 schema 的解析器, 首先为形状创建类型定义 页:1.

这样做有很多方法。 我们用的DASH 2011计划 CXSD 软件 (麻省理工学院许可);采用类型定义 并丢弃生成的解析器.

使用类型定义,我们构建一个遵循XSD的规则集. 这是一个 手动进程; 密切跟踪 XSD 以匹配 min编号 :max 发生, 默认,并需要属性.

MPDType 示例,后面 MPDType 定义数字 :

const mpdType: XmlRules<MPDtype> = {
    ProgramInformation: elements(programInformationType),
    BaseURL: elements(baseURLType),
    Location: elements({ _content: charactersString }),
    Period: elements(periodType, { minOccurs: 1 }),
    Metrics: elements(metricsType),
    EssentialProperty: elements(descriptorType),
    SupplementalProperty: elements(descriptorType),
    UTCTiming: elements(descriptorType),
    availabilityEndTime: attrDateTime,
    availabilityStartTime: attrDateTime,
    id: attrString,
    maxSegmentDuration: attr(parseDuration, stringifyDuration),
    maxSubsegmentDuration: attr(parseDuration, stringifyDuration),
    mediaPresentationDuration: attr(parseDuration, stringifyDuration),
    minBufferTime: attr(parseDuration, stringifyDuration, { required: true }),
    minimumUpdatePeriod: attr(parseDuration, stringifyDuration),
    profiles: attr(parseProfiles, stringifyProfiles, { required: true }),
    publishTime: attrDateTime,
    suggestedPresentationDelay: attr(parseDuration, stringifyDuration),
    timeShiftBufferDepth: attr(parseDuration, stringifyDuration),
    type: attr(parsePresentationTypeType, stringify, {
        default: 'static',
    } as const),
} as const

样式注释——缩略语应按 XSD 的缩略语写;如下所示 (b) 报告中提到的例外情况 TS 样式指南 我们跟随.

XmlRules 定义的用意是人类可以读取的,而且易于人们阅读 TypeScript 编译器验证规则是否与类型定义相匹配. 在此规则集被解析器或字符串使用之前, 必须绘制 到一个更能表现的机器化版本.

使用 mapXmlRules数字 :

const dashDrmRulesMapped = mapXmlRules(dashDrmRules)

XmlRules 使用四种规则类型将 XML 内容映射到一个已输入对象:

  • attr ——属性
  • element 最大发生数为1的元素
  • elements - 元素作为数组
  • characters ——文本节点(已压缩)

属性和字符处理器为 序列化/去序列化 XML 的值.

从规则集创建 SAX 解析器的 XML 处理器 :

const dashManifestHandler = new ParseXmlHandlerImpl(dashDrmRulesMapped)

通过处理器,我们可以将 XML 解析成一个经过验证的、 类型安全的物体 匹配我们的类型定义 :

export function parseDashManifest(manifest: string): DashDrmManifest {
    return parseXml(manifest, dashManifestHandler)
}

货币注: 处理器在解析文档时具有状态, 所以如果 多个工人同时解析文件,每名工人创建一个处理器 线程.

整个过程如下: parseXml 给出一个 XML 字符串和一个 内容处理器。 内容处理器抽象地提供了打开和 关闭 XML 节点 。 基于一个 XSD 计划,我们可以构建一个内容处理器 XmlRules 它知道每个节点应该如何处理.

在低层, parseXml 用途 StringParser 以读取 XML 内容。 作为要素 打开并关闭,并读取属性或文本节点,相应的 引用内容处理器方法。 对照《规则》 文档被读取给了解确切的 XML 源的额外好处 无效文档的位置.

命名空间

命名空间不是可选的;如果 XSD 计划使用命名空间,则命名空间 必须在规则中界定.

export const dashNamespaceUri = 'urn:mpeg:dash:schema:mpd:2011'

export const dashManifestXmlRules: XmlRules<DashManifest> = {
    MPD: element(mpdType, {
        required: true,
        namespaceUri: dashNamespaceUri,
    }),
} as const

命名空间遵循正确的范围界定和默认规则——见 W3C 光谱。 。 。 .

对于 XmlRules,除 压倒了。 使用时 stringifyXml,支持定义命名空间前缀 但可选的。 如果未指定前缀, 默认时会生成前缀 没有使用命名空间 .

合并Schemas

在许多情况下,一个XML文档有多个XSD定义. 这些可以合并 使用 mergeXmlRules数字 :

const dashDrmRules = mergeXmlRules(
    dashManifestXmlRules,
    createDashProtectionXmlRules(cencXmlRules),
    createDashProtectionXmlRules(playreadyXmlRules)
)

mergeXmlRules 确保综合计划定义相容。 当 规则代表不同名称空间的 XSD 计划, 那里 通常不会重叠.

字符串

XmlRules 既提供去序列器,又提供序列器, 所以相同的映射规则 集可用于两个内容处理器 parseXml 财务报告和审定财务报表 stringifyXml数字 :

stringifyXml(xmlString, dashDrmRulesMapped)

元素排序

在 XML 计划中,命令事项 xs:sequence 定义。 亚马逊维尼 XmlRules 地图按此顺序定义属性。 秩序无关紧要 解析,但序列化可以通过计划验证. 这意味着 序列化依赖于 ES6 要求对象密钥由 输入。 许多ES5浏览器也遵循了这个规则,但是 stringifyXml 不会 用于浏览器的 spec。 XML 序列化不需要用于 回放——只有去区域化.

限制

解析器目前忽略处理指令,只支持 默认标准 XML 实体 .

父引用

已解析的 XML 节点在不可假定中可以引用其母元素 parent 属性。 使用 clone 工具, 不包括在 JSON.stringify类型定义可包括a parent 属性; 该类型不由规则集执行, 并且预期 对应父元素的类型,或简单 any。 。 。 .

名称冲突

在某些边缘情况下, XSD 可能描述元素或属性规则 无法以属性名称绘制 1: 1 。 案件包括:

  • 儿童元素或属性名称是一个ES6保留词,例如: public, (中文(简体) ), private, (中文(简体) ), get, (中文(简体) ), set等 (中文(简体) ).
  • 这个名字是一个内部保留词: parent 或者说 clone。 。 。 .
  • 子元素本地名匹配属性名 。 在这些情况下,选择 不同的属性名称并提供一个 localPart 对规则的值 配置 .
import { attrString } from '@amazon/vinyl-xml'

type MyType = { _parent: string }

export const myXmlRules: XmlRules<MyType> = {
    _parent: attrString({ localPart: 'parent' }),
} as const

许可证

阿帕奇 - 2.0

版本与发布记录

@amazon/vinyl-xml 共发布 44 个版本,首次发布于 2026/05/28;过去 12 个月发布了 44 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
5.0.0latest2026/11/16今天
4.1.1-next.20261115174554next2026/11/16今天
4.1.1-next.202611151724472026/11/16今天
4.1.1-next.202611151644392026/11/16今天
4.1.1-next.202611150013552026/11/151 天前
4.1.1-next.202611131749092026/11/142 天前

其他发布通道:hotfix-chromos → 1.2.1,hotfix-close-drm-sessions → 1.2.2,next → 4.1.1-next.20261115174554。

关于 @amazon/vinyl-xml 的常见问题

@amazon/vinyl-xml 是什么?

SAX XML 解析器

如何安装 @amazon/vinyl-xml?

在项目目录运行 npm install @amazon/vinyl-xml,或使用 pnpm add / yarn add / bun add。

@amazon/vinyl-xml 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@amazon/vinyl-xml 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@amazon/vinyl-xml 可以商用吗?

@amazon/vinyl-xml 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@amazon/vinyl-xml 的下载量有多少?

根据 npm 官方下载统计,@amazon/vinyl-xml 在 2026/10/06 – 2026/11/04 这 30 天内被下载 2,671 次,日均约 89 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@amazon/vinyl-xml 还在维护吗?

最新版本 5.0.0 发布于 2026/11/16(今天);至今共发布 44 个版本,其中过去 12 个月发布了 44 个;首次发布于 2026/05/28。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。