函数文档

get_default_block_editor_settings()

💡 云策文档标注

概述

get_default_block_editor_settings() 函数返回默认的块编辑器设置数组,包含媒体设置、主题支持和实验性功能等配置。这些设置用于初始化块编辑器环境,确保一致性和兼容性。

关键要点

  • 函数返回一个数组,包含 alignWide、allowedBlockTypes、allowedMimeTypes、defaultEditorStyles、blockCategories、isRTL、imageDefaultSize、imageDimensions、imageEditing、imageSizes、maxUploadFileSize 等键值对。
  • 媒体设置部分处理上传文件大小(基于用户权限)、图像尺寸名称和默认尺寸,并应用 image_size_names_choose 过滤器。
  • 主题设置通过 get_classic_theme_supports_block_editor_settings() 合并到编辑器设置中,以支持经典主题。
  • 包含实验性功能如 __experimentalDashboardLink 和 __unstableGalleryWithImageBlocks,用于移动应用兼容性。
  • 函数内部使用多个 WordPress 核心函数,如 wp_max_upload_size()、get_theme_support()、is_rtl() 等,确保设置基于当前环境和用户权限。

代码示例

// 示例:获取默认块编辑器设置
$default_settings = get_default_block_editor_settings();
print_r($default_settings);

注意事项

  • maxUploadFileSize 的值取决于当前用户的 upload_files 权限,若无权限则设为 0。
  • imageDefaultSize 基于 image_default_size 选项,默认为 'large',但会验证是否在可用尺寸列表中。
  • defaultEditorStyles 从默认 CSS 文件加载,仅在文件存在时包含,用于无主题样式的情况。
  • 函数自 WordPress 5.8.0 版本引入,是块编辑器 API 的一部分。

📄 原文内容

Returns the default block editor settings.

Return

array The default block editor settings.

Source

function get_default_block_editor_settings() {
	// Media settings.

	// wp_max_upload_size() can be expensive, so only call it when relevant for the current user.
	$max_upload_size = 0;
	if ( current_user_can( 'upload_files' ) ) {
		$max_upload_size = wp_max_upload_size();
		if ( ! $max_upload_size ) {
			$max_upload_size = 0;
		}
	}

	/** This filter is documented in wp-admin/includes/media.php */
	$image_size_names = apply_filters(
		'image_size_names_choose',
		array(
			'thumbnail' => __( 'Thumbnail' ),
			'medium'    => __( 'Medium' ),
			'large'     => __( 'Large' ),
			'full'      => __( 'Full Size' ),
		)
	);

	$available_image_sizes = array();
	foreach ( $image_size_names as $image_size_slug => $image_size_name ) {
		$available_image_sizes[] = array(
			'slug' => $image_size_slug,
			'name' => $image_size_name,
		);
	}

	$default_size       = get_option( 'image_default_size', 'large' );
	$image_default_size = in_array( $default_size, array_keys( $image_size_names ), true ) ? $default_size : 'large';

	$image_dimensions = array();
	$all_sizes        = wp_get_registered_image_subsizes();
	foreach ( $available_image_sizes as $size ) {
		$key = $size['slug'];
		if ( isset( $all_sizes[ $key ] ) ) {
			$image_dimensions[ $key ] = $all_sizes[ $key ];
		}
	}

	// These styles are used if the "no theme styles" options is triggered or on
	// themes without their own editor styles.
	$default_editor_styles_file = ABSPATH . WPINC . '/css/dist/block-editor/default-editor-styles.css';

	static $default_editor_styles_file_contents = false;
	if ( ! $default_editor_styles_file_contents && file_exists( $default_editor_styles_file ) ) {
		$default_editor_styles_file_contents = file_get_contents( $default_editor_styles_file );
	}

	$default_editor_styles = array();
	if ( $default_editor_styles_file_contents ) {
		$default_editor_styles = array(
			array( 'css' => $default_editor_styles_file_contents ),
		);
	}

	$editor_settings = array(
		'alignWide'                        => get_theme_support( 'align-wide' ),
		'allowedBlockTypes'                => true,
		'allowedMimeTypes'                 => get_allowed_mime_types(),
		'defaultEditorStyles'              => $default_editor_styles,
		'blockCategories'                  => get_default_block_categories(),
		'isRTL'                            => is_rtl(),
		'imageDefaultSize'                 => $image_default_size,
		'imageDimensions'                  => $image_dimensions,
		'imageEditing'                     => true,
		'imageSizes'                       => $available_image_sizes,
		'maxUploadFileSize'                => $max_upload_size,
		'__experimentalDashboardLink'      => admin_url( '/' ),
		// The following flag is required to enable the new Gallery block format on the mobile apps in 5.9.
		'__unstableGalleryWithImageBlocks' => true,
	);

	$theme_settings = get_classic_theme_supports_block_editor_settings();
	foreach ( $theme_settings as $key => $value ) {
		$editor_settings[ $key ] = $value;
	}

	return $editor_settings;
}

Hooks

apply_filters( ‘image_size_names_choose’, string[] $size_names )

Filters the names and labels of the default image sizes.

Changelog

Version Description
5.8.0 Introduced.