# @blazediff/object 中文文档

规范地址：https://npmcn.com/package/%40blazediff/object/

版本：1\.8\.0
npm 元数据更新时间：2026-04-07T08:12:12.154Z
中文译文更新时间：2026-11-08T06:29:53.787Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：11.9 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-09-26T14:28:52.559Z
- 最新版本发布：2026-04-07T08:12:12.023Z
- 近 30 天下载量：5876（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 3 个）

## 中文简介

快速对象比较

## 安装

```sh
npm install @blazediff/object
```

也可以使用：`pnpm add @blazediff/object`、`yarn add @blazediff/object`、`bun add @blazediff/object`

## README

# @ blazediff/ 对象

[![npm bundle size](https://img.shields.io/bundlephobia/min/%40blazediff%2Fobject)](https://www.npmjs.com/package/@blazediff/object) [![NPM Downloads](https://img.shields.io/npm/dy/%40blazediff%2Fobject)](https://www.npmjs.com/package/@blazediff/object)

闪电快结构对象与详细变化跟踪的比较.

## 特征

-   **高性能**: 用智能密钥查找策略优化大对象的算法
-   **精确跟踪**: 嵌入对象修改的详细路径跟踪
-   **综合类型**: 处理原始物、对象、阵列、日期、正则ex和循环引用
-   **内存效率**: 具有一致对象形状的最小起落架,用于 V8 优化
-   **循环检测**: 已建成可配置检测的循环参考处理
-   **丰富的输出**: 有类型、路径、值和旧值信息的详细差异对象

## 安装

```bash
npm install @blazediff/object
```

## 快速启动

```typescript
import diff from '@blazediff/object';

const oldObj = {
  name: "John",
  age: 30,
  city: "NYC",
  skills: ["JavaScript", "TypeScript"]
};

const newObj = {
  name: "John",
  age: 31,
  city: "San Francisco",
  skills: ["JavaScript", "TypeScript", "Go"],
  active: true
};

const changes = diff(oldObj, newObj);
console.log(changes);
```

**输出 :**

```json
[
  {
    "type": 2,
    "path": ["age"],
    "value": 31,
    "oldValue": 30
  },
  {
    "type": 2,
    "path": ["city"],
    "value": "San Francisco",
    "oldValue": "NYC"
  },
  {
    "type": 0,
    "path": ["skills", 2],
    "value": "Go",
    "oldValue": undefined
  },
  {
    "type": 0,
    "path": ["active"],
    "value": true,
    "oldValue": undefined
  }
]
```

## API 参考

### `diff(oldObj, newObj, options?)`

比较两个对象并返回一系列差异.

**参数:**

-   `oldObj` (任何):用于比较的原始对象
-   `newObj` (任何):要比较的新对象
-   `options` (对象,可选): 配置选项
    -   `detectCycles` (boolean):启用循环参考检测(默认: `true`(中文(简体) )

**回返情况:**

-   `Difference[]`: 差异对象矩阵

### 类型

Diff 函数返回具有以下结构的相差对象数组:

```typescript
interface Difference {
  type: DifferenceType;
  path: (string | number)[];
  value: any;
  oldValue: any;
}

enum DifferenceType {
  CREATE = 0,  // Property or array element was added
  REMOVE = 1,  // Property or array element was deleted
  CHANGE = 2   // Property or array element value was modified
}
```

**不同类型 :**

-   `0` (CREATE) - 添加属性或阵列元素
-   `1` (REMOVE) - 属性或阵列元素被删除
-   `2` (change) - 修改了属性或阵列元素值

所有相差对象都与 `type`, (中文(简体) ), `path`, (中文(简体) ), `value`,以及 `oldValue` 字段用于优化 V8 性能.

## 使用量

```typescript
import diff from '@blazediff/object';

// Simple property changes
const result = diff(
  { a: 1, b: 2, c: 3 },
  { a: 1, b: 20, d: 4 }
);
// Returns changes for modified 'b', removed 'c', and added 'd'
```

### 嵌入对象

```typescript
// Deep nested changes
const oldData = {
  user: {
    profile: {
      settings: { theme: 'dark', notifications: true }
    }
  }
};

const newData = {
  user: {
    profile: {
      settings: { theme: 'light', notifications: true }
    }
  }
};

const changes = diff(oldData, newData);
// Returns: [{ type: 2, path: ['user', 'profile', 'settings', 'theme'], value: 'light', oldValue: 'dark' }]
```

### 矩阵比较

```typescript
// Array modifications
const changes = diff(
  { items: ['a', 'b', 'c'] },
  { items: ['a', 'x', 'c', 'd'] }
);
// Detects element changes and additions
```

## 常见问题

### @blazediff/object 是什么？

快速对象比较

### 如何安装 @blazediff/object？

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

### @blazediff/object 支持 TypeScript 吗？

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

### @blazediff/object 支持 ESM 还是 CommonJS？

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

### @blazediff/object 可以商用吗？

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

### @blazediff/object 的下载量有多少？

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

### @blazediff/object 还在维护吗？

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