Skip to main content

文档服务 API：选择字段

🌐 Document Service API: Selecting fields

Page summary:

在文档服务 API 查询中使用 fields 参数以选择要随结果返回的特定字段，从而减少在 findOne()、findMany()、create()、update()、delete()、publish() 及其他文档操作中的数据传输量。

🌐 Use the fields parameter in Document Service API queries to select specific fields to return with your results, reducing data payload across findOne(), findMany(), create(), update(), delete(), publish(), and other document operations.

默认情况下，文档服务 API 会返回文档的所有字段，但不会填充任何字段。本页介绍如何使用 fields 参数仅返回查询结果中的特定字段。

🌐 By default the Document Service API returns all the fields of a document but does not populate any fields. This page describes how to use the fields parameter to return only specific fields with the query results.

Tip

你也可以使用 populate 参数来填充关系、媒体字段、组件或动态区域（参见 populate 参数 文档）。

🌐 You can also use the populate parameter to populate relations, media fields, components, or dynamic zones (see the populate parameter documentation).

Note

虽然建议在 Strapi 5 中使用条目的 documentId 进行定位，但条目仍可能有一个 id 字段，并且你将在返回的响应中看到它。这应该会减轻你从 Strapi 4 过渡的难度。有关更多详细信息，请参考重大变更条目。

🌐 Though it's recommended to target entries by their documentId in Strapi 5, entries might still have an id field, and you will see it in the returned response. This should ease your transition from Strapi 4. Please refer to the breaking change entry for more details.

使用 findOne() 查询选择字段​

🌐 Select fields with findOne() queries

strapi.documents("api::restaurant.restaurant").findOne()

用 findOne() 选择字段

在用 documentId 查找文档时，选择要返回的具体字段。

const document = await strapi.documents("api::restaurant.restaurant").findOne({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  fields: ["name", "description"],
});
200 OK
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  description: "Welcome to Biscotte restaurant! …"
}

使用 findFirst() 查询选择字段​

🌐 Select fields with findFirst() queries

strapi.documents("api::restaurant.restaurant").findFirst()

用 findFirst() 选择字段

在找到第一个匹配的文档时，选择要返回的特定字段。

const document = await strapi.documents("api::restaurant.restaurant").findFirst({
  fields: ["name", "description"],
});
200 OK
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  description: "Welcome to Biscotte restaurant! …"
}

使用 findMany() 查询选择字段​

🌐 Select fields with findMany() queries

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

使用 findMany() 选择字段

在查找多个文档时选择要返回的特定字段。

const documents = await strapi.documents("api::restaurant.restaurant").findMany({
  fields: ["name", "description"],
});
200 OK
[
  {
    documentId: "a1b2c3d4e5f6g7h8i9j0klm",
    name: "Biscotte Restaurant",
    description: "Welcome to Biscotte restaurant! …"
  }
  // ...
]

使用 create() 查询选择字段​

🌐 Select fields with create() queries

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

使用 create() 选择字段

创建新文档时选择要返回的特定字段。

const document = await strapi.documents("api::restaurant.restaurant").create({
  data: {
    name: "Restaurant B",
    description: "Description for the restaurant",
  },
  fields: ["name", "description"],
});
200 OK
{
  id: 4,
  documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
  name: 'Restaurant B',
  description: 'Description for the restaurant'
}

使用 update() 查询选择字段​

🌐 Select fields with update() queries

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

使用 update() 选择字段

在更新文档时选择要返回的特定字段。

const document = await strapi.documents("api::restaurant.restaurant").update({
  documentId: "fmtr6d7ktzpgrijqaqgr6vxs",
  data: {
    name: "Restaurant C",
  },
  fields: ["name"],
});
200 OK
{
  documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
  name: 'Restaurant C'
}

使用 delete() 查询选择字段​

🌐 Select fields with delete() queries

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

用 delete() 选择字段

在删除文档时选择要返回的特定字段。

const document = await strapi.documents("api::restaurant.restaurant").delete({
  documentId: "fmtr6d7ktzpgrijqaqgr6vxs",
  fields: ["name"],
});
200 OK
  documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
  // All of the deleted document's versions are returned
  entries: [
    {
      id: 4,
      documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
      name: 'Restaurant C',
      // …
    }
  ]
}

使用 publish() 查询选择字段​

🌐 Select fields with publish() queries

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

选择带有 publish() 的字段

在发布文档时选择要返回的特定字段。

const document = await strapi.documents("api::restaurant.restaurant").publish({
  documentId: "fmtr6d7ktzpgrijqaqgr6vxs",
  fields: ["name"],
});
200 OK
{
  documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
  // All of the published locale entries are returned
  entries: [
    {
      documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
      name: 'Restaurant B'
    }
  ]
}

选择包含 unpublish() 查询的字段​

🌐 Select fields with unpublish() queries

strapi.documents("api::restaurant.restaurant").unpublish()

选择使用 unpublish() 的字段

取消发布文档时选择要返回的特定字段。

const document = await strapi.documents("api::restaurant.restaurant").unpublish({
  documentId: "cjld2cjxh0000qzrmn831i7rn",
  fields: ["name"],
});
200 OK
{
  documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
  // All of the published locale entries are returned
  entries: [
    {
      documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
      name: 'Restaurant B'
    }
  ]
}

选择包含 discardDraft() 查询的字段​

🌐 Select fields with discardDraft() queries

strapi.documents("api::restaurant.restaurant").discardDraft()

使用 discardDraft() 选择字段

在丢弃草稿文件时选择要返回的特定字段。

const document = await strapi.documents("api::restaurant.restaurant").discardDraft({
  documentId: "fmtr6d7ktzpgrijqaqgr6vxs",
  fields: ["name"],
});
200 OK
{
  documentId: "fmtr6d7ktzpgrijqaqgr6vxs",
  // All of the discarded draft entries are returned
  entries: [
    {
      "name": "Restaurant B"
    }
  ]
}
On this page