# @draftable/compare-api 中文文档

规范地址：https://npmcn.com/package/%40draftable/compare-api/

版本：1\.4\.4
npm 元数据更新时间：2023-01-23T08:01:44.418Z
中文译文更新时间：2026-11-12T18:56:33.566Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40draftable/compare-api
原文对照：https://npmcn.com/package/%40draftable/compare-api/?lang=original
项目主页：https://draftable.com/
源码仓库：https://github.com/draftable/compare-api-node-client

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

- 包体积（解压后）：70 kB，39 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=12\.0\.0
- 运行依赖：1 个
- 首次发布：2017-03-01T06:20:36.853Z
- 最新版本发布：2023-01-23T08:01:44.282Z
- 近 30 天下载量：13752（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 0 个）

## 中文简介

可起草文档比较 API 的客户端库

## 安装

```sh
npm install @draftable/compare-api
```

也可以使用：`pnpm add @draftable/compare-api`、`yarn add @draftable/compare-api`、`bun add @draftable/compare-api`

## README

# 可起草比较 API - Node.js 客户端库

[![npm ver](https://img.shields.io/npm/v/@draftable/compare-api)](https://www.npmjs.com/package/@draftable/compare-api) [![npm nodever](https://img.shields.io/node/v/@draftable/compare-api)](https://www.npmjs.com/package/@draftable/compare-api) [![npm dlm](https://img.shields.io/npm/dm/@draftable/compare-api)](https://www.npmjs.com/package/@draftable/compare-api) [![npm dlt](https://img.shields.io/npm/dt/@draftable/compare-api)](https://www.npmjs.com/package/@draftable/compare-api) [![license](https://img.shields.io/github/license/draftable/compare-api-node-client)](https://choosealicense.com/licenses/mit/)

[![travis](https://api.travis-ci.com/draftable/compare-api-node-client.svg?branch=stable)](https://app.travis-ci.com/github/draftable/compare-api-node-client)

一个细的 JavaScript 客户端 [可起草的 API](https://draftable.com/rest-api) 将所有可用的端点包起来,并处理认证和签名.

见 [aPI 完整文档](https://api.draftable.com/) 用于介绍API、使用说明和其他参考材料.

-   [所需资源](https://npmcn.com/package/%40draftable/compare-api/#readme-requirements)
-   [开始](https://npmcn.com/package/%40draftable/compare-api/#readme-getting-started)
-   [API 参考](https://npmcn.com/package/%40draftable/compare-api/#readme-api-reference)
    -   [初始化客户端](https://npmcn.com/package/%40draftable/compare-api/#readme-initializing-the-client)
    -   [获取比较](https://npmcn.com/package/%40draftable/compare-api/#readme-retrieving-comparisons)
    -   [删除比较](https://npmcn.com/package/%40draftable/compare-api/#readme-deleting-comparisons)
    -   [创建比较](https://npmcn.com/package/%40draftable/compare-api/#readme-creating-comparisons)
    -   [显示比较](https://npmcn.com/package/%40draftable/compare-api/#readme-displaying-comparisons)
    -   [导出比较](https://npmcn.com/package/%40draftable/compare-api/#readme-exporting-comparisons)
    -   [工具函数](https://npmcn.com/package/%40draftable/compare-api/#readme-utility-functions)
-   [其他资料](https://npmcn.com/package/%40draftable/compare-api/#readme-other-information)
    -   [浏览器支持](https://npmcn.com/package/%40draftable/compare-api/#readme-browser-support)
    -   [自签名证书](https://npmcn.com/package/%40draftable/compare-api/#readme-self-signed-certificates)
-   [许可证](https://npmcn.com/package/%40draftable/compare-api/#readme-license)

## 所需资源

-   操作系统:任意维护的 Linux, macOS, 或 Windows 发布
-   节点.js 运行时间: 任意 [维护版本](https://nodejs.org/en/about/releases/)

## 开始

-   创建免费 [API 账户](https://api.draftable.com/)
-   获取你的 [全权证书](https://api.draftable.com/account/credentials)
-   安装库

```sh
npm install @draftable/compare-api
```

-   向客户提供证据

```js
var client = require('@draftable/compare-api').client('<yourAccountId>', '<yourAuthToken>');
var comparisons = client.comparisons;
```

-   开始创建比较

```js
comparisons.create({
    left: {
        source: 'https://api.draftable.com/static/test-documents/code-of-conduct/left.rtf',
        fileType: 'rtf',
    },
    right: {
        source: 'https://api.draftable.com/static/test-documents/code-of-conduct/right.pdf',
        fileType: 'pdf',
    },
}).then(function(comparison) {
    console.log("Comparison created: %s", comparison);
    // Generate a signed viewer URL to access the private comparison. The expiry
    // time defaults to 30 minutes if the valid_until parameter is not provided.
    const viewerURL = comparisons.signedViewerURL(comparison.identifier);
    console.log("Viewer URL (expires in 30 mins): %s", viewerURL);
});
```

## API 参考

-   所有 API 请求返回 _承诺_数字 :
    -   成功调用返回数据决心 `Comparison` 对象
    -   成功调用不返回数据决心 `null` (例如a) `DELETE` 请求)
    -   以任何理由失败的电话会拒绝 `Promise` 带有 `Error` 对象

### 初始化客户端

软件包导出一个创建函数 `Client` 你的API账户.

`Client` 页:1 `comparisons` 属性生成 a `ComparisonsClient` 用于管理您的 API 账户的比较.

创建一个 `Client` 根据使用的 API 端点略有不同 :

```js
// Draftable API (default endpoint)
var comparisons = require('@draftable/compare-api').client(
    '<yourAccountId>',  // Replace with your API credentials from:
    '<yourAuthToken>'   // https://api.draftable.com/account/credentials
).comparisons;

// Draftable API regional endpoint or Self-hosted
var comparisons = require('@draftable/compare-api').client(
    '<yourAccountId>',  // Replace with your API credentials from the regional
    '<yourAuthToken>',  // Draftable API endpoint or your Self-hosted container
    'https://draftable.example.com/api/v1'  // Replace with the endpoint URL
).comparisons;
```

对于 API 您可能需要自行托管 [压制 TLS 证书验证](https://npmcn.com/package/%40draftable/compare-api/#readme-self-signed-certificates) 如果服务器使用自签名的证书(默认值).

### 获取比较

-   `getAll()`  
    回返a `Promise` 它决定了你们所有比较的列表 从最新的到最古老的 这可能是一项昂贵的行动.
-   `get(identifier: string)`  
    回返a `Promise` 解决指定的 `Comparison` 如果指定的比较标识符不存在,则拒绝.

`Comparison` 对象具有下列属性:

-   `identifier: string`  
    比较的独特标识符
-   `left: object` 编号 : `right: object`  
    比较的两边信息
    -   `fileType: string`  
        文件扩展名
    -   `sourceURL: string` _(可选)_  
        如果原始请求由 URL 指定, 文件的 URL
    -   `displayName: string` _(可选)_  
        如果在原始请求中给出文件的显示名称
-   `publiclyAccessible: boolean`  
    说明比较是否公开
-   `creationTime: Date`  
    在协调世界时创建比较的时间
-   `expiryTime: Date` _(可选)_  
    比较期的到期时间
-   `ready: boolean`  
    显示是否准备显示比较

如果有的话 `Comparison` 实值 _准备_ (即已处理)它有下列其他属性:

-   `failed: boolean`  
    显示比较处理失败
-   `errorMessage: string` _(仅在 `failed`(中文(简体) )_  
    比较处理失败

#### 示例用途

```js
var identifier = '<identifier>';

comparisons.get(identifier).then(function(comparison) {
    const visibility = comparison.publiclyAccessible ? 'private' : 'public';
    const status = comparison.ready ? 'ready' : 'not ready';
    console.log("Comparison '%s' (%s) is %s.", comparison.identifier, visibility, status);

    if (comparison.ready && comparison.failed) {
        console.log("The comparison failed with error: %s", comparison.errorMessage);
    }
});
```

### 删除比较

-   `destroy(identifier: string)`  
    回返a `Promise` 如果不存在这种比较,则决定成功删除指定的比较或拒绝.

#### 示例用途

```js
comparisons.getAll().then(function(oldest_comparisons) {
    console.log("Deleting oldest 10 comparisons ...");
    const deleteStartIndex = Math.max(0, oldest_comparisons.length - 10);

    for (let i = deleteStartIndex; i < oldest_comparisons.length; ++i) {
        const identifier = oldest_comparisons[i].identifier;
        comparisons.destroy(identifier).then(function() {
            console.log("Comparison '%s' deleted.", identifier);
        });
    }
});
```

### 创建比较

-   `create(options)`  
    回返a `Promise` 它决定了一个新的 `Comparison` 对象.

`options` 由下列参数组成:

-   `left: object` 编号 : `right: object`  
    描述左右文件(见下文)
-   `identifier: string` _(可选)_  
    用于比较的标识符:
    -   如果指定,标识符必须是独一无二的(即尚未使用)
    -   如果未指定, API 将自动生成一个独特的标识符
-   `publiclyAccessible: boolean` _(可选)_  
    指定比较可见度 :
    -   若为 `false` 查看比较时需要使用或未说明的认证
    -   若为 `true` 任何熟悉 URL 的人都可以访问此比较
-   `expires: Date | string` _(可选)_  
    删除比较的时间 :
    -   必须指定为 `Date` 对象或一个 `string` 可以用 `Date.parse`
    -   如果指明,规定的终止时间必须是世界协调时,而且今后
    -   如果未作说明,比较将永远不会到期(但可明确删除)

`options.left` 财务报告和审定财务报表 `options.right` 由下列参数组成:

-   `source: buffer | string`  
    指定比较的这一侧源 :
    -   提供时 `buffer`,包含文件数据(例如. `{source: fs.readFileSync('path/to/file')}`(中文(简体) )
    -   提供时 `string`,服务器将从中下载文件的URL(例如. `{source: 'https://example.com/path/to/file'}`(中文(简体) )
-   `fileType: string`  
    提交文件的类型 :
    -   PDF : (英语) `pdf`
    -   词: `docx`, (中文(简体) ), `docm`, (中文(简体) ), `doc`, (中文(简体) ), `rtf`
    -   电源点 : `pptx`, (中文(简体) ), `pptm`, (中文(简体) ), `ppt`
    -   文本 : `txt`
-   `displayName: string` _(可选)_  
    比较查看器中显示的文件名称

#### 示例用途

```js
var identifier = comparisons.generateIdentifier();

comparisons.create({

    identifier: identifier,

    left: {
        source: 'https://domain.com/left.pdf',
        fileType: 'pdf',
        displayName: 'Document.pdf',
    },

    right: {
        source: fs.readFileSync('path/to/right/file.docx'),
        fileType: 'docx',
        displayName: 'Document (revised).docx',
    },

    // Expire this comparison in 2 hours (default is no expiry)
    expires: new Date(Date.now() + 1000 * 60 * 120),

}).then(function(comparison) {
    console.log("Created comparison: %s", comparison);
});
```

### 显示比较

-   `publicViewerURL(identifier: string, wait?: boolean)`  
    生成用于指定比较的公共查看器 URL
-   `signedViewerURL(identifier: string, valid_until?: Date | string, wait?: boolean)`  
    为指定的比较生成一个签名的查看器 URL

这两个函数都使用以下共同参数:

-   `identifier`  
    用于生成 _查看器 URL_
-   `wait` _(可选)_  
    指定所提供比较不存在的查看者的行为
    -   若为 `false` 或未说明,如果 `identifier` 不存在
    -   若为 `true`,观看者将等待 与提供的比较 `identifier` 存在  
        注意,如果 `identifier` 从未创建

这个 `signedViewerURL` 函数还支持以下参数:

-   `valid_until` _(可选)_  
    URL 到期时间( 不再装入)
    -   必须指定为 `Date` 对象或一个 `string` 可以用 `Date.parse`
    -   如果指明,规定的终止时间必须是世界协调时,而且今后
    -   如果未指定, URL 将随着默认的30分钟到期生成

参见 [API 文档](https://api.draftable.com/) 其他细节.

#### 示例用途

```js
var identifier = '<identifier>'

// Retrieve a signed viewer URL which is valid for 1 hour. The viewer will wait
// for the comparison to exist in the event processing has not yet completed.
var valid_until = new Date(Date.now() + 1000 * 60 * 60)
var viewerURL = comparisons.signedViewerURL(identifier, valid_until, true);
console.log("Viewer URL (expires in 1 hour): %s", viewerURL);
```

### 导出比较

通过发送比较标识符和所请求的导出类型,导出与PDF的比较.

-   支持四种出口类型.
    -   单页: 仅显示右侧文档并显示显示 diff 的突出显示和删除标记
    -   组合:显示左右两侧
    -   左: 只显示左侧
    -   右: 只显示右侧

在创建导出后, 您必须使用导出标识符进行投票以获取导出文档的 URL .

`Export` 对象具有下列属性:

-   `identifier: string` 导出的唯一标识符
-   `comparison: string` 比较的独特标识符
-   `url: string`  
    如果原始请求由 URL 指定, 文件的 URL
-   `kind: string` 导出类型,以下一种 `single_page`, (中文(简体) ), `combined`左侧或 `right`
-   `ready: boolean` 说明出口是否准备得到
-   `failed: boolean` 显示导出失败

#### 导出示例使用

出口后要求

```js
client.exports
  .requestExport({
    comparison: "<identifier>",
    kind: "combined",
    include_cover_page: false,
  })
  .then((result: ExportResult) => {
    console.log(result);
  }
```

获取请求导出

```js
client.exports.get(requestResponse.identifier).then((result: ExportResult) => {
    console.log(result);
  });
```

### 工具函数

-   `generateIdentifier()`  
    生成随机唯一比较标识符

## 其他资料

### 浏览器支持

此库主要为服务器侧使用而设计. 目前不支持在网页浏览器(客户端-侧面)中使用.

通过客户端 JavaScript 调用可起草的 API 被普遍劝阻,因为这意味着与最终用户共享 API 证书 .

### 自签名证书

如果连接到一个使用自签名证书( 默认) 的 API 自动托管端点, 您需要压制证书验证 。 可以通过设置 `NODE_TLS_REJECT_UNAUTHORIZED` 环境变量改为 `0`。 。 。 .

不同操作系统和 shell 环境的示例如下. 注意所有实例只设置运行中 shell 的变量, 它不会持久 。 要坚持设置, 请查看您的外壳环境的文档 。 应当谨慎行事,因为此设置会压制证书的验证 **全部** 节点运行时的连接 !

(ba)sh (Linux, macOS, WSL) (英语)

```sh
export NODE_TLS_REJECT_UNAUTHORIZED=0
```

动力壳:

```posh
$env:NODE_TLS_REJECT_UNAUTHORIZED=0
```

命令提示( 窗口) :

```cmd
SET NODE_TLS_REJECT_UNAUTHORIZED=0
```

在生产环境中设置这种环境可变因素会大大降低安全性,因此受到强烈的阻碍。 我们只建议在开发环境中设置这个环境变量,前提是无法配置一个 CA 签名的 API 自我托管证书 .

## 许可证

所有内容都根据以下条款获得许可: [麻省理工学院许可证](https://npmcn.com/package/%40draftable/compare-api/LICENSE)。 。 。 .

## 常见问题

### @draftable/compare-api 是什么？

可起草文档比较 API 的客户端库

### 如何安装 @draftable/compare-api？

在项目目录运行 npm install @draftable/compare-api，或使用 pnpm add / yarn add / bun add。

### @draftable/compare-api 支持 TypeScript 吗？

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

### @draftable/compare-api 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @draftable/compare-api 需要什么版本的 Node\.js？

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

### @draftable/compare-api 可以商用吗？

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

### @draftable/compare-api 的下载量有多少？

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

### @draftable/compare-api 还在维护吗？

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