# @contentful/content-source-maps 中文文档
规范地址：https://npmcn.com/package/%40contentful/content-source-maps/
版本：0\.12\.3
npm 元数据更新时间：2026-07-29T17:47:25.972Z
中文译文更新时间：2026-11-10T16:31:58.257Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40contentful/content-source-maps
原文对照：https://npmcn.com/package/%40contentful/content-source-maps/?lang=original
项目主页：https://github.com/contentful/live-preview#readme
源码仓库：https://github.com/contentful/live-preview
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：107 kB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2024-02-08T08:47:02.466Z
- 最新版本发布：2026-07-29T17:47:25.716Z
- 近 30 天下载量：5261287（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：75（近 12 个月 6 个）
## 中文简介
用于构建内容源地图的 SDK 基础
## 安装
```sh
npm install @contentful/content-source-maps
```
也可以使用：`pnpm add @contentful/content-source-maps`、`yarn add @contentful/content-source-maps`、`bun add @contentful/content-source-maps`
## README
> ⚠️ **我们的Premium计划中只有内容源图。 Vercel Content Links只在Vercel Pro和企业计划中提供.**
# 内容来源地图
- 自动在短文本,丰富文本和资产等可视字段中添加督察模式,取消人工插入数据属性所需的时间和努力.
- 允许与 [Vercel 的内容链接](https://vercel.com/docs/workflow-collaboration/edit-mode#content-link) 特性,增强可用性与合作.
## 安装
安装 Live 预览 SDK :
```bash
npm install @contentful/live-preview
```
## 如何运作
这个过程使用素描法将元数据隐藏在无形的Unicode字符中,包含信息来激活检查器模式. 这些看不见的Unicode字符不会改变您内容的视觉展示.
### 图QL
#### 1\. 启动现场预览SDK
此步骤仅用于Live Preview Introduction Mode(而不是Vercel内容链接).
```jsx
import { ContentfulLivePreviewProvider } from '@contentful/live-preview/react';
const CustomApp = ({ Component, pageProps }) => (
)
```
#### 2\. 设置图表QL查询
在您的 GraphQL 查询中启用内容源地图如下 :
```graphql
query @contentSourceMaps {
postCollection(preview: true) {
items {
title
}
}
}
```
GraphQL API 现在将连同内容源地图一起返回数据 `extensions` 字段.
#### 3\. 处理图QL回复
然后,将数据传递给提供的函数 `encodeGraphQLResponse` 以编码响应:
```jsx
import { encodeGraphQLResponse } from '@contentful/live-preview';
const dataWithAutoTagging = encodeGraphQLResponse(data);
```
在您网站上提供编码数据时, 检查员模式将自动激活 .
### 内容预览 API (REST)
#### 1\. 启动现场预览SDK
此步骤仅用于Live Preview Introduction Mode(而不是Vercel内容链接).
```jsx
import { ContentfulLivePreviewProvider } from '@contentful/live-preview/react';
const CustomApp = ({ Component, pageProps }) => (
)
```
#### 2\. 启用《全面和平协议》的内容源图
启用使用 [内容客户端 SDK](https://github.com/contentful/contentful.js),简单启用 `includeContentSourceMaps` 在客户端中:
```jsx
export const clientPreview = createClient({
space: process.env.CONTENTFUL_SPACE_ID!,
accessToken: process.env.CONTENTFUL_PREVIEW_ACCESS_TOKEN!,
host: "preview.contentful.com",
alphaFeatures: {
includeContentSourceMaps: true
}
});
```
检查器模式将自动激活 。 请确保使用 Contentful.js v10.11.0 或以上版本.
#### 在不使用JS客户SDK时:直接使用CPA
请注意,如果没有内容丰富的客户端 SDK, 某些保护, 如自动请求所需的 `sys.id`未执行。 为确保内容源图正常运行,完整 `sys` 对象需要检索。 因此,使用a [选择](https://www.contentful.com/developers/docs/references/content-preview-api/#/reference/search-parameters/select-operator) 操作员将此排除在答复之外会造成错误.
添加 `&includeContentSourceMaps=true` 转到 URL
```js
fetch("https://preview.contentful.com/spaces/:spaceId/environments/:envId/entries&includeContentSourceMaps=true",
{
method: "GET",
headers: {
Authorization: "Bearer YOUR_ACCESS_TOKEN",
Content-Type: "application/json",
},
}
)
```
使用 `encodeCPAResponse` 函数来自 Live 预览 SDK,通过它通过带有内容源地图的 CPA 响应。 它会带着您的内容返回, 其中包括隐藏的元数据, 以启用检查器模式 .
```jsx
import { encodeCPAResponse } from '@contentful/live-preview';
const dataWithAutoTagging = encodeCPAResponse(data);
```
## 合并 Live 更新内容和内容源地图
如果您正在使用包含内容源地图的实时更新和检查模式,那么将编码结果传递到 `useContentfulLiveUpdates`。 。 。 .
```jsx
import { encodeGraphQLResponse } from '@contentful/live-preview';
import { useContentfulLiveUpdates } from '@contentful/live-preview/react';
export default function Page({ initialGraphQLResponse }) {
// 1. Encode the full response first (including extensions):
const encoded = encodeGraphQLResponse(initialGraphQLResponse);
// 2. Then pass that encoded data to the live updates hook:
const updated = useContentfulLiveUpdates(encoded);
return {updated.data?.myEntry?.title}
;
}
```
## 解决问题/ 小费
- 在某些情况下,例如在CSS中应用字母间距时,字段可能显示并非有意的样式. 在这种情况下,您可以使用 `splitEncoding` 函数由 Live 预览 SDK 提供,用于检索内容并删除任何隐藏的元数据.
```jsx
import { splitEncoding } from '@contentful/live-preview';
const { cleaned, encoded } = splitEncoding(text);
```
- 如果您提供了资产标题或描述的备选案文属性, 图像会自动被标记 .
- 要停止使用手动标记, 请使用内容源地图 :
```jsx
```
- 对于使用@apollo/客户端,需要一个自定义链接来添加扩展以转发解析到响应中. [示例](https://npmcn.com/package/examples/content-source-maps-apollo/lib/api-graphql.ts)
## 限制
- Markdown支持目前正在开发中.
- 将隐藏的元数据添加到内容中会造成问题,例如用于CSS值,日期或URL内容时. 您可以使用 `splitEncoding` 函数来自 Live 预览 SDK.
- 在这些格式上将跳过编码 :
- 不使用英文字母的任何日期格式(例如:. `4/30/24`(中文(简体) )
- ISO日期(例如:. `2024-04-30T12:34:59Z`(中文(简体) )
- URL 网络
## 常见问题
### @contentful/content-source-maps 是什么？
用于构建内容源地图的 SDK 基础
### 如何安装 @contentful/content-source-maps？
在项目目录运行 npm install @contentful/content-source-maps，或使用 pnpm add / yarn add / bun add。
### @contentful/content-source-maps 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @contentful/content-source-maps 支持 ESM 还是 CommonJS？
同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。
### @contentful/content-source-maps 可以商用吗？
@contentful/content-source-maps 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @contentful/content-source-maps 的下载量有多少？
根据 npm 官方下载统计，@contentful/content-source-maps 在 2026/10/11 – 2026/11/09 这 30 天内被下载 5,261,287 次，日均约 175,376 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @contentful/content-source-maps 还在维护吗？
最新版本 0\.12\.3 发布于 2026/07/30（3 个月前）；至今共发布 75 个版本，其中过去 12 个月发布了 6 个；首次发布于 2024/02/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。