函数文档

sanitize_title_with_dashes()

💡 云策文档标注

概述

sanitize_title_with_dashes() 是 WordPress 核心函数,用于清理标题字符串,将空格和特定字符转换为连字符,生成适合 URL 或文件名的安全字符串。它支持两种上下文模式:'display' 和 'save',后者在保存时进行更严格的字符处理。

关键要点

  • 函数 sanitize_title_with_dashes( $title, $raw_title = '', $context = 'display' ) 接受三个参数:必需参数 $title 为待清理标题,可选参数 $raw_title 未使用,可选参数 $context 指定操作上下文(默认为 'display')。
  • 清理规则包括:移除 HTML 标签,保留字母数字、下划线和连字符,空格转换为连字符,并处理 UTF-8 编码和特殊字符。
  • 当 $context 设置为 'save' 时,会额外转换或移除更多实体字符(如非断空格、连字符变体、斜杠等),并处理一系列特殊符号和不可见字符。
  • 函数不替换特殊重音字符,也不应用 sanitize_title filter,返回清理后的字符串。

代码示例

// 基本用法示例:清理博客名称用于 body class
function wpdocs_childSiteClass( $classes ) {
    $site_title = sanitize_title_with_dashes( get_bloginfo( 'name' ) );
    $classes[] = 'website-' . $site_title;
    return $classes;
}
add_filter( 'body_class', 'wpdocs_childSiteClass' );

注意事项

  • 此函数主要用于生成 URL 友好的字符串,不适用于所有国际化场景,因为它不处理重音字符。
  • 开发者应注意 $context 参数的选择:'display' 用于一般显示,'save' 用于存储或文件名,以避免字符问题。

📄 原文内容

Sanitizes a title, replacing whitespace and a few other characters with dashes.

Description

Limits the output to alphanumeric characters, underscore (_) and dash (-).
Whitespace becomes a dash.

Parameters

$titlestringrequired
The title to be sanitized.
$raw_titlestringoptional
Not used. Default empty.
$contextstringoptional
The operation for which the string is sanitized.
When set to 'save', additional entities are converted to hyphens or stripped entirely. Default 'display'.

Return

string The sanitized title.

More Information

  • This function does not replace special accented characters.
  • This function does not apply the sanitize_title filter to the title.

Source

function sanitize_title_with_dashes( $title, $raw_title = '', $context = 'display' ) {
	$title = strip_tags( $title );
	// Preserve escaped octets.
	$title = preg_replace( '|%([a-fA-F0-9][a-fA-F0-9])|', '---$1---', $title );
	// Remove percent signs that are not part of an octet.
	$title = str_replace( '%', '', $title );
	// Restore octets.
	$title = preg_replace( '|---([a-fA-F0-9][a-fA-F0-9])---|', '%$1', $title );

	if ( wp_is_valid_utf8( $title ) ) {
		if ( function_exists( 'mb_strtolower' ) ) {
			$title = mb_strtolower( $title, 'UTF-8' );
		}
		$title = utf8_uri_encode( $title, 200 );
	}

	$title = strtolower( $title );

	if ( 'save' === $context ) {
		// Convert  , non-breaking hyphen, –, and — to hyphens.
		$title = str_replace( array( '%c2%a0', '%e2%80%91', '%e2%80%93', '%e2%80%94' ), '-', $title );
		// Convert  , non-breaking hyphen, –, and — HTML entities to hyphens.
		$title = str_replace( array( ' ', '‑', ' ', '–', '–', '—', '—' ), '-', $title );
		// Convert forward slash to hyphen.
		$title = str_replace( '/', '-', $title );

		// Strip these characters entirely.
		$title = str_replace(
			array(
				// Soft hyphens.
				'%c2%ad',
				// ¡ and &iquest.;
				'%c2%a1',
				'%c2%bf',
				// Angle quotes.
				'%c2%ab',
				'%c2%bb',
				'%e2%80%b9',
				'%e2%80%ba',
				// Curly quotes.
				'%e2%80%98',
				'%e2%80%99',
				'%e2%80%9c',
				'%e2%80%9d',
				'%e2%80%9a',
				'%e2%80%9b',
				'%e2%80%9e',
				'%e2%80%9f',
				// Bullet.
				'%e2%80%a2',
				// ©, ®, °, …, and &trade.;
				'%c2%a9',
				'%c2%ae',
				'%c2%b0',
				'%e2%80%a6',
				'%e2%84%a2',
				// Acute accents.
				'%c2%b4',
				'%cb%8a',
				'%cc%81',
				'%cd%81',
				// Grave accent, macron, caron.
				'%cc%80',
				'%cc%84',
				'%cc%8c',
				// Non-visible characters that display without a width.
				'%e2%80%8b', // Zero width space.
				'%e2%80%8c', // Zero width non-joiner.
				'%e2%80%8d', // Zero width joiner.
				'%e2%80%8e', // Left-to-right mark.
				'%e2%80%8f', // Right-to-left mark.
				'%e2%80%aa', // Left-to-right embedding.
				'%e2%80%ab', // Right-to-left embedding.
				'%e2%80%ac', // Pop directional formatting.
				'%e2%80%ad', // Left-to-right override.
				'%e2%80%ae', // Right-to-left override.
				'%ef%bb%bf', // Byte order mark.
				'%ef%bf%bc', // Object replacement character.
			),
			'',
			$title
		);

		// Convert non-visible characters that display with a width to hyphen.
		$title = str_replace(
			array(
				'%e2%80%80', // En quad.
				'%e2%80%81', // Em quad.
				'%e2%80%82', // En space.
				'%e2%80%83', // Em space.
				'%e2%80%84', // Three-per-em space.
				'%e2%80%85', // Four-per-em space.
				'%e2%80%86', // Six-per-em space.
				'%e2%80%87', // Figure space.
				'%e2%80%88', // Punctuation space.
				'%e2%80%89', // Thin space.
				'%e2%80%8a', // Hair space.
				'%e2%80%a8', // Line separator.
				'%e2%80%a9', // Paragraph separator.
				'%e2%80%af', // Narrow no-break space.
			),
			'-',
			$title
		);

		// Convert × to 'x'.
		$title = str_replace( '%c3%97', 'x', $title );
	}

	// Remove HTML entities.
	$title = preg_replace( '/&.+?;/', '', $title );
	$title = str_replace( '.', '-', $title );

	$title = preg_replace( '/[^%a-z0-9 _-]/', '', $title );
	$title = preg_replace( '/s+/', '-', $title );
	$title = preg_replace( '|-+|', '-', $title );
	$title = trim( $title, '-' );

	return $title;
}

Changelog

Version Description
1.2.0 Introduced.

User Contributed Notes

  1. Skip to note 4 content

    Add Current Child-Site Body Class – WordPress Multisite

    // Add Current Child-Site Body Class – WordPress Multisite
    function wpdocs_childSiteClass( $classes ) {
    	$site_title =  sanitize_title_with_dashes( get_bloginfo( 'name' ) );
    	$classes[] = 'website-' . $site_title;
    
    	return $classes;
    }
    add_filter( 'body_class', 'wpdocs_childSiteClass' );