# @figit/dom-to-figma 中文文档

规范地址：https://npmcn.com/package/%40figit/dom-to-figma/

版本：0\.2\.4
npm 元数据更新时间：2026-08-22T13:08:17.243Z
中文译文更新时间：2026-11-14T17:26:00.109Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40figit/dom-to-figma
原文对照：https://npmcn.com/package/%40figit/dom-to-figma/?lang=original
项目主页：https://github.com/figitdesign/web-to-figma#readme
源码仓库：https://github.com/figitdesign/web-to-figma

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

- 包体积（解压后）：791 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：3 个
- 首次发布：2026-05-19T11:46:41.441Z
- 最新版本发布：2026-08-22T13:08:16.942Z
- 近 30 天下载量：30977（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

在浏览器中将任意 DOM 树转换为 Figma 剪贴板有效载荷 .

## 安装

```sh
npm install @figit/dom-to-figma
```

也可以使用：`pnpm add @figit/dom-to-figma`、`yarn add @figit/dom-to-figma`、`bun add @figit/dom-to-figma`

## README

# @figit/dom-to-figma (英语)

在浏览器中将任意 DOM 树转换为 Figma 剪贴板有效载荷 .

```ts
import { createFigmaConverter } from "@figit/dom-to-figma";

const figma = createFigmaConverter();

const result = await figma.convert({
  element: document.getElementById("design"),
  width: 1280,
  height: 800,
  name: "Hero",
});

await navigator.clipboard.write([result.toClipboardItem()]);
```

贴入法相. 结束了.

## 安装

```sh
pnpm add @figit/dom-to-figma
```

## 它会做什么

行走一棵真正的 DOM 树,读取计算过的样式, 并制作Figma 在粘贴上读取的内容。 文本成为可编辑的文本;图像,向量,梯度,阴影,边框,并形成占位符全部结转.

被斯莱克用于生产,从浏览器直接将设计复制到Figma.

## 版式

默认转换器推断 **本地图像自动显示**:有弹性的容器,平板块流动,包裹行,并网格成为真正的堆栈(`stackMode`,相距相接,相接相接,相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相接相接相接相接相接相接相接相接相相接相接相接相接相相接相接相接相 推论是每个容器的,并对照浏览器所测量到的几何——任何不能完全复制的容器都回落到绝对定位上,因此结果永远不会比固定位置的粘贴更糟糕.

```ts
const figma = createFigmaConverter(); // layout: "auto" (default)
```

过 `layout: "absolute"` 以禁用推断和定位每个框架(1.0前行为):

```ts
const figma = createFigmaConverter({ layout: "absolute" });
```

## 多帧画布

过 `frames` 而不是一个 `element` 将数个 DOM 树复制到一个相片上 :

```ts
const result = await figma.convert({
  frames: [
    { element: a, width: 800, height: 600, x: 0,   y: 0, name: "Hero" },
    { element: b, width: 800, height: 600, x: 900, y: 0, name: "Pricing" },
  ],
  canvasName: "Landing",
});

await navigator.clipboard.write([result.toClipboardItem()]);
```

## 结果形状

```ts
type ConvertResult = {
  document: FigmaClipboard;          // raw node-change document
  bytes: Uint8Array;                 // encoded .fig-style binary
  base64: string;                    // base64 of bytes
  toClipboardItem(): ClipboardItem;  // ready for navigator.clipboard.write
  toClipboardHtml(): string;         // raw HTML envelope Figma reads on paste
};
```

## 跟踪模式

过 `trace: true` 也可以从每个发射的Figma节点取出一张地图,回到它来自的DOM元素. 它默认是关闭的,在被禁用时不增加成本,并且永远不会改变有效载荷字节——它的存在是为了工具(可视的抖动,调试)而不是生产拷贝.

```ts
const figma = createFigmaConverter({ trace: true });
const result = await figma.convert({ element, width: 1280, height: 800 });

for (const entry of result.trace.entries) {
  // entry.guid    → the emitted node's Figma GUID
  // entry.domPath → ":scope > div:nth-child(2) > p:nth-child(1)"
  // entry.rect    → source rect (getBoundingClientRect) at convert time
  // entry.kind / entry.tag / entry.text
}
```

`domPath` 以 `root.querySelector(domPath)` (根元素为: `:scope`) (中文(简体) ). 文本节点带有其所有元素的路径加一 `::text[i]` 后缀,一个文本节点的每个被包裹的行段共享该路径. `result.trace` 实值 `undefined` 除非转换器是用 `{ trace: true }`。 。 。 .

## 自定义装载器

转换器采用三个可选的钩:

```ts
const figma = createFigmaConverter({
  fontLoader,   // (props) => Promise<FontFile>
  imageLoader,  // (req) => Promise<ImageFile>
  classify,     // (element, defaultKind) => ElementKind
});
```

重复 `convert()` 调用相同的转换器再利用缓存字体和图像。 打电话 `figma.clearCache()` 把他们丢掉.

### 字体

默认 : `createFontsourceLoader()` 通过 jsDelivr 的 CDN 从字体源取出字体 。 覆盖所有Google字体外加其他开源家族. 不需要 API 密钥 .

```ts
import { createFontsourceLoader } from "@figit/dom-to-figma";

const figma = createFigmaConverter({
  fontLoader: createFontsourceLoader({ subset: "latin-ext" }),
});
```

对于非fontsource字体,请自写加载器:

```ts
import type { FontLoader } from "@figit/dom-to-figma";

const myFontLoader: FontLoader = async ({ family, weight, italic }) => {
  const url = await myFontCDN(family, weight, italic);
  const response = await fetch(url);
  return { bytes: await response.arrayBuffer() };
};
```

### 图像

默认 : `createDirectImageLoader()` 直接执行 `fetch(src)`。没有CORS的交叉原生图像需要自定义的加载器,一般是代理链:

```ts
import type { ImageLoader } from "@figit/dom-to-figma";

const myImageLoader: ImageLoader = async ({ src }) => {
  const url = `https://my-proxy.example/?url=${encodeURIComponent(src)}`;
  const response = await fetch(url);
  const blob = await response.blob();
  return {
    bytes: await blob.arrayBuffer(),
    mimeType: blob.type,
  };
};
```

软件包内部将WebP/AVIF/etc重新编码为PNG,因此装入器只需要返回生字节和一个MIME类型.

### 分类

`classify` 让您将 DOM 元素映射到 Figma 节点类型 。 默认分类器返回 `text`, (中文(简体) ), `image`, (中文(简体) ), `vector`, (中文(简体) ), `frame`, (中文(简体) ), `group`, (中文(简体) ), `form-with-placeholder`,或 `skip`数字 :

```ts
import type { Classify } from "@figit/dom-to-figma";

const classify: Classify = (element, defaultKind) => {
  if (element.dataset.role === "text-wrapper") {
    return "text";
  }
  return defaultKind;
};
```

## 运行时间要求

在任何现代浏览器中运行. 取决于 `window.getComputedStyle`, (中文(简体) ), `Blob`, (中文(简体) ), `ClipboardItem`, (中文(简体) ), `document.createElement`, (中文(简体) ), `crypto.subtle.digest`, (中文(简体) ), `Image`,以及 `<canvas>`。 。 。 .

## 免责声明

与法格玛无关或得到其认可.

## 常见问题

### @figit/dom-to-figma 是什么？

在浏览器中将任意 DOM 树转换为 Figma 剪贴板有效载荷 \.

### 如何安装 @figit/dom-to-figma？

在项目目录运行 npm install @figit/dom-to-figma，或使用 pnpm add / yarn add / bun add。

### @figit/dom-to-figma 支持 TypeScript 吗？

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

### @figit/dom-to-figma 支持 ESM 还是 CommonJS？

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

### @figit/dom-to-figma 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @figit/dom-to-figma 可以商用吗？

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

### @figit/dom-to-figma 的下载量有多少？

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

### @figit/dom-to-figma 还在维护吗？

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