文档服务 API：填充字段
¥Document Service API: Populating fields
默认情况下，文档服务 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.
你还可以使用 select 参数仅返回查询结果中的特定字段（请参阅 select 参数 文档）。
¥You can also use the select parameter to return only specific fields with the query results (see the select parameter documentation).
如果安装了用户和权限插件，则必须为正在填充的内容类型启用 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
发布文档的一个或多个语言环境。
¥Queries can accept a populate parameter to explicitly define which fields to populate, with the following syntax option examples.
为所有关系填充 1 级
¥Populate 1 level for all relations
要为所有关系填充一层深度，请将 * 通配符与 populate 参数结合使用：
¥To populate one-level deep for all relations, use the * wildcard in combination with the populate parameter:
const documents = await strapi.documents("api::article.article").findMany({
populate: "*",
});
{
[
{
"id": "cjld2cjxh0000qzrmn831i7rn",
"title": "Test Article",
"slug": "test-article",
"body": "Test 1",
// ...
"headerImage": {
"data": {
"id": 1,
"attributes": {
"name": "17520.jpg",
"alternativeText": "17520.jpg",
"formats": {
// ...
}
// ...
}
}
},
"author": {
// ...
},
"categories": {
// ...
}
}
// ...
]
}
为特定关系填充 1 级
¥Populate 1 level for specific relations
要为特定关系填充一层深度，请将关系名称传递到 populate 数组中：
¥To populate specific relations one-level deep, pass the relation names in a populate array:
const documents = await strapi.documents("api::article.article").findMany({
populate: ["headerImage"],
});
[
{
"id": "cjld2cjxh0000qzrmn831i7rn",
"title": "Test Article",
"slug": "test-article",
"body": "Test 1",
// ...
"headerImage": {
"id": 2,
"name": "17520.jpg"
// ...
}
}
// ...
]
为特定关系填充多个深度级别
¥Populate several levels deep for specific relations
要为特定关系填充多层深度，请将对象格式与 populate 结合使用：
¥To populate specific relations several levels deep, use the object format with populate:
const documents = await strapi.documents("api::article.article").findMany({
populate: {
categories: {
populate: ["articles"],
},
},
});
[
{
"id": "cjld2cjxh0000qzrmn831i7rn",
"title": "Test Article",
"slug": "test-article",
"body": "Test 1",
// ...
"categories": {
"id": 1,
"name": "Test Category",
"slug": "test-category",
"description": "Test 1"
// ...
"articles": [
{
"id": 1,
"title": "Test Article",
"slug": "test-article",
"body": "Test 1",
// ...
}
// ...
]
}
}
// ...
]
组件和动态区域
¥Components & Dynamic Zones
组件的填充方式与关系相同：
¥Components are populated the same way as relations:
const documents = await strapi.documents("api::article.article").findMany({
populate: ["testComp"],
});
[
{
"id": "cjld2cjxh0000qzrmn831i7rn",
"title": "Test Article",
"slug": "test-article",
"body": "Test 1",
// ...
"testComp": {
"id": 1,
"name": "Test Component"
// ...
}
}
// ...
]
动态区域本质上是高度动态的内容结构。要填充动态区域，必须使用 on 属性定义每个组件的填充查询。
¥Dynamic zones are highly dynamic content structures by essence. To populate a dynamic zone, you must define per-component populate queries using the on property.
const documents = await strapi.documents("api::article.article").findMany({
populate: {
testDZ: {
on: {
"test.test-compo": {
fields: ["testString"],
populate: ["testNestedCompo"],
},
},
},
},
});
[
{
"id": "cjld2cjxh0000qzrmn831i7rn",
"title": "Test Article",
"slug": "test-article",
"body": "Test 1",
// ...
"testDZ": [
{
"id": 3,
"__component": "test.test-compo",
"testString": "test1",
"testNestedCompo": {
"id": 3,
"testNestedString": "testNested1"
}
}
]
}
// ...
]
使用 create() 填充
¥Populating with create()
要在创建文档时填充：
¥To populate while creating documents:
strapi.documents("api::article.article").create({
data: {
title: "Test Article",
slug: "test-article",
body: "Test 1",
headerImage: 2,
},
populate: ["headerImage"],
});
{
"id": "cjld2cjxh0000qzrmn831i7rn",
"title": "Test Article",
"slug": "test-article",
"body": "Test 1",
"headerImage": {
"id": 2,
"name": "17520.jpg"
// ...
}
}
使用 update() 填充
¥Populating with update()
要在更新文档时填充：
¥To populate while updating documents:
strapi.documents("api::article.article").update({
documentId: "cjld2cjxh0000qzrmn831i7rn",
data: {
title: "Test Article Update",
},
populate: ["headerImage"],
});
{
"id": "cjld2cjxh0000qzrmn831i7rn",
"title": "Test Article Update",
"slug": "test-article",
"body": "Test 1",
"headerImage": {
"id": 2,
"name": "17520.jpg"
// ...
}
}
使用 publish() 填充
¥Populating with publish()
要在发布文档时填充（与 unpublish() 和 discardDraft() 的行为相同）：
¥To populate while publishing documents (same behavior with unpublish() and discardDraft()):
strapi.documents("api::article.article").publish({
documentId: "cjld2cjxh0000qzrmn831i7rn",
populate: ["headerImage"],
});
{
"id": "cjld2cjxh0000qzrmn831i7rn",
"versions": [
{
"id": "cjld2cjxh0001qzrm1q1i7rn",
"locale": "en",
// ...
"headerImage": {
"id": 2,
"name": "17520.jpg"
// ...
}
}
]
}