文档服务 API：使用 locale 参数

页面摘要： 文档服务 API 中的 locale 参数让你可以使用 findOne()、findMany()、update()、delete() 等方法，针对特定语言版本查询、创建、更新、删除、发布和取消发布文档。

默认情况下，文档服务 API 返回文档的默认本地化版本（即 'en'，也就是英文版本，除非为应用设置了其他默认本地化，参见 国际化（i18n）功能）。本页介绍如何使用 locale 参数仅获取或操作特定本地化的数据。

在 findOne() 中获取本地化版本 {#find-one}

向 findOne() 传入 locale 以获取该本地化下的文档版本。

JavaScript

await strapi.documents('api::restaurant.restaurant').findOne({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'fr',
});

响应

{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  publishedAt: null, // 草稿版本（默认）
  locale: "fr", // 如参数所请求的
  // …
}

如果未传入 status 参数，默认返回 draft 版本。

在 findFirst() 中获取本地化版本 {#find-first}

向 findFirst() 传入 locale 以返回匹配该本地化的文档。

JavaScript

const document = await strapi.documents('api::article.article').findFirst({
  locale: 'fr',
});

响应

{
  "documentId": "cjld2cjxh0000qzrmn831i7rn",
  "title": "Test Article"
  // …
}

如果未传入 status 参数，默认返回 draft 版本。

在 findMany() 中获取本地化版本 {#find-many}

如果未传入 status 参数，默认返回 draft 版本。

向 findMany() 传入 locale 以返回所有拥有该可用本地化的文档。

JavaScript

// 默认 status: draft
await strapi.documents('api::restaurant.restaurant').findMany({ locale: 'fr' });

响应

[
  {
    documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
    name: 'Restaurant Biscotte',
    publishedAt: null,
    locale: 'fr',
    // …
  },
  // …
]

说明：

给定以下 4 个拥有不同本地化的文档：

• 文档 A：
  • en
  • fr
  • it
• 文档 B：
  • en
  • it
• 文档 C：
  • fr
• 文档 D：
  • fr
  • it

findMany({ locale: 'fr' }) 只会返回拥有 'fr' 本地化版本的文档的草稿版本，即文档 A、C 和 D。

为某个本地化 create() 文档 {#create}

向 create() 传入 locale 以针对该特定本地化创建文档。

JavaScript

await strapi.documents('api::restaurant.restaurant').create({
  locale: 'es' // 若未传入，则为默认本地化创建草稿
  data: { name: 'Restaurante B' }
})

响应

{
  documentId: "pw2s0nh5ub1zmnk0d80vgqrh",
  name: "Restaurante B",
  publishedAt: null,
  locale: "es"
  // …
}

更新某个本地化版本 {#update}

向 update() 传入 locale 以仅更新文档中该特定本地化版本。

JavaScript

await strapi.documents('api::restaurant.restaurant').update({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'es',
  data: { name: 'Nuevo nombre del restaurante' },
});

响应

{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Nuevo nombre del restaurante",
  locale: "es",
  publishedAt: null,
  // …
}

delete() 本地化版本 {#delete}

使用文档服务 API 的 delete() 方法 中的 locale 参数，仅删除部分本地化。除非传入特定的 status 参数，否则会同时删除草稿和已发布版本。

删除某个本地化版本

向 delete() 传入 locale 以仅删除文档中该特定本地化版本。

JavaScript

await strapi.documents('api::restaurant.restaurant').delete({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm', // documentId,
  locale: 'es',
});

删除所有本地化版本

在 locale 参数中使用 * 通配符来删除文档的所有本地化版本。

JavaScript

await strapi.documents('api::restaurant.restaurant').delete({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm', // documentId,
  locale: '*',
}); // 针对所有现有本地化

响应

{
  "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
  // 返回所有被删除的本地化版本
  "versions": [
    {
      "title": "Test Article"
    }
  ]
}

publish() 本地化版本 {#publish}

要使用文档服务 API 的 publish() 方法 仅发布文档的某个特定本地化版本，请将 locale 作为参数传入：

发布某个本地化版本

向 publish() 传入 locale 以仅发布文档中该特定本地化版本。

JavaScript

await strapi.documents('api::restaurant.restaurant').publish({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'fr',
});

响应

{
  versions: [
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Restaurant Biscotte',
      publishedAt: '2024-03-14T18:38:05.674Z',
      locale: 'fr',
      // …
    },
  ]
}

发布所有本地化版本

在 locale 参数中使用 * 通配符来发布文档的所有本地化版本。

JavaScript

await strapi
  .documents('api::restaurant.restaurant')
  .publish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });

响应

{
  "versions": [
    {
      "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
      "publishedAt": "2024-03-14T18:45:21.857Z",
      "locale": "en"
      // …
    },
    {
      "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
      "publishedAt": "2024-03-14T18:45:21.857Z",
      "locale": "es"
      // …
    },
    {
      "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
      "publishedAt": "2024-03-14T18:45:21.857Z",
      "locale": "fr"
      // …
    }
  ]
}

unpublish() 本地化版本 {#unpublish}

要使用文档服务 API 的 unpublish() 方法 仅发布文档的某个特定本地化版本，请将 locale 作为参数传入：

取消发布某个本地化版本

向 unpublish() 传入 locale 以仅取消发布文档中该特定本地化版本。

JavaScript

await strapi
  .documents('api::restaurant.restaurant')
  .unpublish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: 'fr' });

响应

{
  versions: 1
}

取消发布所有本地化版本

在 locale 参数中使用 * 通配符来取消发布文档的所有本地化版本。

JavaScript

await strapi
  .documents('api::restaurant.restaurant')
  .unpublish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });

响应

{
  versions: 3
}

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

JavaScript

const document = await strapi.documents('api::article.article').unpublish({
  documentId: 'cjld2cjxh0000qzrmn831i7rn',
  fields: ['title'],
});

响应

{
  "documentId": "cjld2cjxh0000qzrmn831i7rn",
  // 返回所有被取消发布的本地化版本
  "versions": [
    {
      "title": "Test Article"
    }
  ]
}

针对本地化版本的 discardDraft() {#discard-draft}

要使用文档服务 API 的 discardDraft() 方法 仅丢弃文档部分本地化版本的草稿数据，请将 locale 作为参数传入：

丢弃某个本地化版本的草稿

向 discardDraft() 传入 locale 以丢弃该特定本地化版本的草稿数据。

JavaScript

await strapi
  .documents('api::restaurant.restaurant')
  .discardDraft({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: 'fr' });

响应

{
  versions: [
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Restaurant Biscotte',
      publishedAt: null,
      locale: 'fr',
      // …
    },
  ]
}

丢弃所有本地化版本的草稿

在 locale 参数中使用 * 通配符来丢弃文档所有本地化版本的草稿。

JavaScript

await strapi
  .documents('api::restaurant.restaurant')
  .discardDraft({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });

响应

{
  versions: [
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Biscotte Restaurant',
      publishedAt: null,
      locale: 'en',
      // …
    },
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Restaurant Biscotte',
      publishedAt: null,
      locale: 'fr',
      // …
    },
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Biscotte Restaurante',
      publishedAt: null,
      locale: 'es',
      // …
    },
  ]
}

统计某个本地化的文档数量 count() {#count}

要统计特定本地化的文档数量，请将 locale 与其他参数一起传给文档服务 API 的 count() 方法。

如果未传入 status 参数，则会统计草稿文档（即该本地化下可用文档的总数，因为即使是已发布文档也会被视为拥有一个草稿版本）：

// 统计法语的已发布文档数量
strapi.documents('api::restaurant.restaurant').count({ locale: 'fr' });