# @docx4j/jsonix 中文文档

规范地址：https://npmcn.com/package/%40docx4j/jsonix/

版本：3\.13\.0
npm 元数据更新时间：2026-11-07T02:28:55.892Z
中文译文更新时间：2026-11-12T14:44:20.835Z
软件包许可：\(Apache-2\.0 AND BSD-2-Clause\)

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

原始 npm 页面：https://www.npmjs.com/package/%40docx4j/jsonix
原文对照：https://npmcn.com/package/%40docx4j/jsonix/?lang=original
项目主页：https://github.com/plutext/jsonix
源码仓库：https://github.com/plutext/jsonix

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

- 包体积（解压后）：307 kB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-09-14T02:08:47.592Z
- 最新版本发布：2026-11-07T02:28:55.581Z
- 近 30 天下载量：3253（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

Jsonix(为XML的JSON接口)是一个JavaScript库,允许在XML和JSON结构之间转换.

## 安装

```sh
npm install @docx4j/jsonix
```

也可以使用：`pnpm add @docx4j/jsonix`、`yarn add @docx4j/jsonix`、`bun add @docx4j/jsonix`

## README

# 日记

-   Jsonix(为XML的JSON接口)是一个JavaScript库,允许您在XML和JSON结构之间转换.
-   通过 Jsonix 您可以将 XML 解析为 JSON( 这个进程叫做 _解除挂载_)或以 XML 形式将 JSON 序列化(这叫做 _排列_) (中文(简体) ).
-   这些转换是基于可手动写入或由XML Schema生成的可声明的XML/JSON映射.

Jsonix 的优点 :

-   结构严密
-   类型安全
-   双向
-   (可选) XML Schema 驱动

另见其他 [Jsonix 特性](https://npmcn.com/package/%40docx4j/jsonix/#readme-jsonix-features)。 。 。 .

## 示例

这里有个例子 [定购单计划a](http://www.w3.org/TR/xmlschema-0/#po.xsd) (试试看) [在 JSFiddle 网上](http://jsfiddle.net/lexi/LP3DC/)) (中文(简体) ).

### 生成绘图

绘图由单独的 [jsonix-schema- 编译器](https://github.com/highsource/jsonix-schema-compiler) (JDK 11+;其罐子不属于此套件):

```
java -jar jsonix-schema-compiler-full-<VERSION>.jar -d mappings -p PO purchaseorder.xsd [-b bindings.xjb]
```

生成用于 `purchaseorder.xsd` 计划 `mappings/PO.js`; 绘图将放置在变量中 `PO`。 。 。 . 绑定文件( E)`.xjb`)必须使用雅加达命名空间(`xmlns:jaxb="https://jakarta.ee/xml/ns/jaxb"`, (中文(简体) ), `version="3.0"`(中文(简体) ) 含有当前编译器发布; 旧的自定义 `http://java.sun.com/xml/ns/jaxb` 命名空间被默默忽略 .

### 将 XML 分析为 JS

```javascript
// Include or require PO.js so that PO variable is available
// For instance, in node.js:
var PO = require('./mappings/PO').PO;

// First we construct a Jsonix context - a factory for unmarshaller (parser)
// and marshaller (serializer)
var context = new Jsonix.Context([PO]);

// Then we create a unmarshaller
var unmarshaller = context.createUnmarshaller();

// Unmarshal an object from the XML retrieved from the URL
unmarshaller.unmarshalURL('po.xml',
    // This callback function will be provided
    // with the result of the unmarshalling
    function (unmarshalled) {
        // Alice Smith
        console.log(unmarshalled.value.shipTo.name);
        // Baby Monitor
        console.log(unmarshalled.value.items.item[1].productName);
    });
```

你也可以这样 `unmarshalString`, (中文(简体) ), `unmarshalDocument` 和(节点下) `unmarshalFile`。 。 。 .

### 将JS 序列化为 XML

```javascript
// Create a marshaller
var marshaller = context.createMarshaller();

// Marshal a JavaScript Object as XML (DOM Document)
var doc = marshaller.marshalDocument({
    name: {
        localPart: "purchaseOrder"
    },
    value: {
        orderDate: { year: 1999, month: 10, day: 20 },
        shipTo: {
            country: "US",
            name: "Alice Smith",
            street: "123 Maple Street",
            city: "Mill Valley",
            state: "CA",
            zip: 90952
        },
        billTo: { /* ... */ },
        comment: 'Hurry, my lawn is going wild!',
        items: { /* ... */ }
    }
});
```

你也可以这样 `marshalString`。 。 。 .

## 类型脚本

用 `-generateTypeScript` 要在每个映射文件旁边获得描述 jsonix unmarshals 和元帅(`PO.d.ts`) (中文(简体) ). 加上这个包本身的打字,结果不需要投出:

```ts
import { Jsonix } from '@docx4j/jsonix';
import { PO } from './mappings/PO';
import type { PurchaseOrderElement, USAddress } from './mappings/PO';

const context = new Jsonix.Context([PO]);
const element = context.createUnmarshaller().unmarshalString(xml);   // RootElement, inferred from PO
const po = context.createUnmarshaller().unmarshalString<PurchaseOrderElement>(xml).value;
po.shipTo.name;        // string
po.orderDate?.year;    // number | undefined: dates are Jsonix calendars, not JS Dates

const shipTo: USAddress = { name: 'Alice Smith', street: '123 Maple Street', city: 'Mill Valley', state: 'CA', zip: 90952 };
const text = context.createMarshaller().marshalString<PurchaseOrderElement>({
    name: { namespaceURI: '', localPart: 'purchaseOrder' },
    value: { shipTo, billTo: shipTo, items: {} }
});
```

-   解帆归来 `Jsonix.TypedNamedValue<T>`,也就是说. `{ name: QName, value: T }`; 生成的文件异名于此 全球因素`PurchaseOrderElement`作为他们中的所有人`RootElement`) (中文(简体) ). 生成的映射 常数被声明为 `JsonixMapping<RootElement>`,因此从生成的绘图中构建的上下文推断该联盟是 结果 `unmarshal*` 当没有给出类型参数时;一个类型参数会缩小它.
-   无标记物体携带 `TYPE_NAME` (例如:. `'PO.USAddress'`),生成的界面宣布为字面 可用作歧视者的类型。 它对于输入是可选的; 在集合时不需要设置它 .
-   编译器也可以将映射写成ES模块(`<jsonix:output format="esm"/>` 给 `PO.mjs`),这个 软件包有一个ES模块的切入点,所以 `import { Jsonix } from '@docx4j/jsonix'` 在节点无害环境管理和捆绑公司工作.
-   节点和节点捆绑商获得一个输入DOM依赖的静态进口(`jsonix.node.mjs`,由 软件包 `exports` `node` 条件,浏览器的条目为无(`jsonix.mjs`(三); `require()` 保留UMD。 何处 运行时间无法检测其环境(工人、沙箱), `Jsonix.DOM.use({ DOMParser, XMLSerializer, DOMImplementation })` 提供DOM供使用。 在节点中,XML 1.0文本保留了原始的 U+0085和 U+2028 (xmldom 默认值) 会把它们变成线性信号.
-   `context.createUnmarshaller({ onUnexpectedElement, onUnexpectedAttribute })` 报告阅读量下降(不是 校验符:无内容报告的通配符 `onUnexpectedElement` 设置,一个元素 无法持有是 跳过并报告 而不是失败读取, `onOverwrittenElement` 后置元素在 单值财产(最后一项储存,不论有无), `context.createMarshaller({ onElement })` 记录 而错误的输入值名称中的错误 线条。 提供给 `createUnmarshaller` 编号 : `createMarshaller` 仅适用于该呼叫,绝不更改共享 上下文.
-   `new Jsonix.Context(mappings, { parentPointers: true })` 给每个未标记的打字对象一个不可假定的 `PARENT` 指向其包含的打字对象(根对象无),以及 `Jsonix.Util.deepCopy(value, parent?)` 复制子树并重新链接指针, 如 docx4j's `-Xparent-pointer` 编号 : `-Xdocx4j-copy` 型号。 已生成 声明类型 `PARENT` 作为可以包含每种类型的类型结合. `PARENT` 不可见 `for...in`, (中文(简体) ), `Object.keys`JSON和马歇尔.

## Jsonix 特性

-   在几乎所有现代浏览器中运行
-   运行在 [节点.js](http://nodejs.org/)
-   使用通用JS模块、ES模块、AMD模块和香草(全局,没有任何模块加载器)运行
-   由jsonix-schema-编译器生成的申报书所编译的脚本打字(见 [类型脚本](https://npmcn.com/package/%40docx4j/jsonix/#readme-typescript)(中文(简体) )
-   双向(XML - > JS以及JS - > XML)
-   执行 _排列_ (将 JavaScript 对象序列化为 XML)
    -   因此支持字符串数据和 DOM 节点
-   执行 _解除挂载_ (从 XML 分析一个 JavaScript 对象)
    -   支持字符串数据、 DOM 节点、 URL 或文件( 有节点
-   由可控制 JavaScript 对象如何转换成 XML 或反之相向的宣告性 XML/JS 映射驱动
-   绘图可以基于 XML Schema 自动生成
-   强结构 - XML/ 对象映射描述 JavaScript 对象的结构
-   强类型 - XML 侧的字符串内容和JavaScript 侧的值之间的转换由声明属性类型控制
-   提供可扩展类型系统
    -   支持大多数 XML Schema 简单类型( 插入 QNames)
    -   支持列举、列表和联盟简单类型
    -   允许添加自己的简单类型
    -   支持由多个属性组成的复杂类型
    -   扩展后产生的复杂类型支持
-   提供高级财产系统
    -   XML 内容的字符串处理值、 属性、 元素、 元素、 元素参考属性
    -   任意属性, XML 内容的“ 放松” 处理的任何元素属性

## 文档

-   [Jsonix GitHub 项目](https://github.com/highsource/jsonix)
-   [Jsonix 维基百科](https://github.com/highsource/jsonix/wiki)

## 线性

从 [高来源/日索尼克斯](https://github.com/highsource/jsonix) (阿列克谢·瓦利科夫博士) [麻省理工学院的叉子](https://github.com/mitre/jsonix) (单位:千美元)`@mitre/jsonix`页:1 从3.2.0起,由 [插图](https://www.plutext.com/) 时间 [笔迹/jsonix](https://github.com/plutext/jsonix) 发表于 `@docx4j/jsonix`。 。 。 .

## 常见问题

### @docx4j/jsonix 是什么？

Jsonix\(为XML的JSON接口\)是一个JavaScript库,允许在XML和JSON结构之间转换\.

### 如何安装 @docx4j/jsonix？

在项目目录运行 npm install @docx4j/jsonix，或使用 pnpm add / yarn add / bun add。

### @docx4j/jsonix 支持 TypeScript 吗？

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

### @docx4j/jsonix 支持 ESM 还是 CommonJS？

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

### @docx4j/jsonix 可以商用吗？

@docx4j/jsonix 使用 \(Apache-2\.0 AND BSD-2-Clause\) 许可。声明的许可为 \(Apache-2\.0 AND BSD-2-Clause\)，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @docx4j/jsonix 的下载量有多少？

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

### @docx4j/jsonix 还在维护吗？

最新版本 3\.13\.0 发布于 2026/11/07（6 天前）；至今共发布 15 个版本，其中过去 12 个月发布了 15 个；首次发布于 2026/09/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。