# @financial-times/content-tree 中文文档

规范地址：https://npmcn.com/package/%40financial-times/content-tree/

版本：0\.28\.0
npm 元数据更新时间：2026-11-11T08:58:01.679Z
中文译文更新时间：2026-11-14T18:14:14.770Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40financial-times/content-tree
原文对照：https://npmcn.com/package/%40financial-times/content-tree/?lang=original
项目主页：https://github.com/Financial-Times/content-tree#readme
源码仓库：https://github.com/Financial-Times/content-tree

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

- 包体积（解压后）：396 kB，9 个文件
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-02-11T08:45:34.147Z
- 最新版本发布：2026-11-11T08:58:01.487Z
- 近 30 天下载量：2635（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：32（近 12 个月 32 个）

## 中文简介

内容树格式

## 安装

```sh
npm install @financial-times/content-tree
```

也可以使用：`pnpm add @financial-times/content-tree`、`yarn add @financial-times/content-tree`、`bun add @financial-times/content-tree`

## README

# ![content-tree](https://npmcn.com/package/%40financial-times/content-tree/logo.png)

**内容树** 是描述 FT 文章外形为抽象树的规格。 它执行 [无符号](https://github.com/syntax-tree/unist) 谱. 它意在成为我们整个中央管理系统的共享数据合同([闪光](https://github.com/Financial-Times/spark)),内容 APIs,和前端系统.

要读到光谱,去 [SPEC.md 高频](https://npmcn.com/package/%40financial-times/content-tree/SPEC.md)。如果您正在执行文章渲染器,或者添加或修改文章组件,您应该读取该规格.

如果您正在寻找关于 CAPI 返回内容的确定指南, 可在 [https://api-docs.ft.com/内部/参考文献/get content-tree-uuid](https://api-docs.ft.com/internal/reference/get_content-tree-uuid)

* * *

## 目录

-   [概览](https://npmcn.com/package/%40financial-times/content-tree/#readme-overview)
-   [概念](https://npmcn.com/package/%40financial-times/content-tree/#readme-concepts)
-   [使用 `content-tree`](https://npmcn.com/package/%40financial-times/content-tree/#readme-using-content-tree)
    -   [字体](https://npmcn.com/package/%40financial-times/content-tree/#readme-typescript)
    -   [走开](https://npmcn.com/package/%40financial-times/content-tree/#readme-go-libraries)
    -   [杰森·斯克马](https://npmcn.com/package/%40financial-times/content-tree/#readme-json-schemas)
-   [捐款](https://npmcn.com/package/%40financial-times/content-tree/#readme-contributing)
-   [释放](https://npmcn.com/package/%40financial-times/content-tree/#readme-releasing)
-   [许可证](https://npmcn.com/package/%40financial-times/content-tree/#readme-license)

## 概览

主要内容- 树的规格定义在一个 markdown 文件

-   [**`SPEC.md`**](https://npmcn.com/package/%40financial-times/content-tree/SPEC.md):一个标记下文档,定义了树的规格. 以类似打字符的语法写成, 附加自定义 `[external](#concepts)` 属性修改符.

从这个光谱中,我们自动生成以下作为构建过程的一部分:

-   **`content-tree.d.ts`** - 从下标谱自动生成的打字符类型
-   **`/schemas`** - JSON schemas, 自动由下调光谱生成

这个 [内容元数据( M)](https://biz-ops.in.ft.com/Team/content) 团队保持一些 [走开](https://go.dev/) 用于支持在戈兰g内使用内容树工作的代码:

-   **`content_tree.go`** - Go structs,其中载有戈兰格应用中使用的内容树谱的类型定义。 通过内容和元数据手动更新.
-   **`/libraries`** - 用于在其他格式之间转换内容树数据结构的图书馆

支持代码 :

-   **`/tests`** - 验证计划及变压器的测试
-   **`/tools`** - 建造和生成计划及类型的公用事业

## 概念

### (正文)语法树

抽象语法树,即AST,是对内容的一种结构化的代表,其中内容的含义和结构作为树来体现,独立于任何特定的渲染指令或表示.

内容 树是代表 _语义_ 文章的结构----例如段落、标题、图像、其他编辑部分----不执行特定的标记语言或视觉表现。 这使得在不同的产品和平台及背景中更容易使用相同的内容.

-   **`Node`** - 树上的元素 `type` 表示内容单位
-   **`Parent`** - 一个 `Node` 它已经 `children` 节点
-   **`Root`** - 单身顶级 `Node` 在树上

### 中转对休息

FT文章可能包含独立于内容(如图像,视频剪辑)发布的补充资产,或者从外部系统(如繁荣图,社交媒体帖子)提取数据的编辑部分. 当文章通过网络传输(例如通过 FT Content API 获取)时,这些外部资源通常通过 `id`,而获取这些资源需要花费大量时间.

为支持这两种使用案例,内容树可以存在于不同的州:a **满** 树(有已解析的外部数据)和 a **过境** 树(如果外部资源被ID引用)。 两个州的内容和编辑意图保持不变.

### `external`

为了区分中转和完全节点属性,我们在我们的打字属性上使用一个额外的修饰符,叫做 `external`说明该财产从过境代表处中省去,必须由消费申请提供,以便建造一整棵树.

**示例** 推特/X的帖子会用ID发布,但该帖子的实际内容应该在时从X API取出.

| **光谱** | **过境** | **满** | **松动** |
| --- | --- | --- | --- |
| 
```ts
interface Tweet extends Node {
    id: string
    type: "tweet"
    external html: string
}
```

 | 

```ts
interface Tweet extends Node {
    id: string
    type: "tweet"
}
```

 | 

```ts
interface Tweet extends Node {
    id: string
    type: "tweet"
    html: string
}
```

 | 

```ts
interface Tweet extends Node {
    id: string
    type: "tweet"
    html?: string
}
```

 |

## 使用 `content-tree`

### 字体

此软件包提供打字机类型 `content-tree.d.ts` 用于验证JS/TS应用程序中的数据形状。 这些类型自动生成自 [SPEC.md 高频](https://npmcn.com/package/%40financial-times/content-tree/SPEC.md)。 。 。 .

有三个不同的名称空间被曝光,对于不同的状态来说,一棵树可以存在于其中(参见: [中转对休息](https://npmcn.com/package/%40financial-times/content-tree/#readme-in-transit-vs-at-rest)(中文(简体) )

-   `ContentTree.transit` - 仅包含内容API答复中公布和可用的字段
-   `ContentTree.full` - 包含内容的充分表述,包括需要外部资源提供的任何数据(在最高一级也披露) `ContentTree` 名称空间)
-   `ContentTree.loose` - 充分说明内容,包括作为可选内容的外部资源所需的任何数据

1.  以依赖方式安装此寄存器 :

```sh
npm install https://github.com/Financial-Times/content-tree
```

2.  在您的 Typescript/ JSDoc 代码中使用 :

```ts
import type { ContentTree } from "@financial-times/content-tree"

function makeBigNumber(): ContentTree.BigNumber {
    return {
        type: "big-number", //will autocomplete in code editor, and be valid
        number: "1.2m",
        description: "People affected worldwide"
    }
}

function makeImageSetNoFixins(): ContentTree.transit.ImageSet {
    return {
        type: "image-set",
        id: "79acd774-6ca7-487d-a257-cbf64d2498d9",
        // if you try to add a `picture` here it will get mad
    }
}
```

### 杰森·斯克马

也有一些JSON schemas由光谱生成.

-   `content-tree.schema.json` - JSON为全内容树形状设计的计划
-   `transit-tree.schema.json` - JSON计划,不包括任何 `external` 属性
-   `body-tree.schema.json` - JSON为中转树设计的方案 _无_ 页:1 `Root` 节点,仅包含 [体质](https://npmcn.com/package/%40financial-times/content-tree/SPEC.md#body) 定义。 此方案定义返回的数据 `bodyTree` 字段 `/content-tree` API (英语).

### 去图书馆

这些库是供内容和元数据组内部使用的,用于确保我们所有的内容 API 表述与内容-树谱的变化保持一致.

-   `from-bodyxml` - 转换遗产 `bodyXML` 字段,从 C&M 的内部代表到有效的 `bodyTree` 贾森.
-   `to-external-bodyxml` - 将内容树转换为稳定的XML代表,用作 `bodyXML` 字段在 FT 中 `/enrichedcontent` API 密码
-   `to-string` - 将内容树转换为纯文本字符串

(TODO:如何安装/使用)

## 捐款

要更改内容树谱 :

-   切开这个回放并运行 `npm install`
-   更新 [SPEC.md 高频](https://npmcn.com/package/%40financial-times/content-tree/SPEC.md) 使用您的更改 :
    -   要添加一个新的格式化节点,请在 [`Formatting Blocks`](https://npmcn.com/package/%40financial-times/content-tree/SPEC.md#formatting-blocks)。如果格式化可以适用于段落中的案文,确保添加到段落中 [`Phrasing`](https://npmcn.com/package/%40financial-times/content-tree/SPEC.md#phrasing) 类型
    -   要增加一个新的故事块,请在下面添加定义: [`Storyblocks`](https://npmcn.com/package/%40financial-times/content-tree/SPEC.md#storyblocks)。 。 。 .
-   运行 `npm run build` 用于更新 `content-tree.d.ts` 和(视需要) `schemas` 文件

公关一旦建立,与 [内容元数据( M)](https://biz-ops.in.ft.com/Team/content) 确保Go图书馆和变压器进行相关的修改.

对于重大或非标准变化,考虑首先创建一个问题,或在 `#content-pipeline` 斯克频道.

## 释放

对内容树的单一语义变化通常会分出多个拉取请求,而Go和JS更改则由单独的团队执行. 因此,必须在C&M、Spark和CP之间协调发布,以确保每个发布包含支持新版内容树所需的所有修改.

在发布之前,你还需要提出拉出请求来递增软件包.json版本号,这应该在自己的PR中进行,这样每个团队至少有一位成员可以批准. 请你把签到 [{\\fn方正粗倩简体\\fs12\\an8\\1chffff00\\b0}动画故事团队](https://financialtimes.enterprise.slack.com/archives/C035P5DCHMH) 松动频道,并分享这个PR在那里。 然后通过 GitHub 发布: 它们必须包含 SemVer 标签 `vX.Y.Z` 和Json包裹里的那个吻合 发行笔记应当填写,以沟通发行中的变化. 削减发行会引发CI为JS消费者发布npm. Go 消费者可以依赖新的 git 标签作为模块版本.

### Beta 发布

如果您想要在合并为主之前从分支中实现β放出,可以采取以下步骤:

-   将您的释放设置为 `v0.0.0-beta.0` 地点 `0` 您所设置的版本号是什么
-   在Github,进入 [https://github.com/Financial-Times/content-tree/releases (中文(简体) )](https://github.com/Financial-Times/content-tree/releases) 并按下草稿的新释放按钮
-   起草新版本时
    -   将标记设置为您 β 的标签
    -   将目标设定为要释放的分支
    -   设置版本编号的发行标题
    -   以正常方式填入释放笔记
    -   检查发布标签下的释放前选项
    -   按下出版发布按钮

## 许可证

本软件由金融时报根据以下规定出版: [麻省理工学院许可证](https://npmcn.com/package/%40financial-times/content-tree/mit)。 。 。 .

衍生自 [无符号](https://github.com/syntax-tree/unist) © [Titus 虫类](https://wooorm.com/)

## 常见问题

### @financial-times/content-tree 是什么？

内容树格式

### 如何安装 @financial-times/content-tree？

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

### @financial-times/content-tree 支持 TypeScript 吗？

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

### @financial-times/content-tree 可以商用吗？

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

### @financial-times/content-tree 的下载量有多少？

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

### @financial-times/content-tree 还在维护吗？

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