文档服务 API：填充字段

🌐 Document Service API: Populating fields

Page summary:

使用 Document Service API 的 populate 参数可以显式加载关系、媒体字段、组件和动态区域，支持一层或多层深度，并在 create()、update()、publish() 和 delete() 操作中使用。

🌐 Use the populate parameter with the Document Service API to explicitly load relations, media fields, components, and dynamic zones at one or multiple levels deep, and within create(), update(), publish(), and delete() operations.

默认情况下，文档服务 API 不会填充任何关系、媒体字段、组件或动态区域。本页介绍如何使用 populate 参数来填充特定字段。

🌐 By default the Document Service API does not populate any relations, media fields, components, or dynamic zones. This page describes how to use the populate parameter to populate specific fields.

Tip

你也可以使用 select 参数仅返回查询结果中的特定字段（参见 select 参数 文档）。

🌐 You can also use the select parameter to return only specific fields with the query results (see the select parameter documentation).

Caution

如果安装了“用户与权限”插件，则必须为正在填充的内容类型启用 find 权限。如果某个角色无法访问某个内容类型，则该内容类型将不会被填充。

🌐 If the Users & Permissions plugin is installed, the find permission must be enabled for the content-types that are being populated. If a role doesn't have access to a content-type it will not be populated.

关系与媒体字段

🌐 Relations and media fields

查询可以接受一个 populate 参数来显式定义要填充的字段，以下是语法选项示例。这包括所有关系类型：一对多、多对一、多对多以及多态关系（morphToOne、morphToMany）。

🌐 Queries can accept a populate parameter to explicitly define which fields to populate, with the following syntax option examples. This includes all relation types: one-to-many, many-to-one, many-to-many, and polymorphic relations (morphToOne, morphToMany).

为所有关系填充 1 级

🌐 Populate 1 level for all relations

strapi.documents("api::article.article").findMany()

为所有关系填充 1 级

Populate one-level deep for all relations using the wildcard.

为特定关系填充 1 级

🌐 Populate 1 level for specific relations

strapi.documents("api::article.article").findMany()

为特定关系填充 1 级

Populate specific relations one-level deep using an array.

为特定关系填充多层数据

🌐 Populate several levels deep for specific relations

strapi.documents("api::article.article").findMany()

为特定关系填充多层数据

Populate specific relations several levels deep using nested populate.

排序已填充的关系

🌐 Sort populated relations

在 populate 对象中使用 sort 参数按属性对相关条目进行排序。对于多对多和其他关联表关系，显式的 sort 优先于默认的连接顺序。

🌐 Use the sort parameter inside a populate object to order related entries by an attribute. For many-to-many and other join-table relations, an explicit sort takes precedence over the default connect order.

strapi.documents("api::article.article").findMany()

排序已填充的关系

Order related entries by an attribute using the sort parameter inside a populate object.

Note

从 populate 对象中省略 sort 以保留默认的连接顺序（条目关联的顺序）。

🌐 Omit sort from a populate object to preserve the default connect order (the order in which entries were associated).

组件与动态区域

🌐 Components & Dynamic Zones

组件的填充方式与关系相同：

🌐 Components are populated the same way as relations:

strapi.documents("api::article.article").findMany()

填充组件

Populate components using the same syntax as relations.

动态区域本质上是高度动态的内容结构。标准填充查询（例如 populate: '*' 或 populate: ['testDZ']）只会检索动态区域内组件的默认非关联标量字段（例如字符串、数字）。它们不会自动获取嵌套关系、媒体字段或嵌套组件。

🌐 Dynamic zones are highly dynamic content structures by essence. Standard populate queries (like populate: '*' or populate: ['testDZ']) will only retrieve the default, non-relational scalar fields (e.g., strings, numbers) of components within a dynamic zone. They will not automatically fetch nested relations, media fields, or nested components.

要填充特定组件的嵌套关系、媒体字段或动态区域内的组件，必须使用 on 属性（片段填充语法）定义每个组件的填充查询。

🌐 To populate component-specific nested relations, media fields, or components within a dynamic zone, you must define per-component populate queries using the on property (fragment population syntax).

strapi.documents("api::article.article").findMany()

填充动态区域

Populate dynamic zones using per-component queries with the on property.

正在用 create() 填充

🌐 Populating with create()

strapi.documents("api::article.article").create()

Populate with create

Populate relations in the response when creating a document.

正在用 update() 填充

🌐 Populating with update()

strapi.documents("api::article.article").update()

Populate with update

Populate relations in the response when updating a document.

正在用 publish() 填充

🌐 Populating with publish()

相同的行为适用于 unpublish() 和 discardDraft()。

🌐 Same behavior applies with unpublish() and discardDraft().

strapi.documents("api::article.article").publish()

Populate with publish

Populate relations in the response when publishing a document.

正在用 delete() 填充

🌐 Populating with delete()

在删除文档时进行填充：

🌐 To populate while deleting documents:

strapi.documents("api::article.article").delete()

Populate with delete

Populate relations in the response when deleting a document.