文档服务 API：publicationFilter

🌐 Document Service API: publicationFilter

Page summary:

使用可选的 publicationFilter 参数根据文档草稿与已发布版本之间的关系查询文档，例如从未发布的草稿，或自上次发布以来已被修改的条目。它适用于 findOne()、findFirst()、findMany() 和 count()，并可与其他查询参数结合使用。status 仍然决定你获取的是草稿版本还是已发布版本。

🌐 Use the optional publicationFilter parameter to query documents by the relationship between their draft and published versions, for example drafts that were never published, or entries modified since they were last published. It works with findOne(), findFirst(), findMany(), and count(), and combines with other query parameters. status still decides whether you get the draft or the published version.

publicationFilter 是一个参数，与 status 参数 结合使用时，可以帮助你通过 文档服务 API 处理复杂查询，以精确找到你需要的内容。

🌐 The publicationFilter is a parameter that, combined with the status parameter, can help you cover complex queries to find exactly what you need with the Document Service API.

当 status 回答“我想要草稿还是已发布的版本？”时，publicationFilter 参数回答了一个不同的问题：“我想要哪些文档，基于它们的草稿和已发布版本的关系？” 例如，这对于查找从未发布的草稿，或草稿与在线版本相比有未保存更改的条目非常有用。

🌐 While status answers "do I want the draft or the published version?", the publicationFilter parameter answers a different question: "which documents do I want, based on how their draft and published versions relate?". This is useful for example to find drafts that were never published, or entries whose draft has unsaved changes compared to what is live.

Prerequisites

内容类型必须启用草稿与发布功能。如果草稿与发布被禁用，publicationFilter将不起作用。

🌐 The Draft & Publish feature must be enabled on the content-type. If Draft & Publish is disabled, publicationFilter has no effect.

可用值

🌐 Available values

publicationFilter 接受以下值之一：

值	选择
never-published	从未在特定语言环境中发布的文档
never-published-document	从未在任何语言环境中发布的文档
modified	自上次发布以来草稿被编辑过的文档
unmodified	自上次发布以来草稿未更改的文档
has-published-version	同时拥有草稿和已发布版本的文档
published-without-draft	已发布但没有草稿对应的文档 (仅用于诊断)
published-with-draft	已发布且同时拥有草稿的文档 (仅用于诊断)
has-published-version-document	至少在一个语言环境中发布的文档 (在启用 i18n 时有用)

有关如何使用 publicationFilter 值的详细示例，包括与 status 参数一起使用，请参见 可能的用例 表。

🌐 For detailed examples of how to use the publicationFilter values, including with the status parameter, see the possible use cases table.

Note

• 未知值会引发验证错误。
• 以 -document 结尾的值会考虑文档的所有语言环境，这在启用 国际化 (i18n) 时很重要：例如，never-published-document 一旦文档的某个语言环境被发布就会将其排除。所有其他值则一次只考虑一个语言环境。在未启用 i18n 的情况下，这两种变体的行为相同。

Caution: Different default behaviors for different APIs

当省略 status 时，文档服务 API 会返回文档的草稿版本，而 REST 和 GraphQL 则会返回已发布的版本，因此 REST API 查询需要明确指定 status（参见 REST API: publicationFilter）。

🌐 The Document Service API returns draft versions of documents when status is omitted, while REST and GraphQL return the published ones instead, so REST API queries need an explicit status (see REST API: publicationFilter).

可能的使用场景

🌐 Possible use cases

下表列出了许多可能的使用场景，说明如何将 status 和 publicationFilter 参数结合使用，以在文档服务 API 中精确找到你所需的内容。点击一个使用场景即可跳转到完整示例：

🌐 The following table lists many possible use cases, illustrating how the status and publicationFilter parameters can be combined to find exactly what you need with the Document Service API. Click a use case to jump to a complete example:

我想…	使用 status 作为…	使用 publicationFilter 作为…
查找从未发布的草稿	draft	never-published
查找在任何地区从未发布的草稿	draft	never-published-document
查找已修改的文档	draft 或 published	modified
查找未修改的文档	draft 或 published	unmodified
查找有已发布版本的文档	draft 或 published	has-published-version
查找至少在一个地区发布的文档	draft 或 published	has-published-version-document
与 findOne() 和 findFirst() 一起使用	draft 或 published	任何值
只计算匹配的文档	draft 或 published	任何值

Note

将一个值与上表中的相反 status 配对是有效的，但不会返回错误，而是返回空结果：例如，never-published 与 status: 'published' 配对会返回空结果，因为这些文档尚无已发布版本。

🌐 Pairing a value with the opposite status from the table above is valid but returns nothing rather than an error: for example, never-published with status: 'published' returns an empty result, because these documents have no published version yet.

例子

🌐 Examples

以下部分列出了上方表格中总结的最常见用例。

🌐 The following section lists the most common use cases summed up in the table above.

查找从未发布的草稿

🌐 Find never published drafts

最常见的用例之一是查找从未发布的草稿。为此，请传递 status: 'draft' 和 publicationFilter: 'never-published'。

🌐 One of the most common use cases is to find the drafts that have never been published. To do so, pass status: 'draft' and publicationFilter: 'never-published'.

此参数组合仅适用于特定语言环境；要在所有语言环境中查找这些文档，请改为使用 never-published-document。

🌐 This parameter combination works only on a given locale; to find these documents across all locales, use never-published-document instead.

strapi.documents().findMany()

findMany() with publicationFilter: 'never-published'

返回从未在其所在地区发布的草稿。

查找从未在任何地区发布的草稿

🌐 Find drafts never published in any locale

publicationFilter: never-published-document 返回从未在任何地区发布的文档。它查看整个文档的所有地区版本，而不是一次查看一个地区版本。要仅查找给定地区的这些文档，请改用 使用 never-published。

一旦文档的其中一个本地化版本被发布，该文档就算作已发布：文档随后会被排除在外，即使其他本地化版本仅以草稿形式存在。下面的示例返回那些从未在任何地方发布过的文档的草稿版本：

🌐 A document counts as published as soon as one of its locales is published: the document is then left out, even the locales that only exist as a draft. The example below returns the draft versions of documents that were never published anywhere:

strapi.documents().findMany()

findMany() with publicationFilter: 'never-published-document'

返回从未在任何地区发布的文件草稿。

查找已修改的文档

🌐 Find modified documents

publicationFilter: modified 选择草稿有修改但未发布更改的文档。然后 status 决定你得到这些文档的哪个版本。

例如，使用 status: 'draft' 时，查询返回草稿版本：

🌐 For instance, with status: 'draft', the query returns the draft versions:

strapi.documents().findMany()

findMany() with publicationFilter: 'modified' and status: 'draft'

返回含有未发布更改的文档草稿版本。

使用 status: 'published' 时，相同的查询会返回这些文档当前的实时版本：

strapi.documents().findMany()

findMany() with publicationFilter: 'modified' and status: 'published'

返回具有未发布更改的文档的当前版本。

查找未修改的文档

🌐 Find unmodified documents

publicationFilter: unmodified 选择自上次发布以来草稿未更改的文档。然后 status 决定你将获取这些文档的哪个版本。

例如，使用 status: 'draft' 时，查询返回草稿版本：

🌐 For instance, with status: 'draft', the query returns the draft versions:

strapi.documents().findMany()

findMany() with publicationFilter: 'unmodified' and status: 'draft'

返回自上次发布以来未更改的文件草稿版本。

使用 status: 'published' 时，相同的查询会返回这些文档当前的实时版本：

strapi.documents().findMany()

findMany() with publicationFilter: 'unmodified' and status: 'published'

返回自上次发布以来未更改的文档当前版本。

查找有已发布版本的文档

🌐 Find documents with a published version

publicationFilter: has-published-version 选择那些在相同语言环境下既有草稿版本又有已发布版本的文档。status 然后决定你获得这些文档的哪个版本。

例如，使用 status: 'draft' 时，查询返回草稿版本：

🌐 For instance, with status: 'draft', the query returns the draft versions:

strapi.documents().findMany()

findMany() with publicationFilter: 'has-published-version' and status: 'draft'

返回那些在相同语言环境下也有已发布版本的文档草稿版本。

使用 status: 'published' 时，相同的查询会返回这些文档当前的实时版本：

strapi.documents().findMany()

findMany() with publicationFilter: 'has-published-version' and status: 'published'

返回当前在线版本的文档，这些文档在同一语言区域也有已发布的版本。

查找在至少一个地区有已发布版本的文档

🌐 Find documents with a published version in at least one locale

publicationFilter: has-published-version-document 会考虑所有地区，因此只要其中一个地区的文档已发布，它就会匹配该文档。使用 status: 'draft' 时，它会返回这些文档每个地区的草稿版本，包括那些从未发布过的地区：

strapi.documents().findMany()

findMany() with publicationFilter: 'has-published-version-document'

返回至少在一个地区发布的文档的草稿版本。

与 findOne() 和 findFirst() 一起使用

🌐 Use with findOne() and findFirst()

如果所请求的文档（以及适用时的区域设置）与筛选条件不匹配，即使 documentId 存在，findOne() 和 findFirst() 也会返回 null：

🌐 If the requested document (and locale, when applicable) does not match the filter, findOne() and findFirst() return null even when the documentId exists:

strapi.documents().findOne()

findOne() with publicationFilter: 'never-published'

Return the document only if it matches the filter, null otherwise.

只计算匹配的文档

🌐 Count only matching documents

没有 publicationFilter，count({ status: 'draft' }) 会计算每一个草稿版本，包括那些文档已经有已发布版本的草稿。添加 publicationFilter 以仅计算符合给定值的文档（参见 status 文档)：

🌐 Without publicationFilter, count({ status: 'draft' }) counts every draft version, including drafts whose document already has a published version. Add publicationFilter to count only the documents that match a given value (see the status documentation):

strapi.documents().count()

count() with publicationFilter: 'never-published'

Count only the documents that match a given value.

诊断值

🌐 Diagnostic values

published-without-draft 和 published-with-draft 值仅用于数据完整性检查，而不是日常查询。在健康的数据库中，每个已发布的文档也都有一个草稿版本，因此这些值仅用于检测由遗留数据或手动数据库编辑导致处于不一致状态的文档。它们仅与 status: 'published' 一起使用。

🌐 The published-without-draft and published-with-draft values are meant for data-integrity checks only, not for everyday queries. In a healthy database, every published document also has a draft version, so these values are only useful to detect documents left in an inconsistent state by legacy data or manual database edits. They only work with status: 'published'.

显示诊断值示例

publicationFilter: published-without-draft 选择没有草稿对应的已发布文档。在正常操作中，这应返回空值：

strapi.documents().findMany()

findMany() with publicationFilter: 'published-without-draft'

返回在同一语言环境下没有匹配草稿版本的已发布文档。

publicationFilter: published-with-draft 选择那些也有草稿的已发布文档，这在一个健康的数据库中是每个已发布的文档:

strapi.documents().findMany()

findMany() with publicationFilter: 'published-with-draft'

返回那些也有相同本地版本草稿的已发布文档。

与其他参数的组合

🌐 Combination with other parameters

publicationFilter 与其他查询参数作为逻辑 AND 进行组合，包括 filters 和 populate。在填充 draft 与 publish 关系时，嵌套查询会继承相同的过滤逻辑。

内容管理员映射

🌐 Content Manager mapping

在内容管理器中，草稿（从未发布） 列表过滤器映射到 status: 'draft' 和 publicationFilter: 'never-published-document'（以文档为范围，而不是每区域语言的 never-published）。

🌐 In the Content Manager, the Draft (never published) list filter maps to status: 'draft' and publicationFilter: 'never-published-document' (document-scoped, not the per-locale never-published).