# @apostrophecms/import-export 中文文档

规范地址：https://npmcn.com/package/%40apostrophecms/import-export/

版本：3\.7\.1
npm 元数据更新时间：2026-10-20T16:55:29.692Z
中文译文更新时间：2026-11-06T11:06:49.315Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40apostrophecms/import-export
原文对照：https://npmcn.com/package/%40apostrophecms/import-export/?lang=original
项目主页：https://github.com/apostrophecms/apostrophe/tree/main/packages/import-export#readme
源码仓库：https://github.com/apostrophecms/apostrophe

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

- 包体积（解压后）：2.1 MB，134 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：7 个
- 首次发布：2023-10-12T19:17:54.749Z
- 最新版本发布：2026-10-14T18:14:54.766Z
- 近 30 天下载量：4949（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：36（近 12 个月 10 个）

## 中文简介

导入 ApostropeCMS 的导出文档

## 安装

```sh
npm install @apostrophecms/import-export
```

也可以使用：`pnpm add @apostrophecms/import-export`、`yarn add @apostrophecms/import-export`、`bun add @apostrophecms/import-export`

## README

![ApostropheCMS logo](https://raw.githubusercontent.com/apostrophecms/apostrophe/main/logo.svg)

# Aposrape 导入导出模块

 [![](https://img.shields.io/badge/MADE%20FOR%20ApostropheCMS-000000.svg?style=for-the-badge&logo=Apostrophe&labelColor=6516dd)](https://docs.apostrophecms.org/)[![](https://img.shields.io/discord/517772094482677790?color=5865f2&label=Join%20the%20Discord&logo=discord&logoColor=fff&labelColor=000&style=for-the-badge&logoWidth=20) ](http://chat.apostrophecms.org/)[![](https://img.shields.io/static/v1?style=for-the-badge&labelColor=000000&label=License&message=MIT&color=3DA639)](https://github.com/apostrophecms/apostrophe/blob/main/packages/import-export/LICENSE.md)

此模块允许导入和导出页面和部件, 无论是否相关 文件、图像和其他相关类型的文档.

## 安装

要安装模块, 请使用命令行在 Aposrope 项目的根目录中运行此命令 :

```
npm install @apostrophecms/import-export
```

## 使用量

配置该模块 `app.js` 文件 :

```javascript
require('apostrophe')({
  shortName: 'my-project',
  modules: {
    '@apostrophecms/import-export': {}
  }
});
```

## 导出文件

### 页 次

![Screenshot highlighting the export menu item in the context menu of the bulk operations in the manager.](https://static.apostrophecms.com/apostrophecms/import-export/images/bulk-export.png)

页面可以通过从单个页面的上下文菜单中选择"Export"来导出,也可以通过选择多页再从批量操作上下文菜单中选择"Export"来导出. 在输出一页时,它将保留其导入时的出版状态。 导出时发布的页面将在导入时发布,除非您选择仅作为草稿导入的选项。 页面草稿将保持草稿状态.

在一组嵌入式文档中导出母页将 **没有** 导出儿童页面。 每个子页必须分别导出 。 要维护页面顺序,先导入父文档的文件,再导入子文档的文件.

如果一个页面存在于多个地块中,则仅会导出当前地块的页面,而不会导出其他地块. 页面必须针对每个地方分别导出 .

* * *

![Screenshot of the page export modal](https://static.apostrophecms.com/apostrophecms/import-export/images/page-export-modal.png)

点击导出会引入一个包含两个输入控件的对话框 .

第一个是选择用于导出文件的文件格式。 目前,该模块仅输出于 `.tar.gz` 格式,但今后可能会扩大.

第二个输入切换与页面相关的文档,如文档中通过关系字段或部件连接的图像、文件、片段或片段,是否应当包含在下载中。 任何或所有可以不选. 请注意,这并不意味着特定的页面包括所有那些文档类型,只是这些文档类型都存在于您的项目中,并且不禁用用于导出.

点击"Export Page"按钮会触发将导出文件下载到您的本地计算机.

* * *

### 块

![Screenshot of exporting pieces using the batch method](https://static.apostrophecms.com/apostrophecms/import-export/images/piece-batch-export.png)

与页面不同,棋子可以单独从上下文菜单导出到棋子右侧,也可以使用管理器中棋子列表上方的上下文菜单作为批次. 例如,上面的图像中有两篇文章被选入导出. 与页面类型一样,所有导出都是按本地进行.

点击导出会打开在导出页面时出现的同一对话框, 从而可以选择应该导出的相关文档 .

* * *

### 模板

![Screenshot of exporting templates](https://static.apostrophecms.com/apostrophecms/import-export/images/template-export.png)

如果你拥有 [模板库 Pro](https://apostrophecms.com/extensions/template-library) 模块,模板通过在模板管理器中选择一个或多个,然后使用位于批量操作右侧的上下文菜单来导出。 与件型出口商一样,您可以选择只批量输出一个或多个文件,这取决于检查了多少文件。 与页面类型一样,所有导出都是按本地进行.

点击导出将打开在导出页面时出现的同一对话框, 从而可以选择应该导出的相关文档 .

* * *

## 导入文件

![Screenshot of the utilities context menu for importing in the page manager](https://static.apostrophecms.com/apostrophecms/import-export/images/page-import.png) 任何导出文件,无论内容如何,都可以使用位于内容管理器上方的公用上下文菜单来导入,一般位于按钮左侧以添加该类型的新内容. 这包括页面管理器,任何件管理器,或安装后的文档模板管理器.

![Screenshot of the file upload modal for importing files](https://static.apostrophecms.com/apostrophecms/import-export/images/page-import-with-translation.png)

点击“ 导入” 菜单项将打开对话框来选择您想要导入的导出文件 。 您只能一次选择一个文件, 附加文件的选择将取代第一个文件 。 在此阶段,您可以选择导入任何已出版的页面为 [草稿](https://npmcn.com/package/%40apostrophecms/import-export/#readme-importing-as-drafts-only)。如果您有可选选项 [`@apostrophecms-pro/automatic-translation` 扩展](https://apostrophecms.com/extensions/automatic-translation) 安装和配置后,您可以选择将内容翻译为进行导入时的语言。 在您选择导出的文件并单击导入按钮后,将显示进度栏,并在文件被完全导入时显示成败通知.

如果您选择的文件有您项目中已经存在的文件, 您将会得到一份通知和会被过度写入的文件列表 。 从该列表中您可以选择您不想导入的文档 。 注意,如果您有任何文件先前已经发布,然后存档,它们会触发重复的覆盖警告.

当导入当前从一个语言导出、而您没有自动翻译模块或没有选择翻译内容的页面、 片段或模板时, 您将会收到通知, 询问您是否想要继续 .

当导入包含一组被嵌入的页面的多个文件时,在导入孩子文件之前导入父文件将保留树上的页面顺序. 如果儿童文件的文件是在父母文件之前或独立于父母文件导入的,则会作为主页的孩子被添加.

警告 - 尽管您可以重命名导出的文件,但您不能更改文件扩展名( Q)`.tar.gz`)或内容,或进口可能没有按计划进行。 您在尝试导入与另一个文件导出者编写的不兼容文件、 扩展名不正确的文件, 或使用版本的文件时也会出错 `Import/Export` 模块,可以打破当前已安装版本的更改.

> 网站之间共享文件的一个告诫是,每个页面类型和块类型模块必须相同。 例如,如果网站A使用一个页面类型: `contact-page`,该类型的页面只能被导入到同样具有 `contact-page` 模块。 如果两个工程的代码库存在显著差异,则可能要么导致导入失败,要么如果计划字段无法对齐,一些数据会丢失.

### 权限

拥有文档类型“ 创建” 和“ 编辑” 权限的用户可以导出并导入这些文件 。 然而,拥有其他文档类型权限但缺乏"创建"或"编辑"权限的用户,无法导入文档. 他们仍然可以出口这类文件.

### 选项

您可以禁用任何页面或部件类型的导出和(或)导入 `importExport` 选项。 此选项对象为 `import` 财务报告和审定财务报表 `export` 键可以同时取布尔值.

```javascript
export default {
  extend: '@apostrophecms/piece-type',
  options: {
    importExport: {
      import: true,
      export: false
    },
    label: 'Article',
    pluralLabel: 'Articles'
```

在这个例子中,可以从文件中导入"Article"的棋子类型,但不允许用户输出任何此类. 这也会导致导出选项从"Article"的"Article"片段上下文菜单中的批量和个人上下文菜单中消失. 请注意,这不会影响其他片型. 如果禁用用于导出的页面类型或文档模板,也会从相应的管理器中删除导出菜单. 最后,任何已禁用的文档类型都不会出现在相关文档的列表中.

禁止导入文档类型将会从文档管理器的用户上下文菜单中删除导入项 。 它还会在从另一个管理器的上下文菜单中导入时阻断任何此类文档的插入. 最后,任何含有禁入的相关文档类型的导出文件仍然会成功导入允许的文档类型.

这个 `export` 键也可以带一个对象 `expiration` 属性。 此属性的值设定了导出文件在被删除前的持续时间 。 默认为600000ms(10分),但如果预计下载会因某种原因被延迟,则可被延长.

```javascript
export default {
  extend: '@apostrophecms/piece-type',
  options: {
    importExport: {
      import: true,
      export: {
        expiration: 600000
      }
    },
    label: 'Article',
    pluralLabel: 'Articles'
```

### 归档大小限制

为了保护服务器的存储, 提取导入归档( Q)`.tar.gz`)停止,而导入失败,一旦归档超过其中的一个限制. 当导入失败时, 任何被上传和提取的东西都会被移除 。 设定 `importLimits` 此模块的选项可更改它们:

```javascript
export default {
  options: {
    importLimits: {
      // Maximum number of files and directories in the archive
      maxEntries: 100000,
      // Maximum total size of the extracted files, in bytes.
      // No absolute maximum by default
      maxExtractedSize: null,
      // Maximum total size of the extracted files, as a multiple of the
      // size of the archive. Up to 64MB may always be extracted.
      // Set to `false` to disable this check
      maxCompressionRatio: 100
    }
  }
};
```

此模块的导出完全处于默认值之内, 因为媒体文件几乎无法压缩 。 默认大多会停止"压缩炸弹",小型档案会扩张为大量数据. 如果您的服务器磁盘空间有限, 请设定 `maxExtractedSize`。 。 。 .

## 从另一个地方导入文档

无论原始的地籍,进口的地籍文件都导入到目前的地籍. 您将被提示确认语言是否不同, 您没有或者没有选择使用自动翻译模块 .

如果设置了多个地块,则会促使用户在取消导入或继续导入之间作出选择,除非用户已经选择翻译内容.

![Screenshot highlighting the confirm modal letting the user choose between aborting on continuing the import when the docs locale is different from the site one.](https://static.apostrophecms.com/apostrophecms/import-export/images/different-locale-modal.png)

### 自动翻译

如果 `@apostrophecms-pro/automatic-translation` 模块已安装,导入模式将提供一个“ Translate”复选框。 被选中后,模块将使用所配置的翻译服务,将导入的文档自动翻译到当前站点的地块.

当选择"Translate"复选框时,当Docs locale与站点不同时,允许用户在继续导入时选择中止的确认模式会被压制,而导入将不进行任何进一步的用户互动.

## 仅导入为草稿

进口模式包括一个标有 " 的复选框_将所有文档导入为草稿_" 在选定文件时,仅从草稿中导入已公布的文件。 该功能允许用户在进口文件发布前对其进行审查和修改.

默认情况下,可以通过启用 `importDraftsOnlyDefault: true` 选项.

如果导入文件中的文档没有被发布版本,则仍然会被导入. 没有单独草稿的内容类型通常会被导入.

## 使用 CSV 格式更新已存在的部件

您也可以通过此模块更新已有的棋子 .

要做到这一点,你将需要一个(只有一个) **键列** 在你的档案。 此列的名称 **必须是当前字段的名称** 将每一行作为特定现存作品的更新, **接下来是 `:key`**。 。 。 .

例如,如果需要批量更改用户的用户名,您可能会编写这样的CSV文件:

```
username:key,username
bobsmith,bob.smith
janedoe,jane.doe
```

键栏是 _旧值_。您也可以选择提交 _新值_ 在单独的一栏中对应同一栏,而不包含 `:key`。您也可以按您认为合适的方式加入其他栏目。 重要的是,你必须有一个,只有一个 `:key` 栏,以进行更新.

请注意,草案和已公布的版本都会被更新,即使其中之一与键列值不符.

## 插入和更新

如果一行对您没有价值 `:key` 栏中,它被视为插入,而不是更新.

## 导入丰富文本( HTML) 而非纯文本

默认情况下, 如果您在 CSV 文件内为类型字段创建一列 `area`,将输入为简洁文本。 任何特殊角色,如 `<` 财务报告和审定财务报表 `>` 将被逃脱,以便用户能看到它们。 不支持 HTML 选项 .

要将区域导入为丰富文本 HTML 标记,请添加 `importAsRichText: true` 选项 `area` 字段.

## 如何添加新格式 ?

### 为格式创建文件 :

将格式添加到 `lib/formats/<format_name>.js` 并导出到 `lib/formats/index.js`。 。 。 .

**简单示例** (对于一个没有附件文件的文件):

```js
// lib/formats/ods.js
module.exports = {
  label: 'ODS',
  extension: '.ods',
  allowedExtension: '.ods',
  allowedTypes: [ 'application/vnd.oasis.opendocument.spreadsheet' ],
  async input(filepath) {
    // Read `filepath` using `fs.createReadStream`
    // or any reader provided by a third-party library

    // Return parsed docs as an array
    return { docs };
  },
  async output(filepath, { docs }) {
    // Write `docs` into `filepath` using `fs.createWriteStream`
    // or any writer provided by a third-party library
  }
};
```

**说明**编号: `input` 财务报告和审定财务报表 `output` 函数仍应预知任何超常逻辑.

```js
// lib/formats/index.js
const ods = require('./ods');

module.exports = {
  // ...
  ods
};
```

### 带有附件文件的格式 :

如果您想要添加包含存档等附件文件的格式, 您可以启用此格式 `includeAttachments` 选项,并使用 `input` 财务报告和审定财务报表 `output` 函数.

**高级示例**数字 :

```js
// lib/formats/zip.js
module.exports = {
  label: 'ZIP',
  extension: '.zip',
  allowedExtension: '.zip',
  allowedTypes: [
    'application/zip',
    'application/x-zip',
    'application/x-zip-compressed'
  ],
  includeAttachments: true,
  async input(filepath) {
    let exportPath = filepath;

    // If the given path is the archive, we first need to extract it
    // and define `exportPath` to the extracted folder, not the archive
    if (filepath.endsWith(this.allowedExtension)) {
      exportPath = filepath.replace(this.allowedExtension, '');

      // Use format-specif extraction
      await extract(filepath, exportPath);
      await fsp.unlink(filepath);
    }

    // Read docs and attachments from `exportPath`
    // given that they are stored in aposDocs.json and aposAttachments.json files:
    const docs = await fsp.readFile(path.join(exportPath, 'aposDocs.json'));
    const attachments = await fsp.readFile(path.join(exportPath, 'aposAttachments.json'));
    const parsedDocs = EJSON.parse(docs);
    const parsedAttachments = EJSON.parse(attachments);

    // Add the attachment names and their path where they are going to be written to
    const attachmentsInfo = parsedAttachments.map(attachment => ({
      attachment,
      file: {
        name: `${attachment.name}.${attachment.extension}`,
        path: path.join(exportPath, 'attachments', `${attachment._id}-${attachment.name}.${attachment.extension}`)
      }
    }));

    // Return parsed docs as an array, attachments with their extra files info
    // and `exportPath` since it we need to inform the caller where the extracted data is:
    return {
      docs: parsedDocs,
      attachmentsInfo,
      exportPath
    };
  },
  async output(
    filepath,
    {
      docs,
      attachments = [],
      attachmentUrls = {}
    },
    processAttachments
  ) {
    // Store the docs and attachments into `aposDocs.json` and `aposAttachments.json` files
    // and add them to the archive

    // Create a `attachments/` directory in the archive and store the attachment files inside it:
    const addAttachment = async (attachmentPath, name, size) => {
      // Read attachment from `attachmentPath`
      // and store it into `attachments/<name>` inside the archive
    }
    const { attachmentError } = await processAttachments(attachmentUrls, addAttachment);

    // Write the archive that contains `aposDocs.json`, `aposAttachments.json` and `attachments/`
    // into `filepath` using `fs.createWriteStream` or any writer provided by a third-party library

    // Return potential attachment processing error so that the caller is aware of it:
    return { attachmentError };
  }
};
```

### 通过单独的模块添加格式

您可能想要在另一个模块中覆盖一个或多个格式,原因如下:

-   格式依赖不托管国家预防机制的依赖性(例如: [@ apostrophycems/ 进出口- xlsx](https://apostrophecms.com/extensions/import-export-xlsx)(中文(简体) )
-   您想要在一个单独的模块和寄存器中完全显示格式, 以便于维护
-   .

要做到这一点,只需创建一个改进的Aposrope模块 `@apostrophecms/import-export` 并登记表格 `init` 方法.

有示例 `import-export-excel` 模块 :

```js
const formats = {
  xls: {
    label: 'XLS',
    extension: '.xls',
    allowedExtension: '.xls',
    allowedTypes: [ 'application/vnd.ms-excel' ],
    async input(filepath) {},
    async output(filepath, { docs }) {}
  },
  xlsx: {
    label: 'XLSX',
    extension: '.xlsx',
    allowedExtension: '.xlsx',
    allowedTypes: [ 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' ],
    async input(filepath) {},
    async output(filepath, { docs }) {}
  }
};

module.exports = {
  improve: '@apostrophecms/import-export',
  init(self) {
    self.registerFormats(formats);
  }
};
```

然后将模块添加到项目中 **软件包.json** 财务报告和审定财务报表 **应用程序.js**。 。 。 .

## 常见问题

### @apostrophecms/import-export 是什么？

导入 ApostropeCMS 的导出文档

### 如何安装 @apostrophecms/import-export？

在项目目录运行 npm install @apostrophecms/import-export，或使用 pnpm add / yarn add / bun add。

### @apostrophecms/import-export 支持 TypeScript 吗？

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

### @apostrophecms/import-export 支持 ESM 还是 CommonJS？

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

### @apostrophecms/import-export 可以商用吗？

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

### @apostrophecms/import-export 的下载量有多少？

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

### @apostrophecms/import-export 还在维护吗？

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