Skip to main content

文档

Strapi 5 中的文档是仅限 API 的概念。文档代表内容类型给定条目的所有不同内容变体。

¥A document in Strapi 5 is an API-only concept. A document represents all the different variations of content for a given entry of a content-type.

单一类型包含一个唯一文档，而集合类型可以包含多个文档。

¥A single type contains a unique document, and a collection type can contain several documents.

当你使用管理面板时，文档的概念从未被提及，并且对于终端用户来说不是必需的。用户在 内容管理者 中创建和编辑条目。例如，作为用户，你可以列出给定语言环境的条目，也可以编辑给定语言环境中特定条目的草稿版本。

¥When you use the admin panel, the concept of a document is never mentioned and not necessary for the end user. Users create and edit entries in the Content Manager. For instance, as a user, you either list the entries for a given locale, or edit the draft version of a specific entry in a given locale.

但是，在 API 级别，条目字段的值实际上可以具有：

¥However, at the API level, the value of the fields of an entry can actually have:

  • 英语和法语语言环境的内容不同，

    ¥different content for the English and the French locale,

  • 甚至在每个语言环境中为草稿和已发布版本设置不同的内容。

    ¥and even different content for the draft and published version in each locale.

包含所有语言环境的所有草稿和已发布版本内容的存储桶是一个文档。

¥The bucket that includes the content of all the draft and published versions for all the locales is a document.

使用 文档服务 API 操作文档将帮助你创建、检索、更新和删除文档或它们包含的特定数据子集。

¥Manipulating documents with the Document Service API will help you create, retrieve, update, and delete documents or a specific subset of the data they contain.

下图表示内容的所有可能变化，具体取决于为内容类型启用了哪些功能（例如 国际化（i18n） 和 起草并发布）：

¥The following diagrams represent all the possible variations of content depending on which features, such as Internationalization (i18n) and Draft & Publish, are enabled for a content-type:

  • 如果在内容类型上启用了国际化（i18n）功能，则文档可以有多个文档语言环境。

    ¥If the Internationalization (i18n) feature is enabled on the content-type, a document can have multiple document locales.

  • 如果在内容类型上启用了草稿和发布功能，则文档可以具有已发布版本和草稿版本。

    ¥If the Draft & Publish feature is enabled on the content-type, a document can have a published and a draft version.

🤓 用于查询文档数据的 API

要与文档或它们所代表的数据进行交互：

¥To interact with documents or the data they represent:

  • 从后端服务器（例如，从控制器、服务和插件的后端部分）使用 文档服务 API。

    ¥From the back-end server (for instance, from controllers, services, and the back-end part of plugins), use the Document Service API.

  • 从应用的前端部分，使用 REST API 或 GraphQL API 查询数据。

    ¥From the front-end part of your application, query your data using the REST API or the GraphQL API.

有关 API 的更多信息，请参阅 内容 API 介绍。

¥For additional information about the APIs, please refer to the Content API introduction.

👀 返回结果中的默认版本

后端和前端 API 之间的一个重要区别是关于未传递参数时返回的默认版本：

¥An important difference between the back-end and front-end APIs is about the default version returned when no parameter is passed:

  • 文档服务 API 默认返回草稿版本，

    ¥The Document Service API returns the draft version by default,

  • 而 REST 和 GraphQL API 默认返回已发布的版本。

    ¥while REST and GraphQL APIs return the published version by default.