Skip to main content

文档服务 API：使用 locale 参数

🌐 Document Service API: Using the locale parameter

Page summary:

文档服务 API 中的 locale 参数允许你使用 findOne()、findMany()、update() 和 delete() 等方法查询、创建、更新、删除、发布和取消发布特定语言版本的文档。

🌐 The locale parameter in the Document Service API lets you query, create, update, delete, publish, and unpublish documents for specific language versions using methods like findOne(), findMany(), update(), and delete().

默认情况下，Document Service API 返回文档的默认语言版本（默认为'en'，即英语版本，除非应用已设置了其他默认语言，详见国际化（i18n）功能）。本页面描述了如何使用 locale 参数仅获取或操作特定语言的数据。

🌐 By default the Document Service API returns the default locale version of documents (which is 'en', i.e. the English version, unless another default locale has been set for the application, see Internationalization (i18n) feature). This page describes how to use the locale parameter to get or manipulate data only for specific locales.

获取带有 findOne() 的本地化版本​

🌐 Get a locale version with findOne()

strapi.documents().findOne()

用 findOne() 获取本地化版本

传递一个区域设置给 findOne() 来获取该区域的文档版本。

await strapi.documents('api::restaurant.restaurant').findOne({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'fr',
});
200 OK
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  publishedAt: null, // draft version (default)
  locale: "fr", // as asked from the parameters
  // …
}

如果没有传递 status 参数，则默认返回 draft 版本。

🌐 If no status parameter is passed, the draft version is returned by default.

获取带有 findFirst() 的本地化版本​

🌐 Get a locale version with findFirst()

strapi.documents().findFirst()

使用 findFirst() 获取本地版本

传入一个区域到 findFirst() 来返回匹配该区域的文档。

const document = await strapi.documents('api::article.article').findFirst({
  locale: 'fr',
});
200 OK
{
  "documentId": "cjld2cjxh0000qzrmn831i7rn",
  "title": "Test Article"
  // …
}

如果没有传递 status 参数，则默认返回 draft 版本。

🌐 If no status parameter is passed, the draft version is returned by default.

使用 findMany() 获取本地化版本​

🌐 Get locale versions with findMany()

如果没有传递 status 参数，则默认返回 draft 版本。

🌐 If no status parameter is passed, the draft versions are returned by default.

strapi.documents().findMany()

使用 findMany() 获取本地化版本

传递一个区域设置给 findMany()，可以返回所有可用该区域设置的文档。

// Defaults to status: draft
await strapi.documents('api::restaurant.restaurant').findMany({ locale: 'fr' });
200 OK
[
  {
    documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
    name: 'Restaurant Biscotte',
    publishedAt: null,
    locale: 'fr',
    // …
  },
  // …
]
解释:

给定以下 4 个具有不同语言环境的文档：

🌐 Given the following 4 documents that have various locales:

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

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

create() 为一个区域创建文档​

🌐 create() a document for a locale

strapi.documents().create()

为一个本地创建文档

传入一个区域设置到 create() 来为那个特定的区域创建文档。

await strapi.documents('api::restaurant.restaurant').create({
  locale: 'es' // if not passed, the draft is created for the default locale
  data: { name: 'Restaurante B' }
})
200 OK
{
  documentId: "pw2s0nh5ub1zmnk0d80vgqrh",
  name: "Restaurante B",
  publishedAt: null,
  locale: "es"
  // …
}

update() 本地化版本​

🌐 update() a locale version

strapi.documents().update()

更新本地版本

传递一个区域设置给 update()，只更新文档的那个特定区域版本。

await strapi.documents('api::restaurant.restaurant').update({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'es',
  data: { name: 'Nuevo nombre del restaurante' },
});
200 OK
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Nuevo nombre del restaurante",
  locale: "es",
  publishedAt: null,
  // …
}

delete() 语言区域版本​

🌐 delete() locale versions

使用 Document Service API 的 delete() 方法 的 locale 参数仅删除某些语言版本。除非传入特定的 status 参数，否则这将删除草稿和已发布版本。

🌐 Use the locale parameter with the delete() method of the Document Service API to delete only some locales. Unless a specific status parameter is passed, this deletes both the draft and published versions.

删除一个语言版本​

🌐 Delete a locale version

strapi.documents().delete()

删除一个语言版本

传递一个区域设置给 delete()，只删除文档的那个特定区域版本。

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

删除所有语言版本​

🌐 Delete all locale versions

strapi.documents().delete()

删除所有语言版本

使用 * 通配符搭配 locale 参数来删除文档的所有语言版本。

await strapi.documents('api::restaurant.restaurant').delete({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm', // documentId,
  locale: '*',
}); // for all existing locales
200 OK
{
  "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
  // All of the deleted locale versions are returned
  "versions": [
    {
      "title": "Test Article"
    }
  ]
}

publish() 语言版本​

🌐 publish() locale versions

要使用文档服务 API 的 publish() 方法 仅发布文档的特定语言版本，请将 locale 作为参数传递：

🌐 To publish only specific locale versions of a document with the publish() method of the Document Service API, pass locale as a parameter:

发布本地化版本​

🌐 Publish a locale version

strapi.documents().publish()

发布本地化版本

传递一个区域设置给 publish()，只发布文档的那个特定区域版本。

await strapi.documents('api::restaurant.restaurant').publish({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'fr',
});
200 OK
{
  versions: [
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Restaurant Biscotte',
      publishedAt: '2024-03-14T18:38:05.674Z',
      locale: 'fr',
      // …
    },
  ]
}

发布所有语言版本​

🌐 Publish all locale versions

strapi.documents().publish()

发布所有语言版本

使用 * 通配符搭配 locale 参数来发布文档的所有语言版本。

await strapi
  .documents('api::restaurant.restaurant')
  .publish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
200 OK
{
  "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() locale versions

要使用文档服务 API 的 unpublish() 方法 仅发布文档的特定语言版本，请将 locale 作为参数传递：

🌐 To publish only specific locale versions of a document with the unpublish() method of the Document Service API, pass locale as a parameter:

取消发布本地版本​

🌐 Unpublish a locale version

strapi.documents().unpublish()

取消发布本地版本

传入一个语言环境到 unpublish()，只取消发布该文档的特定语言版本。

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

取消发布所有语言版本​

🌐 Unpublish all locale versions

strapi.documents().unpublish()

取消发布所有语言版本

使用带有 locale 参数的 * 通配符来取消发布文档的所有语言版本。

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

取消发布并选择字段

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

const document = await strapi.documents('api::article.article').unpublish({
  documentId: 'cjld2cjxh0000qzrmn831i7rn',
  fields: ['title'],
});
200 OK
{
  "documentId": "cjld2cjxh0000qzrmn831i7rn",
  // All of the unpublished locale versions are returned
  "versions": [
    {
      "title": "Test Article"
    }
  ]
}

discardDraft() 用于本地化版本​

🌐 discardDraft() for locale versions

要仅丢弃某些语言版本文档的草稿数据，使用文档服务 API 的 discardDraft() 方法，传递 locale 作为参数：

🌐 To discard draft data only for some locales versions of a document with the discardDraft() method of the Document Service API, pass locale as a parameter:

丢弃本地化版本的草稿​

🌐 Discard draft for a locale version

strapi.documents().discardDraft()

丢弃本地化版本的草稿

传递一个区域设置给 discardDraft() 来放弃该特定区域版本的草稿数据。

await strapi
  .documents('api::restaurant.restaurant')
  .discardDraft({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: 'fr' });
200 OK
{
  versions: [
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Restaurant Biscotte',
      publishedAt: null,
      locale: 'fr',
      // …
    },
  ]
}

丢弃所有语言版本的草稿​

🌐 Discard drafts for all locale versions

strapi.documents().discardDraft()

丢弃所有语言版本的草稿

使用带有 * 通配符的 locale 参数来放弃文档的所有语言版本的草稿。

await strapi
  .documents('api::restaurant.restaurant')
  .discardDraft({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
200 OK
{
  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() documents for a locale

要统计特定语言环境的文档，请将 locale 与其他参数一起传递给文档服务 API 的 count() 方法。

🌐 To count documents for a specific locale, pass the locale along with other parameters to the count() method of the Document Service API.

如果没有传递 status 参数，则统计草稿文档（即该语言环境下可用文档的总数，因为即使已发布的文档也会被计为有草稿版本）：

🌐 If no status parameter is passed, draft documents are counted (which is the total of available documents for the locale since even published documents are counted as having a draft version):

// Count number of published documents in French
strapi.documents('api::restaurant.restaurant').count({ locale: 'fr' });
On this page