# @amazon/vinyl-xml 中文文档

规范地址：https://npmcn.com/package/%40amazon/vinyl-xml/

版本：5\.0\.0
npm 元数据更新时间：2026-11-16T02:16:38.356Z
中文译文更新时间：2026-11-16T02:20:24.397Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40amazon/vinyl-xml
原文对照：https://npmcn.com/package/%40amazon/vinyl-xml/?lang=original
项目主页：https://github.com/amazonmusic/vinyl#readme
源码仓库：https://github.com/amazonmusic/vinyl

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：529 kB，87 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-05-27T23:27:26.400Z
- 最新版本发布：2026-11-16T02:16:38.000Z
- 近 30 天下载量：2671（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：44（近 12 个月 44 个）

## 中文简介

SAX XML 解析器

## 安装

```sh
npm install @amazon/vinyl-xml
```

也可以使用：`pnpm add @amazon/vinyl-xml`、`yarn add @amazon/vinyl-xml`、`bun add @amazon/vinyl-xml`

## README

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

[![Website](https://img.shields.io/badge/website-amazonmusic.github.io%2Fvinyl-blue)](https://amazonmusic.github.io/vinyl) [![npm](https://img.shields.io/npm/v/@amazon/vinyl-xml.svg)](https://www.npmjs.com/package/@amazon/vinyl-xml) [![size](https://img.shields.io/bundlejs/size/@amazon/vinyl-xml.svg?label=size)](https://bundlejs.com/?q=@amazon/vinyl-xml)

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

## 安装

```shell
npm install @amazon/vinyl-xml
```

## 概览

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

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

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

`MPDType` 示例,后面 [MPDType 定义](https://github.com/Dash-Industry-Forum/MPEG-Conformance-and-reference-source/blob/master/conformance/MPDValidator/schemas/DASH-MPD.xsd)数字 :

```typescript
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 样式指南](https://google.github.io/styleguide/tsguide.html#identifiers-abbreviations) 我们跟随._

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

使用 `mapXmlRules`数字 :

```typescript
const dashDrmRulesMapped = mapXmlRules(dashDrmRules)
```

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

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

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

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

```typescript
const dashManifestHandler = new ParseXmlHandlerImpl(dashDrmRulesMapped)
```

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

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

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

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

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

## 命名空间

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

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

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

命名空间遵循正确的范围界定和默认规则——见 [W3C 光谱](https://www.w3.org/TR/REC-xml-names/)。 。 。 .

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

## 合并Schemas

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

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

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

## 字符串

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

```typescript
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` 对规则的值 配置 .

```typescript
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 是什么？

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 和提交记录判断。

