# @design-parity/adapter-bundle 中文文档

规范地址：https://npmcn.com/package/%40design-parity/adapter-bundle/

版本：1\.18\.0
npm 元数据更新时间：2026-11-07T13:56:30.542Z
中文译文更新时间：2026-11-12T02:05:04.070Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40design-parity/adapter-bundle
原文对照：https://npmcn.com/package/%40design-parity/adapter-bundle/?lang=original
项目主页：https://github.com/yschimke/design-parity/tree/main/packages/adapters/bundle#readme
源码仓库：https://github.com/yschimke/design-parity

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

- 包体积（解压后）：38.8 kB，26 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-06-14T05:42:47.819Z
- 最新版本发布：2026-11-07T13:56:30.215Z
- 近 30 天下载量：3709（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：102（近 12 个月 102 个）

## 中文简介

Image-bundle reference 适配器:解决一个承诺的目录或.zip of reference PNGs外加一个ext.json(通过design-map.json链接),并正常化为DesignReference. 覆盖任何没有读取 API 或 HTML 导出的设计工具—— 仅仅是一个导出堆

## 安装

```sh
npm install @design-parity/adapter-bundle
```

也可以使用：`pnpm add @design-parity/adapter-bundle`、`yarn add @design-parity/adapter-bundle`、`bun add @design-parity/adapter-bundle`

## README

# @ design- parity/ adapter- bundle (英语)

图像组合 [`ReferenceAdapter`](https://npmcn.com/package/core/src/types.ts) 页:1 设计平等。 仅取决于 `@design-parity/core` (加上微小的, 无依赖性 [`fflate`](https://www.npmjs.com/package/fflate) 内存 (原始内容存档于2018-09-29). unzip.

## 原始图像 + 微小显示

有一个真正的工作流程与 **没有设计工具 API 和 HTML 导出**(单位:千美元) 设计师只要交出一个 **一批出口的巴布亚新几内亚** - 已承诺的文件夹或 `.zip` ——直出设计工具. 这个 [`adapter-claude-design`](https://npmcn.com/package/%40design-parity/claude-design) 驱动程序已经 “ 承诺 HTML 导出 + 交接” , 但这超出了本案的需要 。 这个 适配器将其归纳为“绘制图像+一个微小的图像” `manifest.json`",所以这个 包括作为巴布亚新几内亚出口的法格玛/斯地克/克洛德出口,或无任何工具 完全融入.

一样 `linkMethod: "manifest"` (唯一的链接方法是一个没有机器的源 链接可以; 更简单的输入.

```
design-map.json ──▶ fixtures/bundle/offer-card/  ──┐
   (manifest)        (dir or .zip of PNGs)          ├─▶ DesignReference
                       └─ manifest.json ────────────┘     (manifest)
```

## 捆绑

这个 `ref` 内 `design-map.json` 是一条与承诺相对的道路 **目录** 或者说 **`.zip`**。捆绑 持有参考 PNGs + a `manifest.json`数字 :

```json
{
  "componentId": "ui/Card.kt#OfferCard",
  "tokens": { "spacing": { "padding": 16 }, "radius": { "corner": 12 } },
  "images": [
    { "state": "default", "theme": "light", "size": "600px", "path": "offer-card.light.png" },
    { "state": "default", "theme": "dark",  "size": "600px", "path": "offer-card.dark.png" }
  ]
}
```

-   **`images[].path`** ——一PNG,相对于捆接根解决. 内容 `width`编号 :`height` 从巴布亚新几内亚的IHDR中读取 ——因此参考维度永远不能从承诺的字节漂移. ()`width` 编号 : `height` 如果在清单中出现,则会忽略提示。 )
-   **`images[].size`** ——制片方的断点标签,通过canonicalized通过 `normalizeSize` 从 `@design-parity/core` (单位:千美元)`"600px"` → `"medium"`)所以说 捆绑的图像 **组合** 与候选人。 未识别标签被保存 逐字记录.
-   **`tokens`** ——内含 `DesignTokens` 用来检查遵守规定的情况.
-   **`componentId`** ——可选;在提交时必须与组件相匹配 解决者要求, 否则 `resolve` 掷出.

目录捆绑的图像 `uri` 是通往巴布亚新几内亚的相对路径;a `.zip` 捆绑没有独立文件 每个条目,所以 `uri` 是未解析的 PNG 字节 内含为 `data:image/png;base64,…` URI (英语). diff 引擎和 HTML 报告 两种解码 `data:` URIs,所以一个 `.zip` 捆绑是完全可以和可制造的 端对端.

## 使用量

```ts
import { createBundleAdapter } from "@design-parity/adapter-bundle";

const adapter = createBundleAdapter();
const ref = await adapter.resolve(
  "ui/Card.kt#OfferCard",          // resolver-supplied code handle
  "fixtures/bundle/offer-card",    // the design-map ref (dir or .zip, repo-relative)
  { repoRoot: process.cwd(), env: process.env },
);
```

## 错误

`resolve` 扔出一个清晰、前缀、打出的错误( 全部扩展) `BundleError`:

-   `BundleNotFoundError` ——目录 / `.zip` 名称 `ref` 缺少.
-   `BundleManifestError` —— 说 `manifest.json` 不存在 无效 JSON 畸形, 或编号 `componentId` 与解脱相矛盾.
-   `BundleImageNotFoundError` — 显示图像引用未在 捆绑.

一切运行 **离线** ——没有网络,没有模型.

## 常见问题

### @design-parity/adapter-bundle 是什么？

Image-bundle reference 适配器:解决一个承诺的目录或\.zip of reference PNGs外加一个ext\.json\(通过design-map\.json链接\),并正常化为DesignReference\. 覆盖任何没有读取 API 或 HTML 导出的设计工具—— 仅仅是一个导出堆

### 如何安装 @design-parity/adapter-bundle？

在项目目录运行 npm install @design-parity/adapter-bundle，或使用 pnpm add / yarn add / bun add。

### @design-parity/adapter-bundle 支持 TypeScript 吗？

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

### @design-parity/adapter-bundle 支持 ESM 还是 CommonJS？

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

### @design-parity/adapter-bundle 可以商用吗？

@design-parity/adapter-bundle 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @design-parity/adapter-bundle 的下载量有多少？

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

### @design-parity/adapter-bundle 还在维护吗？

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