云策 WordPress 开发者社区

类文档

WP_Font_Face

查看官方原文 ↗
💡 云策文档标注

概述

WP_Font_Face 是 WordPress 6.4.0 引入的类，用于生成和打印给定字体的 @font-face CSS 样式。它处理字体变体、验证属性，并优化浏览器支持。

关键要点

  • 核心功能：通过 generate_and_print() 方法生成并输出 @font-face 样式，支持本地托管字体文件。
  • 验证机制：使用 validate_fonts() 和 validate_font_face_declarations() 确保字体属性有效，包括默认属性如 font-family、font-style 等。
  • CSS 构建：build_font_face_css() 和 compile_src() 等方法编译字体变体设置和 src 属性，order_src() 优化浏览器支持顺序。
  • 样式元素处理：get_style_element() 和 generate_style_element_attributes() 管理包装 CSS 的 style 标签属性，根据主题支持动态调整。
  • 私有属性：定义字体属性默认值、有效属性和有效 font-display 值，确保数据一致性。

代码示例

// 示例：使用 WP_Font_Face 生成字体样式
$font_face = new WP_Font_Face();
$fonts = array(
    'font-family' => 'MyFont',
    'src' => array( 'url' => 'path/to/font.woff2' ),
    'font-weight' => '400'
);
$font_face->generate_and_print( $fonts );

注意事项

  • 构造函数中，如果非后台且主题不支持 HTML5 style 标签，会自动添加 type="text/css" 属性。
  • 字体数组需符合 wp_print_font_faces() 支持的字段格式，否则可能验证失败。
  • 私有属性如 $valid_font_face_properties 定义了所有有效属性名，开发时需参考以避免错误。
📄 原文内容

Font Face generates and prints @font-face styles for given fonts.

Methods

NameDescription
WP_Font_Face::__constructCreates and initializes an instance of WP_Font_Face.
WP_Font_Face::build_font_face_cssBuilds the font-family’s CSS.
WP_Font_Face::compile_srcCompiles the `src` into valid CSS.
WP_Font_Face::compile_variationsCompiles the font variation settings.
WP_Font_Face::generate_and_printGenerates and prints the `@font-face` styles for the given fonts.
WP_Font_Face::generate_style_element_attributesGets the defined element’s attributes.
WP_Font_Face::get_cssGets the `@font-face` CSS styles for locally-hosted font files.
WP_Font_Face::get_style_elementGets the style element for wrapping the `@font-face` CSS.
WP_Font_Face::order_srcOrders `src` items to optimize for browser support.
WP_Font_Face::validate_font_face_declarationsValidates each font-face declaration (property and value pairing).
WP_Font_Face::validate_fontsValidates each of the font-face properties.

Source

class WP_Font_Face {

	/**
	 * The font-face property defaults.
	 *
	 * @since 6.4.0
	 *
	 * @var string[]
	 */
	private $font_face_property_defaults = array(
		'font-family'  => '',
		'font-style'   => 'normal',
		'font-weight'  => '400',
		'font-display' => 'fallback',
	);

	/**
	 * Valid font-face property names.
	 *
	 * @since 6.4.0
	 *
	 * @var string[]
	 */
	private $valid_font_face_properties = array(
		'ascent-override',
		'descent-override',
		'font-display',
		'font-family',
		'font-stretch',
		'font-style',
		'font-weight',
		'font-variant',
		'font-feature-settings',
		'font-variation-settings',
		'line-gap-override',
		'size-adjust',
		'src',
		'unicode-range',
	);

	/**
	 * Valid font-display values.
	 *
	 * @since 6.4.0
	 *
	 * @var string[]
	 */
	private $valid_font_display = array( 'auto', 'block', 'fallback', 'swap', 'optional' );

	/**
	 * Array of font-face style tag's attribute(s)
	 * where the key is the attribute name and the
	 * value is its value.
	 *
	 * @since 6.4.0
	 *
	 * @var string[]
	 */
	private $style_tag_attrs = array();

	/**
	 * Creates and initializes an instance of WP_Font_Face.
	 *
	 * @since 6.4.0
	 */
	public function __construct() {
		if (
			function_exists( 'is_admin' ) && ! is_admin()
			&&
			function_exists( 'current_theme_supports' ) && ! current_theme_supports( 'html5', 'style' )
		) {
			$this->style_tag_attrs = array( 'type' => 'text/css' );
		}
	}

	/**
	 * Generates and prints the `@font-face` styles for the given fonts.
	 *
	 * @since 6.4.0
	 *
	 * @param array[][] $fonts Optional. The font-families and their font variations.
	 *                         See <a href="https://developer.wordpress.org/reference/functions/wp_print_font_faces/">wp_print_font_faces()</a> for the supported fields.
	 *                         Default empty array.
	 */
	public function generate_and_print( array $fonts ) {
		$fonts = $this->validate_fonts( $fonts );

		// Bail out if there are no fonts are given to process.
		if ( empty( $fonts ) ) {
			return;
		}

		$css = $this->get_css( $fonts );

		/*
		 * The font-face CSS is contained within <style> tags and can only be interpreted
		 * as CSS in the browser. Using wp_strip_all_tags() is sufficient escaping
		 * to avoid malicious attempts to close </style> and open a <script>.
		 */
		$css = wp_strip_all_tags( $css );

		// Bail out if there is no CSS to print.
		if ( empty( $css ) ) {
			return;
		}

		printf( $this->get_style_element(), $css );
	}

	/**
	 * Validates each of the font-face properties.
	 *
	 * @since 6.4.0
	 *
	 * @param array $fonts The fonts to valid.
	 * @return array Prepared font-faces organized by provider and font-family.
	 */
	private function validate_fonts( array $fonts ) {
		$validated_fonts = array();

		foreach ( $fonts as $font_faces ) {
			foreach ( $font_faces as $font_face ) {
				$font_face = $this->validate_font_face_declarations( $font_face );
				// Skip if failed validation.
				if ( false === $font_face ) {
					continue;
				}

				$validated_fonts[] = $font_face;
			}
		}

		return $validated_fonts;
	}

	/**
	 * Validates each font-face declaration (property and value pairing).
	 *
	 * @since 6.4.0
	 *
	 * @param array $font_face Font face property and value pairings to validate.
	 * @return array|false Validated font-face on success, or false on failure.
	 */
	private function validate_font_face_declarations( array $font_face ) {
		$font_face = wp_parse_args( $font_face, $this->font_face_property_defaults );

		// Check the font-family.
		if ( empty( $font_face['font-family'] ) || ! is_string( $font_face['font-family'] ) ) {
			// @todo replace with `wp_trigger_error()`.
			_doing_it_wrong(
				__METHOD__,
				__( 'Font font-family must be a non-empty string.' ),
				'6.4.0'
			);
			return false;
		}

		// Make sure that local fonts have 'src' defined.
		if ( empty( $font_face['src'] ) || ( ! is_string( $font_face['src'] ) && ! is_array( $font_face['src'] ) ) ) {
			// @todo replace with `wp_trigger_error()`.
			_doing_it_wrong(
				__METHOD__,
				__( 'Font src must be a non-empty string or an array of strings.' ),
				'6.4.0'
			);
			return false;
		}

		// Validate the 'src' property.
		foreach ( (array) $font_face['src'] as $src ) {
			if ( empty( $src ) || ! is_string( $src ) ) {
				// @todo replace with `wp_trigger_error()`.
				_doing_it_wrong(
					__METHOD__,
					__( 'Each font src must be a non-empty string.' ),
					'6.4.0'
				);
				return false;
			}
		}

		// Check the font-weight.
		if ( ! is_string( $font_face['font-weight'] ) && ! is_int( $font_face['font-weight'] ) ) {
			// @todo replace with `wp_trigger_error()`.
			_doing_it_wrong(
				__METHOD__,
				__( 'Font font-weight must be a properly formatted string or integer.' ),
				'6.4.0'
			);
			return false;
		}

		// Check the font-display.
		if ( ! in_array( $font_face['font-display'], $this->valid_font_display, true ) ) {
			$font_face['font-display'] = $this->font_face_property_defaults['font-display'];
		}

		// Remove invalid properties.
		foreach ( $font_face as $property => $value ) {
			if ( ! in_array( $property, $this->valid_font_face_properties, true ) ) {
				unset( $font_face[ $property ] );
			}
		}

		return $font_face;
	}

	/**
	 * Gets the style element for wrapping the `@font-face` CSS.
	 *
	 * @since 6.4.0
	 *
	 * @return string The style element.
	 */
	private function get_style_element() {
		$attributes = $this->generate_style_element_attributes();

		return "<style class='wp-fonts-local'{$attributes}>n%sn</style>n";
	}

	/**
	 * Gets the defined <style> element's attributes.
	 *
	 * @since 6.4.0
	 *
	 * @return string A string of attribute=value when defined, else, empty string.
	 */
	private function generate_style_element_attributes() {
		$attributes = '';
		foreach ( $this->style_tag_attrs as $name => $value ) {
			$attributes .= " {$name}='{$value}'";
		}
		return $attributes;
	}

	/**
	 * Gets the `@font-face` CSS styles for locally-hosted font files.
	 *
	 * This method does the following processing tasks:
	 *    1. Orchestrates an optimized `src` (with format) for browser support.
	 *    2. Generates the `@font-face` for all its fonts.
	 *
	 * @since 6.4.0
	 *
	 * @param array[] $font_faces The font-faces to generate @font-face CSS styles.
	 * @return string The `@font-face` CSS styles.
	 */
	private function get_css( $font_faces ) {
		$css = '';

		foreach ( $font_faces as $font_face ) {
				// Order the font's `src` items to optimize for browser support.
				$font_face = $this->order_src( $font_face );

				// Build the @font-face CSS for this font.
				$css .= '@font-face{' . $this->build_font_face_css( $font_face ) . '}' . "n";
		}

		// Don't print the last newline character.
		return rtrim( $css, "n" );
	}

	/**
	 * Orders `src` items to optimize for browser support.
	 *
	 * @since 6.4.0
	 *
	 * @param array $font_face Font face to process.
	 * @return array Font-face with ordered src items.
	 */
	private function order_src( array $font_face ) {
		if ( ! is_array( $font_face['src'] ) ) {
			$font_face['src'] = (array) $font_face['src'];
		}

		$src         = array();
		$src_ordered = array();

		foreach ( $font_face['src'] as $url ) {
			// Add data URIs first.
			if ( str_starts_with( trim( $url ), 'data:' ) ) {
				$src_ordered[] = array(
					'url'    => $url,
					'format' => 'data',
				);
				continue;
			}
			$format         = pathinfo( $url, PATHINFO_EXTENSION );
			$src[ $format ] = $url;
		}

		// Add woff2.
		if ( ! empty( $src['woff2'] ) ) {
			$src_ordered[] = array(
				'url'    => $src['woff2'],
				'format' => 'woff2',
			);
		}

		// Add woff.
		if ( ! empty( $src['woff'] ) ) {
			$src_ordered[] = array(
				'url'    => $src['woff'],
				'format' => 'woff',
			);
		}

		// Add ttf.
		if ( ! empty( $src['ttf'] ) ) {
			$src_ordered[] = array(
				'url'    => $src['ttf'],
				'format' => 'truetype',
			);
		}

		// Add eot.
		if ( ! empty( $src['eot'] ) ) {
			$src_ordered[] = array(
				'url'    => $src['eot'],
				'format' => 'embedded-opentype',
			);
		}

		// Add otf.
		if ( ! empty( $src['otf'] ) ) {
			$src_ordered[] = array(
				'url'    => $src['otf'],
				'format' => 'opentype',
			);
		}
		$font_face['src'] = $src_ordered;

		return $font_face;
	}

	/**
	 * Builds the font-family's CSS.
	 *
	 * @since 6.4.0
	 *
	 * @param array $font_face Font face to process.
	 * @return string This font-family's CSS.
	 */
	private function build_font_face_css( array $font_face ) {
		$css = '';

		/*
		 * Wrap font-family in quotes if it contains spaces
		 * and is not already wrapped in quotes.
		 */
		if (
			str_contains( $font_face['font-family'], ' ' ) &&
			! str_contains( $font_face['font-family'], '"' ) &&
			! str_contains( $font_face['font-family'], "'" )
		) {
			$font_face['font-family'] = '"' . $font_face['font-family'] . '"';
		}

		foreach ( $font_face as $key => $value ) {
			// Compile the "src" parameter.
			if ( 'src' === $key ) {
				$value = $this->compile_src( $value );
			}

			// If font-variation-settings is an array, convert it to a string.
			if ( 'font-variation-settings' === $key && is_array( $value ) ) {
				$value = $this->compile_variations( $value );
			}

			if ( ! empty( $value ) ) {
				$css .= "$key:$value;";
			}
		}

		return $css;
	}

	/**
	 * Compiles the `src` into valid CSS.
	 *
	 * @since 6.4.0
	 *
	 * @param array $value Value to process.
	 * @return string The CSS.
	 */
	private function compile_src( array $value ) {
		$src = '';

		foreach ( $value as $item ) {
			$src .= ( 'data' === $item['format'] )
				? ", url({$item['url']})"
				: ", url('{$item['url']}') format('{$item['format']}')";
		}

		$src = ltrim( $src, ', ' );
		return $src;
	}

	/**
	 * Compiles the font variation settings.
	 *
	 * @since 6.4.0
	 *
	 * @param array $font_variation_settings Array of font variation settings.
	 * @return string The CSS.
	 */
	private function compile_variations( array $font_variation_settings ) {
		$variations = '';

		foreach ( $font_variation_settings as $key => $value ) {
			$variations .= "$key $value";
		}

		return $variations;
	}
}

View all references View on Trac View on GitHub

Changelog

VersionDescription
6.4.0Introduced.

User Contributed Notes

You must log in before being able to contribute a note or feedback.

{“prefetch”:[{“source”:”document”,”where”:{“and”:[{“href_matches”:”/*”},{“not”:{“href_matches”:[“/wp-*.php”,”/wp-admin/*”,”/files/*”,”/wp-content/*”,”/wp-content/plugins/*”,”/wp-content/themes/wporg-developer-2023/*”,”/wp-content/themes/wporg-parent-2021/*”,”/*\?(.+)”]}},{“not”:{“selector_matches”:”a[rel~=”nofollow”]”}},{“not”:{“selector_matches”:”.no-prefetch, .no-prefetch a”}}]},”eagerness”:”conservative”}]} var prism_settings = {“pluginUrl”:”https://developer.wordpress.org/wp-content/plugins/code-syntax-block/”}; //# sourceURL=mkaz-code-syntax-prism-js-js-extra var autocomplete = {“ajaxurl”:”https://developer.wordpress.org/wp-admin/admin-ajax.php”,”nonce”:”a22d1a9404″,”post_type”:”wp-parser-class”}; //# sourceURL=autocomplete-js-extra wp.i18n.setLocaleData( { ‘text directionu0004ltr’: [ ‘ltr’ ] } ); //# sourceURL=wp-i18n-js-after var wporgFunctionReferenceI18n = {“copy”:”Copy”,”copied”:”Code copied”,”expand”:”Expand code”,”collapse”:”Collapse code”,”sourceFile”:”wp-includes/fonts/class-wp-font-face.php”}; //# sourceURL=wporg-developer-function-reference-js-extra var quicktagsL10n = {“closeAllOpenTags”:”Close all open tags”,”closeTags”:”close tags”,”enterURL”:”Enter the URL”,”enterImageURL”:”Enter the URL of the image”,”enterImageDescription”:”Enter a description of the image”,”textdirection”:”text direction”,”toggleTextdirection”:”Toggle Editor Text Direction”,”dfw”:”Distraction-free writing mode”,”strong”:”Bold”,”strongClose”:”Close bold tag”,”em”:”Italic”,”emClose”:”Close italic tag”,”link”:”Insert link”,”blockquote”:”Blockquote”,”blockquoteClose”:”Close blockquote tag”,”del”:”Deleted text (strikethrough)”,”delClose”:”Close deleted text tag”,”ins”:”Inserted text”,”insClose”:”Close inserted text tag”,”image”:”Insert image”,”ul”:”Bulleted list”,”ulClose”:”Close bulleted list tag”,”ol”:”Numbered list”,”olClose”:”Close numbered list tag”,”li”:”List item”,”liClose”:”Close list item tag”,”code”:”Code”,”codeClose”:”Close code tag”,”more”:”Insert Read More tag”}; //# sourceURL=quicktags-js-extra var wporg_note_feedback = {“show”:”Show feedback”,”hide”:”Hide feedback”,”hide_feedback”:”Hide feedback form”,”add_feedback”:”Add feedback”}; //# sourceURL=wporg-developer-user-notes-feedback-js-extra var wporg_note_preview = {“ajaxurl”:”https://developer.wordpress.org/wp-admin/admin-ajax.php”,”nonce”:”de3c1c9510″,”preview”:”preview note”,”preview_empty”:”Nothing to preview”,”is_admin”:””}; //# sourceURL=wporg-developer-preview-js-extra _stq = window._stq || []; _stq.push([ “view”, {“v”:”ext”,”blog”:”209306761″,”post”:”149949″,”tz”:”0″,”srv”:”developer.wordpress.org”,”j”:”1:15.5″} ]); _stq.push([ “clickTrackerInit”, “209306761”, “149949” ]); //# sourceURL=jetpack-stats-js-before var wporgGlobalHeaderI18n = {“openSearchLabel”:”Open Search”,”closeSearchLabel”:”Close Search”,”overflowMenuLabel”:”More menu”}; //# sourceURL=wporg-global-header-script-js-extra {“baseUrl”:”https://s.w.org/images/core/emoji/17.0.2/72×72/”,”ext”:”.png”,”svgUrl”:”https://s.w.org/images/core/emoji/17.0.2/svg/”,”svgExt”:”.svg”,”source”:{“concatemoji”:”https://developer.wordpress.org/wp-includes/js/wp-emoji-release.min.js?ver=7.1-alpha-62244″}} /*! This file is auto-generated */ const a=JSON.parse(document.getElementById(“wp-emoji-settings”).textContent),o=(window._wpemojiSettings=a,”wpEmojiSettingsSupports”),s=[“flag”,”emoji”];function i(e){try{var t={supportTests:e,timestamp:(new Date).valueOf()};sessionStorage.setItem(o,JSON.stringify(t))}catch(e){}}function c(e,t,n){e.clearRect(0,0,e.canvas.width,e.canvas.height),e.fillText(t,0,0);t=new Uint32Array(e.getImageData(0,0,e.canvas.width,e.canvas.height).data);e.clearRect(0,0,e.canvas.width,e.canvas.height),e.fillText(n,0,0);const a=new Uint32Array(e.getImageData(0,0,e.canvas.width,e.canvas.height).data);return t.every((e,t)=>e===a[t])}function p(e,t){e.clearRect(0,0,e.canvas.width,e.canvas.height),e.fillText(t,0,0);var n=e.getImageData(16,16,1,1);for(let e=0;e{s[e]=t(o,e,n,a)}),s}function r(e){var t=document.createElement(“script”);t.src=e,t.defer=!0,document.head.appendChild(t)}a.supports={everything:!0,everythingExceptFlag:!0},new Promise(t=>{let n=function(){try{var e=JSON.parse(sessionStorage.getItem(o));if(“object”==typeof e&&”number”==typeof e.timestamp&&(new Date).valueOf(){i(n=e.data),r.terminate(),t(n)})}catch(e){}i(n=f(s,u,c,p))}t(n)}).then(e=>{for(const n in e)a.supports[n]=e[n],a.supports.everything=a.supports.everything&&a.supports[n],”flag”!==n&&(a.supports.everythingExceptFlag=a.supports.everythingExceptFlag&&a.supports[n]);var t;a.supports.everythingExceptFlag=a.supports.everythingExceptFlag&&!a.supports.flag,a.supports.everything||((t=a.source||{}).concatemoji?r(t.concatemoji):t.wpemoji&&t.twemoji&&(r(t.twemoji),r(t.wpemoji)))}); //# sourceURL=https://developer.wordpress.org/wp-includes/js/wp-emoji-loader.min.js