文档服务 API：选择字段

页面摘要： 在文档服务 API 查询中使用 fields 参数来选择结果中要返回的特定字段，从而减少 findOne()、findMany()、create()、update()、delete()、publish() 及其他文档操作的数据负载。

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

TIP

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

NOTE

虽然在 Strapi 5 中建议按 documentId 定位条目，但条目可能仍有 id 字段，你会在返回的响应中看到它。这有助于你从 Strapi 4 过渡。更多详情请参阅破坏性变更条目。

在 findOne() 查询中选择字段 {#findone}

通过 documentId 查找文档时，选择要返回的特定字段。

JavaScript

const document = await strapi.documents("api::restaurant.restaurant").findOne({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  fields: ["name", "description"],
});

响应

{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  description: "Welcome to Biscotte restaurant! …"
}

在 findFirst() 查询中选择字段 {#findfirst}

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

JavaScript

const document = await strapi.documents("api::restaurant.restaurant").findFirst({
  fields: ["name", "description"],
});

响应

{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  description: "Welcome to Biscotte restaurant! …"
}

在 findMany() 查询中选择字段 {#findmany}

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

JavaScript

const documents = await strapi.documents("api::restaurant.restaurant").findMany({
  fields: ["name", "description"],
});

响应

[
  {
    documentId: "a1b2c3d4e5f6g7h8i9j0klm",
    name: "Biscotte Restaurant",
    description: "Welcome to Biscotte restaurant! …"
  }
  // ...
]

在 create() 查询中选择字段 {#create}

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

JavaScript

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

响应

{
  id: 4,
  documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
  name: 'Restaurant B',
  description: 'Description for the restaurant'
}

在 update() 查询中选择字段 {#update}

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

JavaScript

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

响应

{
  documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
  name: 'Restaurant C'
}

在 delete() 查询中选择字段 {#delete}

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

JavaScript

const document = await strapi.documents("api::restaurant.restaurant").delete({
  documentId: "fmtr6d7ktzpgrijqaqgr6vxs",
  fields: ["name"],
});

响应

  documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
  // 返回所有被删除文档的版本
  entries: [
    {
      id: 4,
      documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
      name: 'Restaurant C',
      // …
    }
  ]
}

在 publish() 查询中选择字段 {#publish}

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

JavaScript

const document = await strapi.documents("api::restaurant.restaurant").publish({
  documentId: "fmtr6d7ktzpgrijqaqgr6vxs",
  fields: ["name"],
});

响应

{
  documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
  // 返回所有已发布的本地化条目
  entries: [
    {
      documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
      name: 'Restaurant B'
    }
  ]
}

在 unpublish() 查询中选择字段 {#unpublish}

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

JavaScript

const document = await strapi.documents("api::restaurant.restaurant").unpublish({
  documentId: "cjld2cjxh0000qzrmn831i7rn",
  fields: ["name"],
});

响应

{
  documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
  // 返回所有已发布的本地化条目
  entries: [
    {
      documentId: 'fmtr6d7ktzpgrijqaqgr6vxs',
      name: 'Restaurant B'
    }
  ]
}

在 discardDraft() 查询中选择字段 {#discarddraft}

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

JavaScript

const document = await strapi.documents("api::restaurant.restaurant").discardDraft({
  documentId: "fmtr6d7ktzpgrijqaqgr6vxs",
  fields: ["name"],
});

响应

{
  documentId: "fmtr6d7ktzpgrijqaqgr6vxs",
  // 返回所有被丢弃的草稿条目
  entries: [
    {
      "name": "Restaurant B"
    }
  ]
}