文档服务 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

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

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

Caution

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

🌐 If the Users & Permissions feature is enabled, 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.

Info

status、publicationFilter 和 hasPublishedVersion 参数只能在根级别使用，并且适用于整个查询。它们不能放在嵌套的 populate 对象里，如果尝试这样做会返回验证错误。

🌐 The status, publicationFilter, and hasPublishedVersion parameters are root-level only and apply to the entire query. They cannot be used inside nested populate objects and will return a validation error if attempted.

关系与媒体字段

🌐 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 级

使用通配符填充所有关系的一层深度。

JavaScript

const documents = await strapi.documents("api::article.article").findMany({
  populate: "*",
});

200 OK

{
  [
    {
      "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

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

为特定关系填充 1 级

使用数组填充特定关系（一层深度）。

JavaScript

const documents = await strapi.documents("api::article.article").findMany({
  populate: ["headerImage"],
});

200 OK

[
  {
    "id": "cjld2cjxh0000qzrmn831i7rn",
    "title": "Test Article",
    "slug": "test-article",
    "body": "Test 1",
    // ...
    "headerImage": {
      "id": 2,
      "name": "17520.jpg"
      // ...
    }
  }
  // ...
]

为特定关系填充多层数据

🌐 Populate several levels deep for specific relations

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

为特定关系填充多层数据

使用嵌套填充来填充多层的特定关系。

JavaScript

const documents = await strapi.documents("api::article.article").findMany({
  populate: {
    categories: {
      populate: ["articles"],
    },
  },
});

200 OK

[
  {
    "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",
          // ...
        }
        // ...
      ]
    }
  }
  // ...
]

排序已填充的关系

🌐 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()

排序已填充的关系

在 populate 对象里使用 sort 参数按某个属性对条目排序。

JavaScript

const documents = await strapi.documents("api::article.article").findMany({
  populate: {
    categories: {
      sort: 'name:asc',
    },
  },
});

200 OK

[
  {
    "id": "cjld2cjxh0000qzrmn831i7rn",
    "title": "Test Article",
    // ...
    "categories": [
      {
        "id": 1,
        "name": "Architecture"
        // ...
      },
      {
        "id": 3,
        "name": "Technology"
        // ...
      }
    ]
  }
  // ...
]

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

Note

当被填充时，空的 morphMany 关联（包括像图库这样的 type: 'media', multiple: true 字段）会返回 [] 而不是 null，这与 oneToMany 和 manyToMany 一致。有关迁移指南，请参见 morphMany 序列化破坏性更改。

🌐 When populated, empty morphMany relations (including type: 'media', multiple: true fields such as a gallery) return [] instead of null, consistent with oneToMany and manyToMany. See the morphMany serialization breaking change for migration guidance.

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

🌐 Components are populated the same way as relations:

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

填充组件

使用和关系相同的语法来填充组件。

JavaScript

const documents = await strapi.documents("api::article.article").findMany({
  populate: ["testComp"],
});

200 OK

[
  {
    "id": "cjld2cjxh0000qzrmn831i7rn",
    "title": "Test Article",
    "slug": "test-article",
    "body": "Test 1",
    // ...
    "testComp": {
      "id": 1,
      "name": "Test Component"
      // ...
    }
  }
  // ...
]

动态区域本质上是高度动态的内容结构。标准填充查询（例如 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).

Community plugin: shorter dynamic zone populate objects

当一个动态区域接受许多组件时，populate 对象可能会变得很长。 Smart Populate 是一个社区插件，它会在 Strapi 启动时读取你的组件模式，并为你构建该对象，这样查询就可以传递 smart 令牌了：

await strapi.documents('api::article.article').findMany({
  populate: { testDZ: 'smart' },
});

组件内部的关系默认会填充一层深度，并且可以针对每个组件进行调整。
它不是一个 populate=deep 插件，这是一个REST API 文档不推荐的类别：填充对象来自你的模式，并且关系不会递归展开。
这个插件不是由 Strapi 维护的。

🌐 Relations inside components are populated 1 level deep by default, and can be adjusted per component. It is not a populate=deep plugin, a category the REST API documentation advises against: the populate object comes from your schemas and relations are not expanded recursively. This plugin is not maintained by Strapi.

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

填充动态区域

使用每个组件的查询和 on 属性填充动态区域。

JavaScript

const documents = await strapi.documents("api::article.article").findMany({
  populate: {
    testDZ: {
      on: {
        "test.test-compo": {
          fields: ["testString"],
          populate: ["testNestedCompo"],
        },
      },
    },
  },
});

200 OK

[
  {
    "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()

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

用创建填充

在创建文档时在响应中填充关联。

JavaScript

strapi.documents("api::article.article").create({
  data: {
    title: "Test Article",
    slug: "test-article",
    body: "Test 1",
    headerImage: 2,
  },
  populate: ["headerImage"],
});

200 OK

{
  "id": "cjld2cjxh0000qzrmn831i7rn",
  "title": "Test Article",
  "slug": "test-article",
  "body": "Test 1",
  "headerImage": {
    "id": 2,
    "name": "17520.jpg"
    // ...
  }
}

正在用 `update()` 填充

🌐 Populating with update()

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

用更新填充

在更新文档时在响应中填充关联内容。

JavaScript

strapi.documents("api::article.article").update({
  documentId: "cjld2cjxh0000qzrmn831i7rn",
  data: {
    title: "Test Article Update",
  },
  populate: ["headerImage"],
});

200 OK

{
  "id": "cjld2cjxh0000qzrmn831i7rn",
  "title": "Test Article Update",
  "slug": "test-article",
  "body": "Test 1",
  "headerImage": {
    "id": 2,
    "name": "17520.jpg"
    // ...
  }
}

正在用 `publish()` 填充

🌐 Populating with publish()

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

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

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

用发布填充

在发布文档时在响应中填充关联信息。

JavaScript

strapi.documents("api::article.article").publish({
  documentId: "cjld2cjxh0000qzrmn831i7rn",
  populate: ["headerImage"],
});

200 OK

{
  "id": "cjld2cjxh0000qzrmn831i7rn",
  "versions": [
    {
      "id": "cjld2cjxh0001qzrm1q1i7rn",
      "locale": "en",
      // ...
      "headerImage": {
        "id": 2,
        "name": "17520.jpg"
        // ...
      }
    }
  ]
}

正在用 `delete()` 填充

🌐 Populating with delete()

在删除文档时进行填充：

🌐 To populate while deleting documents:

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

填充并删除

在删除文档时在响应中填充关联。

JavaScript

strapi.documents("api::article.article").delete({
  documentId: "cjld2cjxh0000qzrmn831i7rn",
  populate: ["headerImage"],
});

200 OK

{
  "documentId": "cjld2cjxh0000qzrmn831i7rn",
  "entries": [
    {
      "id": "cjld2cjxh0000qzrmn831i7rn",
      "title": "Test Article",
      "slug": "test-article",
      "body": "Test 1",
      "headerImage": {
        "id": 2,
        "name": "17520.jpg"
        // ...
      }
      // ...
    }
  ]
}

关系与媒体字段​

为所有关系填充 1 级​

为特定关系填充 1 级​

为特定关系填充多层数据​

排序已填充的关系​

组件与动态区域​

正在用 create() 填充​

正在用 update() 填充​

正在用 publish() 填充​

正在用 delete() 填充​

关系与媒体字段

为所有关系填充 1 级

为特定关系填充 1 级

为特定关系填充多层数据

排序已填充的关系

组件与动态区域

正在用 `create()` 填充

正在用 `update()` 填充

正在用 `publish()` 填充

正在用 `delete()` 填充