sanitize_title()
云策文档标注
概述
sanitize_title() 函数用于将字符串转换为可在 URL 或 HTML 属性中使用的 slug。它通过移除重音字符并限制输出为字母数字、下划线和短横线，确保字符串的安全性和兼容性。
关键要点
- 函数将字符串转换为 slug，适用于 URL 或 HTML 属性，而非人类可读标题。
- 默认情况下，在 'save' 上下文中使用 remove_accents() 转换重音字符为 ASCII，并通过 'sanitize_title' 过滤器进一步限制输出字符。
- 接受三个参数：$title（必需，要清理的字符串）、$fallback_title（可选，$title 为空时的备用标题）、$context（可选，清理操作上下文，默认为 'save'）。
- 返回清理后的字符串，如果 $title 为空且 $fallback_title 设置，则返回备用标题。
- 上下文 'save' 常用于保存值到数据库，而 'query' 上下文由 sanitize_title_for_query() 用于查询 WHERE 子句。
- 函数包含 'sanitize_title' 过滤器钩子，允许自定义清理逻辑。
- 对于非 ASCII 字符（如中文），输出可能为百分比编码形式，这在 URL 中是标准且安全的，但需注意在 HTML 属性中的使用。
代码示例
function sanitize_title( $title, $fallback_title = '', $context = 'save' ) {
$raw_title = $title;
if ( 'save' === $context ) {
$title = remove_accents( $title );
}
$title = apply_filters( 'sanitize_title', $title, $raw_title, $context );
if ( '' === $title || false === $title ) {
$title = $fallback_title;
}
return $title;
}注意事项
- 函数输出适用于 URL，但可能不直接适合作为人类可读标题；例如，"My Excellent Sentence" 会转换为 "my-excellent-sentence"。
- 对于多字节字符（如中文），输出为百分比编码（如 "%e9%80%99%e6%98%af%e5%ad%97%e4%b8%b2"），这在 URL 中是标准做法，但需确保在 HTML 属性中正确使用。
- 在 JavaScript 中，可考虑使用 @wordpress/url 包中的 cleanForSlug 作为替代方案，但注意它仅近似核心功能。
原文内容
Sanitizes a string into a slug, which can be used in URLs or HTML attributes.
Description
By default, converts accent characters to ASCII characters and further limits the output to alphanumeric characters, underscore (_) and dash (-) through the ‘sanitize_title’ filter.
If $title is empty and $fallback_title is set, the latter will be used.
Parameters
$titlestringrequired-
The string to be sanitized.
$fallback_titlestringoptional-
A title to use if $title is empty. Default empty.
$contextstringoptional-
The operation for which the string is sanitized.
When set to'save', the string runs through remove_accents() .
Default'save'.
Source
function sanitize_title( $title, $fallback_title = '', $context = 'save' ) {
$raw_title = $title;
if ( 'save' === $context ) {
$title = remove_accents( $title );
}
/**
* Filters a sanitized title string.
*
* @since 1.2.0
*
* @param string $title Sanitized title.
* @param string $raw_title The title prior to sanitization.
* @param string $context The context for which the title is being sanitized.
*/
$title = apply_filters( 'sanitize_title', $title, $raw_title, $context );
if ( '' === $title || false === $title ) {
$title = $fallback_title;
}
return $title;
}
Hooks
- apply_filters( ‘sanitize_title’, string $title, string $raw_title, string $context )
-
Filters a sanitized title string.
Changelog
| Version | Description |
|---|---|
| 1.0.0 | Introduced. |
Skip to note 5 content
Codex
WordPress Titles
To create the file name portion of a URL the same way that WordPress does use this:
It should return a formatted value, the output would be this:
this-long-title-is-what-my-post-or-page-might-beSkip to note 6 content
kwaves
As was noted in the codex reference page for this function:
So
My Excellent Sentencebecomesmy-excellent-sentencefor example.This is because this function applies a filter of the same name to which WordPress adds
sanitize_title_with_dashesby default.Skip to note 7 content
凱寧
If title is Chinese, its not suitable as a HTML attributes.
Because the function will converts words to ASCII characters.It will be a disaster.
$str = "這是字串"; $str = sanitize_title( $str ); echo $str; // it will echo "%e9%80%99%e6%98%af%e5%ad%97%e4%b8%b2"https://wp.example/%e9%80%99%e6%98%af%e5%ad%97%e4%b8%b2, because that is what needs to be used inhrefattributes, and is what is transmitted to a web server in a request. However what web browsers will typically show you (in the address bar, when hovering over links, etc.) is the decoded equivalent, likehttps://wp.example/這是字串. This means your URL complies with Internet standards, but also remains readable when actually used.Skip to note 8 content
Ramon Ahnert
JS alternative: cleanForSlug from @wordpress/url package.
According to the documentation:
> This replicates some of what sanitize_title() does in WordPress core, but is only designed to approximate what the slug will be.