# @episerver/content-delivery 中文文档

规范地址：https://npmcn.com/package/%40episerver/content-delivery/

版本：1\.1\.0
npm 元数据更新时间：2026-06-09T09:11:56.206Z
中文译文更新时间：2026-11-13T19:47:37.125Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40episerver/content-delivery
原文对照：https://npmcn.com/package/%40episerver/content-delivery/?lang=original
项目主页：https://www.optimizely.com/
源码仓库：https://github.com/episerver/content-delivery-js-sdk

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

- 包体积（解压后）：120 kB，42 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2021-07-05T13:13:34.337Z
- 最新版本发布：2022-03-25T08:26:22.257Z
- 近 30 天下载量：10536（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 0 个）

## 中文简介

用于 Episerver 内容交付 API 的 SDK.

## 安装

```sh
npm install @episerver/content-delivery
```

也可以使用：`pnpm add @episerver/content-delivery`、`yarn add @episerver/content-delivery`、`bun add @episerver/content-delivery`

## README

# 优化内容交付 JavaScript SDK - 内容加载器,内容解析器和站点加载器

用于从运行该程序的优化应用程序中加载和解析内容的 SDK [内容交付 API](https://world.optimizely.com/documentation/developer-guides/content-delivery-api/)。SDK是用 TypeScript 编写的,包括类型.

请访问 [优化世界](https://world.optimizely.com/) 用于充分记录API.

> 注意此 SDK 需要您使用平面化的 JSON 格式, 参见下面的代码示例 如何配置 API 使用此格式 .

```cs
services.AddContentDeliveryApi(options => 
{
    options.FlattenPropertyModel = true;
});
```

## 安装

使用 npm :

```bash
$ npm install @episerver/content-delivery@latest
```

使用线条 :

```bash
$ yarn install @episerver/content-delivery@latest
```

## 实例

### 内容加载器

既然我们输入了内容装载器

```js
import { ContentLoader } from '@episerver/content-delivery';

const contentLoader = new ContentLoader();
```

构造器需要一个 [`ContentDeliveryConfig`](https://npmcn.com/package/%40episerver/content-delivery/#readme-contentdeliveryconfig-schema) 对象.

用标识符加载内容 :

```js
contentLoader.getContent('38963a25-b6ec-493b-aca4-f4fbce1aed4d')
  .then((content) => {
    // Content was successfully loaded
  })
  .catch((contentLoaderError) => {
    console.error('Content not loaded', contentLoaderError.errorMessage);
  });
```

该函数可选 [`ContentRequest`](https://npmcn.com/package/%40episerver/content-delivery/#readme-contentrequest-schema) 对象,我们可以指定要装入哪个语言分支 `branch` 参数 :

```js
contentLoader.getContent('38963a25-b6ec-493b-aca4-f4fbce1aed4d', { branch: 'en' })
  .then((content) => {
    // Content was successfully loaded
  });
```

我们可以具体说明哪些属性应被纳入与 `select` 参数 :

```js
contentLoader.getContent('38963a25-b6ec-493b-aca4-f4fbce1aed4d', { select: ['heading', 'body'] })
  .then((content) => {
    // Content was successfully loaded
  });
```

我们可以确定哪些属性在回应中应该扩大,与 `expand` 参数 :

```js
contentLoader.getContent('38963a25-b6ec-493b-aca4-f4fbce1aed4d', { expand: ['teasers'] })
  .then((content) => {
    // Content was successfully loaded
  });
```

引用属性(内容区和内容引用)仅包括默认引用的内容. 通过扩展这些属性,引用内容的内容也包含在响应中. 见 [内容 API 文档](https://world.optimizely.com/documentation/developer-guides/content-delivery-api/api-fundamentals/contentapi/) 更多信息.

用父标识符装入孩子 :

```js
contentLoader.getChildren('38963a25-b6ec-493b-aca4-f4fbce1aed4d')
  .then((children) => {
    // Children was successfully loaded
  });
```

该函数可选 [`ContentCollectionRequest`](https://npmcn.com/package/%40episerver/content-delivery/#readme-contentcollectionrequest-schema) 对象。 计外 `ContentRequest` 参数,我们也可以限制内容项的数量来加载:

```js
contentLoader.getChildren('38963a25-b6ec-493b-aca4-f4fbce1aed4d', { top: 10 })
  .then((collection) => {
    // Children was successfully loaded
    var children = collection.items;
    var continuationToken = collection.continuationToken;
  });
```

在装入下一组内容项目时,请使用续作符:

```js
contentLoader.getChildren('38963a25-b6ec-493b-aca4-f4fbce1aed4d', { continuationToken: continuationToken })
  .then((collection) => {
    // Children was successfully loaded
    var children = collection.items;
    // When we reached the last set, the continuation token won't be present.
    var continuationToken = collection.continuationToken;
  });
```

注意续作符号包含应装入多少项,不需要提供 `top` 参数.

用标识符装入祖先 :

```js
contentLoader.getAncestors('38963a25-b6ec-493b-aca4-f4fbce1aed4d')
  .then((ancestors) => {
    // Ancestors was successfully loaded
  });
```

该函数可选 [`ContentRequest`](https://npmcn.com/package/%40episerver/content-delivery/#readme-contentrequest-schema) 对象.

#### `ContentRequest` 计划

```js
{
  branch: 'en',
  select: [''],
  expand: [''],
}
```

#### `ContentCollectionRequest` 计划

```js
{
  branch: 'en',
  select: [''],
  expand: [''],
  top: 0,
  continuationToken: '',
}
```

#### `ContentLoaderError` 计划

```js
{
  data: {},
  errorCode: 404,
  errorMessage: '',
}
```

### 内容解析器

鉴于我们输入了内容解析器

```js
import { ContentResolver } from '@episerver/content-delivery';

const contentResolver = new ContentResolver();
```

构造器需要一个 [`ContentDeliveryConfig`](https://npmcn.com/package/%40episerver/content-delivery/#readme-contentdeliveryconfig-schema) 对象.

用 URL 解决内容 :

```js
contentResolver.resolveContent('https://site.com/en/page1/page2/doesnt-exist/', false)
  .then((resolvedContent) => {
    // Content was resolved. Note that the promise is fulfilled
    // even though the content was not found. The return object contains a
    // status property you can check.
    var content = resolvedContent.content;
  })
  .catch((contentResolverError) => {
    // Promise is only rejected if there was a service error.
    console.error('Content not resolved', contentResolverError.errorMessage);
  });
```

第二个参数, `matchExact`,定义URL是部分匹配还是精确匹配。 URL的剩余路径,如果部分匹配,则可用于 `remainingPath` 在返回对象中,参见 [`ResolvedContent`](https://npmcn.com/package/%40episerver/content-delivery/#readme-resolvedcontent-schema)。该函数还需要可选的 [`ResolveContentRequest`](https://npmcn.com/package/%40episerver/content-delivery/#readme-resolvecontentrequest-schema) 对象.

#### `ResolveContentRequest` 计划

```js
{
  select: [''],
  expand: [''],
}
```

#### `ResolvedContent` 计划

```js
{
  content: {},
  branch: 'en',
  status: 'UNKNOWN|RESOLVED|NOTFOUND|UNAUTHORIZED|ACCESSDENIED',
  mode: 'DEFAULT|PREVIEW|EDIT',
  remainingPath: 'doesnt-exist/',
  siteId: '6ed7799f-efd8-4421-8eb3-c95bfbf7281d',
  startPageId: 'ff2e86ae-27a9-4417-b503-ecb9c2fdd63b',
}
```

#### `ContentResolverError` 计划

```js
{
  errorMessage: '',
}
```

### 站点加载器

鉴于我们进口了现场装载器,并立即进行:

```js
import { SiteLoader } from '@episerver/content-delivery';

const siteLoader = new SiteLoader();
```

构造器需要一个 [`ContentDeliveryConfig`](https://npmcn.com/package/%40episerver/content-delivery/#readme-contentdeliveryconfig-schema) 对象.

以标识符装入站点 :

```js
siteLoader.getSite('45872cd5-e63c-363e-caa4-35e6ab1ad6d4')
  .then((site) => {
    // Site was successfully loaded
  })
  .catch((siteLoaderError) => {
    console.error('Site not loaded', siteLoaderError.errorMessage);
  });
```

正在装入所有站点 :

```js
siteLoader.getSites()
  .then((sites) => {
    // Sites was successfully listed
  });
```

## 配置

#### `ContentDeliveryConfig` 计划

```js
{
  apiUrl: 'https://site.com/api/episerver/v2.0',
  getAccessToken: function (path) { 
    // Return access token.
  },
  selectAllProperties: true,
  expandAllProperties: false,
}
```

### 更改默认配置

默认配置与您传递到内容加载器和解析器类的构建器的配置结合.

```js
import { defaultConfig } from '@episerver/content-delivery';

defaultConfig.apiUrl = 'https://site.com/api/episerver/v2.0';
defaultConfig.getAccessToken = () => authService.getAccessToken();
defaultConfig.selectAllProperties = true;
defaultConfig.expandAllProperties = true;
```

## 常见问题

### @episerver/content-delivery 是什么？

用于 Episerver 内容交付 API 的 SDK\.

### 如何安装 @episerver/content-delivery？

在项目目录运行 npm install @episerver/content-delivery，或使用 pnpm add / yarn add / bun add。

### @episerver/content-delivery 支持 TypeScript 吗？

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

### @episerver/content-delivery 支持 ESM 还是 CommonJS？

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

### @episerver/content-delivery 可以商用吗？

@episerver/content-delivery 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @episerver/content-delivery 的下载量有多少？

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

### @episerver/content-delivery 还在维护吗？

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