文档服务 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
查询可以接受一个 populate 参数来明确指定要填充的字段，语法选项示例如下。
🌐 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"
// ...
}
}
]
}