# @bgotink/kdl 中文文档

规范地址：https://npmcn.com/package/%40bgotink/kdl/

版本：0\.4\.1
npm 元数据更新时间：2026-10-13T19:26:25.267Z
中文译文更新时间：2026-11-08T00:59:13.396Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：346 kB，95 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2022-06-26T12:41:43.759Z
- 最新版本发布：2026-10-13T19:26:24.942Z
- 近 30 天下载量：132903（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 4 个）

## 中文简介

方便修改的 KDL 解析器和序列器.

## 安装

```sh
npm install @bgotink/kdl
```

也可以使用：`pnpm add @bgotink/kdl`、`yarn add @bgotink/kdl`、`bun add @bgotink/kdl`

## README

# `@bgotink/kdl`

此软件包包含一个解析器和字符串 [KDL 文档语言](https://kdl.dev/),一种以节点为基础,方便人类的配置和串行格式.

此软件包中的解析器注重以允许格式保留修改的方式解析文档. 这在与人类维护的KDL文件合作时最为有用.

## 安装

```sh
yarn add @bgotink/kdl
# or
npm install @bgotink/kdl
# or
pnpm add @bgotink/kdl
# or ...
```

## 使用量

以下例子假设一个节点.js环境. 这个 `@bgotink/kdl` 软件包在任何javascript运行时间,包括浏览器中工作,只要它支持相对现代的浏览器标准. 如果您想在非节点运行时运行这些样本,请将输入替换为 `assert` 和你的运行时间相当的东西.

```js
import {parse, format} from "@bgotink/kdl";
import assert from "node:assert/strict";

const doc = parse(String.raw`
    node "value" #"other value"# 2.0 4 #false \
            #null -0 {
        child; "child too"
    }
`);

doc.nodes[0].children.nodes[0].entries.push(
    parse(
        String.raw`/-lorem="ipsum" \
            dolor=#true`,
        {as: "entry"},
    ),
);

assert.equal(
    format(doc),
    String.raw`
    node "value" #"other value"# 2.0 4 #false \
            #null -0 {
        child /-lorem="ipsum" \
            dolor=#true; "child too"
    }
`,
);
```

## JSON-in-KDL(吉克语)

此套件导出功能来自 `@bgotink/kdl/json` 以 JSON- in- KDL (JiK) 4. 0. 关于格式的资料,见 [jiK 4.0.0 规格](https://github.com/kdl-org/kdl/blob/76d5dd542a9043257bc65476c0a70b94667052a7/JSON-IN-KDL.md)。 。 。 .

```js
import {parse} from "@bgotink/kdl/json";
import assert from "node:assert/strict";

assert.deepEqual(
    parse(
        String.raw`
            - {
                prop #false
                otherProp {
                    - 0
                    - 2
                    - 4
                }
            }
        `,
    ),
    {
        prop: false,
        otherProp: [0, 2, 4],
    },
);
```

有四项职能:

-   `parse` 财务报告和审定财务报表 `stringify` 将文本转换为编码的 JSON 值并返回。 这些功能对于编码/解码整个JiK文件很有用.
-   `toJson` 财务报告和审定财务报表 `fromJson` 将 KDL 节点转换为编码后的 JSON 值并返回 。 这些函数对输出提供了更精细的控制,可用于例如嵌入到KDL文档的JiK节点的编码/解码.

## (去)序号

该软件包包含用于(去)串行化的公用事业 `@bgotink/kdl/dessert`。 。 。 .

```js
import {parse} from "@bgotink/kdl/dessert";
import assert from "node:assert/strict";

assert.deepEqual(
    parse(
        String.raw`
            name "my-package"
            
            dependency "@bgotink/kdl" range="^0.2.0"
            dependency "prettier" range="^3" dev=#true
        `,
        (ctx) => {
            const dependencies = {};
            const devDependencies = {};

            const name = ctx.child.single.required("name", (ctx) =>
                ctx.argument.required("string"),
            );

            for (const dependency of ctx.children("dependency", (ctx) => ({
                name: ctx.argument.required("string"),
                range: ctx.property("range", "string") ?? "*",
                dev: ctx.property("dev", "boolean") ?? false,
            }))) {
                (dependency.dev ? devDependencies : dependencies)[dependency.name] =
                    dependency.range;
            }

            return {name, dependencies, devDependencies};
        },
    ),
    {
        name: "my-package",
        dependencies: {
            "@bgotink/kdl": "^0.2.0",
        },
        devDependencies: {
            prettier: "^3",
        },
    },
);
```

## KDL v1 数据

软件包导出两个函数 `@bgotink/kdl/v1-compat` 以支持 KDL v1 中写入的文档 :

-   `parse` 剖析 KDL v1 文档,并将所有链接的格式信息转换为有效的 KDL v2 文档 . 如果产生的文件被传递到 `format()`,生成的字符串将是同一个文档,但在 KDL v2 语法中。 其中将包括原始文件作者采用的所有评论和格式.
-   `parseCompat` 剖析 KDL v2 或 KDL v1 的文档, 并返回有效的 KDL v2 文档 . 这是一个结合正则 `parse` 与 v1 兼容的函数 `parse` 函数为支持两种格式的单一函数.

## 基尔克

这个软件包将 KDL 文档转换为 JavaScript 对象,反之亦然. 因此受到JavaScript语言的限制.

### 属性

允许多个同名属性. 将保留所有复制文件,这意味着这些文件将正确往返。 使用时 `node.getProperty()`编号 :`node.getProperties()`编号 :`node.getPropertyEntry()`中,最后一个有该名称值的属性将被返回,从而有效地阴影了任何先前的重复。 使用 `node.getPropertyEntries()`编号 :`node.entries` 确实暴露了阴影的复制品, 把它留给呼叫者来处理。 通过节点 `clearFormat()` 删除这些阴影复制件.

### 数字

JavaScript 将所有数字存储为 64 位 [IEEE 754 (英语)](https://en.wikipedia.org/wiki/IEEE_754) 浮点数. 这限制了哪些整数可以安全使用. 这些限制比您可能预期的要低,如果您习惯于在一个单独的64位整数数据类型的环境中工作.

原表示的解析数字予以保留,除非 `clearFormat` 使用该值或含有该值的任何条目/节点/文档.

## 许可证

这个包裹根据麻省理工学院的许可获得许可,可以在 `LICENSE.md`。 。 。 .

测试套房在 `test/upstream` 属于 [KDL 规格](https://github.com/kdl-org/kdl) 依据创用CC授权使用.

## 常见问题

### @bgotink/kdl 是什么？

方便修改的 KDL 解析器和序列器\.

### 如何安装 @bgotink/kdl？

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

### @bgotink/kdl 支持 TypeScript 吗？

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

### @bgotink/kdl 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bgotink/kdl 可以商用吗？

@bgotink/kdl 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bgotink/kdl 的下载量有多少？

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

### @bgotink/kdl 还在维护吗？

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