# @ungap/structured-clone 中文文档

规范地址：https://npmcn.com/package/%40ungap/structured-clone/

版本：1\.4\.0
npm 元数据更新时间：2026-08-27T08:46:13.050Z
中文译文更新时间：2026-11-05T15:17:12.339Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：29.7 kB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2021-10-29T18:41:57.090Z
- 最新版本发布：2026-08-27T08:46:12.636Z
- 近 30 天下载量：371423528（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 5 个）

## 中文简介

结构化克隆多填充

## 安装

```sh
npm install @ungap/structured-clone
```

也可以使用：`pnpm add @ungap/structured-clone`、`yarn add @ungap/structured-clone`、`bun add @ungap/structured-clone`

## README

# 结构化 Clone 多填充

[![Downloads](https://img.shields.io/npm/dm/@ungap/structured-clone.svg)](https://www.npmjs.com/package/@ungap/structured-clone) [![build status](https://github.com/ungap/structured-clone/actions/workflows/node.js.yml/badge.svg)](https://github.com/ungap/structured-clone/actions) [![Coverage Status](https://coveralls.io/repos/github/ungap/structured-clone/badge.svg?branch=main)](https://coveralls.io/github/ungap/structured-clone?branch=main)

具有再生能力和外型的可知序列器和去序列器 _贾森_ 从 _HTML 语言_ 标准本身.

-   [支持类型](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types)
    -   _尚未支持_: Blob、 文件、 文件列表、 图像比特地图、 图像数据或其他非 _联合来文_ 类型但打入的数组在没有重大问题的情况下支持,但u/int8、u/int16和u/int32是唯一安全的上接(现在).
    -   _无法执行_页:1 `{transfer: []}` 选项可以被通过,但它被完全忽略.
-   [MDN 文档](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone)
-   [序列器](https://html.spec.whatwg.org/multipage/structured-data.html#structuredserializeinternal)
-   [减序器](https://html.spec.whatwg.org/multipage/structured-data.html#structureddeserialize)

串行值可以安全地被字符串为 _贾森_ 以及去区域化 复活所有价值 甚至递归性 或比什么更复杂 _贾森_ 允许.

### 实例

检查 [100%的测试覆盖率](https://npmcn.com/package/%40ungap/structured-clone/test/index.js) 要知道更多的东西.

```js
// as default export
import structuredClone from '@ungap/structured-clone';
const cloned = structuredClone({any: 'serializable'});

// as independent serializer/deserializer
import {serialize, deserialize} from '@ungap/structured-clone';

// the result can be stringified as JSON without issues
// even if there is recursive data, bigint values,
// typed arrays, and so on
const serialized = serialize({any: 'serializable'});

// the result will be a replica of the original object
const deserialized = deserialize(serialized);
```

#### 全球多元填充

注意: 如果需要, 只有猴子补丁全局 。 这种多填充效果只是一个明确的导入: `import structuredClone from "@ungap/structured-clone"`

```js
// Attach the polyfill as a Global function
import structuredClone from "@ungap/structured-clone";
if (!("structuredClone" in globalThis)) {
  globalThis.structuredClone = structuredClone;
}

// Or don't monkey patch
import structuredClone from "@ungap/structured-clone"
// Just use it in the file
structuredClone()
```

**说明**: 不要将本模块默认导出直接附加到全局范围, 请设置一个条件性守护以检测本地执行 。 在全球各地实施 `structuredClone()` 指派到全局对象后,将产生无限循环 `globalThis.structuredClone()` 名为. 参见上面的例子,以安全的方式提供您项目中的多填充.

### 额外特性

结构化克隆算法和JSON之间没有中间地层:

-   JSON对不兼容的价值观比较放松:它只是忽略了这些
-   结构化克隆在不兼容的价值观上是僵硬的,然而它却使得专门的例子无法重建,再加上它不提供任何帮助者,例如: `toJSON()`,使有具体案例的序列化成为可能或更好

本单元专门 `serialize` 在可选附加参数中,导出要约 a **损失** 属性,以避免在道路上找到不兼容类型(功能、符号.)时扔出,这样就可以在发送时减少对抛出错误的担心.

```js
// as default export
import structuredClone from '@ungap/structured-clone';
const cloned = structuredClone(
  {
    method() {
      // ignored, won't be cloned
    },
    special: Symbol('also ignored')
  },
  {
    // avoid throwing
    lossy: true,
    // avoid throwing *and* looks for toJSON
    json: true
  }
);
```

行为也一样 _贾森_ 当它涉及到 _阵列_,这样,不支持的值将因 `null` 占位符代替.

#### 给杰森

若为 `lossy` 选项是不够的, `json` 将实际执行 `lossy` 检查 `toJSON` 用于分析对象的方法.

备选案文 `json` 出口将所有特性结合起来:

```js
import {stringify, parse} from '@ungap/structured-clone/json';

parse(stringify({any: 'serializable'}));
```

## 常见问题

### @ungap/structured-clone 是什么？

结构化克隆多填充

### 如何安装 @ungap/structured-clone？

在项目目录运行 npm install @ungap/structured-clone，或使用 pnpm add / yarn add / bun add。

### @ungap/structured-clone 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/ungap\_\_structured-clone 是否存在。

### @ungap/structured-clone 支持 ESM 还是 CommonJS？

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

### @ungap/structured-clone 可以商用吗？

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

### @ungap/structured-clone 的下载量有多少？

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

### @ungap/structured-clone 还在维护吗？

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