云策 WordPress 开发者社区

类文档

WP_Font_Library

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

概述

WP_Font_Library 是 WordPress 6.5.0 引入的字体库类，用于管理字体集合的注册、获取和注销。它采用单例模式，提供核心方法来操作字体集合。

关键要点

  • WP_Font_Library 类用于处理字体集合，包括注册、注销和查询功能。
  • 使用单例模式，通过 WP_Font_Library::get_instance() 获取主实例。
  • 主要方法包括 register_font_collection、unregister_font_collection、get_font_collection、get_font_collections 和 is_collection_registered。
  • 字体集合以 slug 为键存储在私有数组 $collections 中，确保唯一性。
  • 注册时检查重复性，返回 WP_Font_Collection 对象或 WP_Error；注销时返回布尔值表示成功与否。

代码示例

// 获取 WP_Font_Library 实例
$font_library = WP_Font_Library::get_instance();

// 注册字体集合
$collection = $font_library->register_font_collection( 'my-fonts', $args );
if ( is_wp_error( $collection ) ) {
    // 处理错误
}

// 获取所有字体集合
$collections = $font_library->get_font_collections();

// 获取特定字体集合
$specific_collection = $font_library->get_font_collection( 'my-fonts' );

// 注销字体集合
$unregistered = $font_library->unregister_font_collection( 'my-fonts' );

注意事项

  • slug 参数应仅包含字母数字字符、破折号和下划线，使用 sanitize_title() 进行清理。
  • 注册重复的 slug 会触发 _doing_it_wrong 并返回 WP_Error。
  • 注销不存在的集合会触发 _doing_it_wrong 并返回 false。
  • is_collection_registered 是私有方法，用于内部检查。
  • 该类自 WordPress 6.5.0 版本引入。
📄 原文内容

Font Library class.

Methods

Name Description
WP_Font_Library::get_font_collection Gets a font collection.
WP_Font_Library::get_font_collections Gets all the font collections available.
WP_Font_Library::get_instance Utility method to retrieve the main instance of the class.
WP_Font_Library::is_collection_registered Checks if a font collection is registered.
WP_Font_Library::register_font_collection Register a new font collection.
WP_Font_Library::unregister_font_collection Unregisters a previously registered font collection.

Source

class WP_Font_Library {

	/**
	 * Font collections.
	 *
	 * @since 6.5.0
	 * @var array
	 */
	private $collections = array();

	/**
	 * Container for the main instance of the class.
	 *
	 * @since 6.5.0
	 * @var WP_Font_Library|null
	 */
	private static $instance = null;

	/**
	 * Register a new font collection.
	 *
	 * @since 6.5.0
	 *
	 * @param string $slug Font collection slug. May only contain alphanumeric characters, dashes,
	 *                     and underscores. See sanitize_title().
	 * @param array  $args Font collection data. See wp_register_font_collection() for information on accepted arguments.
	 * @return WP_Font_Collection|WP_Error A font collection if it was registered successfully,
	 *                                     or WP_Error object on failure.
	 */
	public function register_font_collection( string $slug, array $args ) {
		$new_collection = new WP_Font_Collection( $slug, $args );

		if ( $this->is_collection_registered( $new_collection->slug ) ) {
			$error_message = sprintf(
				/* translators: %s: Font collection slug. */
				__( 'Font collection with slug: "%s" is already registered.' ),
				$new_collection->slug
			);
			_doing_it_wrong(
				__METHOD__,
				$error_message,
				'6.5.0'
			);
			return new WP_Error( 'font_collection_registration_error', $error_message );
		}
		$this->collections[ $new_collection->slug ] = $new_collection;
		return $new_collection;
	}

	/**
	 * Unregisters a previously registered font collection.
	 *
	 * @since 6.5.0
	 *
	 * @param string $slug Font collection slug.
	 * @return bool True if the font collection was unregistered successfully and false otherwise.
	 */
	public function unregister_font_collection( string $slug ) {
		if ( ! $this->is_collection_registered( $slug ) ) {
			_doing_it_wrong(
				__METHOD__,
				/* translators: %s: Font collection slug. */
				sprintf( __( 'Font collection "%s" not found.' ), $slug ),
				'6.5.0'
			);
			return false;
		}
		unset( $this->collections[ $slug ] );
		return true;
	}

	/**
	 * Checks if a font collection is registered.
	 *
	 * @since 6.5.0
	 *
	 * @param string $slug Font collection slug.
	 * @return bool True if the font collection is registered and false otherwise.
	 */
	private function is_collection_registered( string $slug ) {
		return array_key_exists( $slug, $this->collections );
	}

	/**
	 * Gets all the font collections available.
	 *
	 * @since 6.5.0
	 *
	 * @return array List of font collections.
	 */
	public function get_font_collections() {
		return $this->collections;
	}

	/**
	 * Gets a font collection.
	 *
	 * @since 6.5.0
	 *
	 * @param string $slug Font collection slug.
	 * @return WP_Font_Collection|null Font collection object, or null if the font collection doesn't exist.
	 */
	public function get_font_collection( string $slug ) {
		if ( $this->is_collection_registered( $slug ) ) {
			return $this->collections[ $slug ];
		}
		return null;
	}

	/**
	 * Utility method to retrieve the main instance of the class.
	 *
	 * The instance will be created if it does not exist yet.
	 *
	 * @since 6.5.0
	 *
	 * @return WP_Font_Library The main instance.
	 */
	public static function get_instance() {
		if ( null === self::$instance ) {
			self::$instance = new self();
		}

		return self::$instance;
	}
}

View all references View on Trac View on GitHub

Changelog

Version Description
6.5.0 Introduced.