云策 WordPress 开发者社区

钩子文档

image_size_names_choose

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

概述

image_size_names_choose 是一个 WordPress 过滤器，用于修改默认图像尺寸的名称和标签，使自定义图像尺寸在 WordPress 媒体库中可供管理员选择。

关键要点

  • 过滤器参数为 $size_names，是一个数组，键为图像尺寸名称，值为标签，默认包括 'Thumbnail'、'Medium'、'Large' 和 'Full Size'。
  • 主要用途是让自定义图像尺寸通过 add_image_size() 添加后，能在媒体库中显示为可选选项。
  • 过滤器在 WordPress 3.3.0 版本中引入，常用于主题或插件开发中。

代码示例

// 添加自定义图像尺寸
function custom_theme_setup() {
    add_image_size( 'custom-size-1', 1200, 300, true );
    add_image_size( 'custom-size-2', 1000, 333, true );
}
add_action( 'after_setup_theme', 'custom_theme_setup' );

// 使自定义尺寸在媒体库中可选
function custom_image_sizes( $size_names ) {
    $new_sizes = array(
        'custom-size-1' => __( 'Custom Size #1', 'generatewp.com' ),
        'custom-size-2' => __( 'Custom Size #2', 'generatewp.com' ),
    );
    return array_merge( $size_names, $new_sizes );
}
add_filter( 'image_size_names_choose', 'custom_image_sizes' );
📄 原文内容

Filters the names and labels of the default image sizes.

Parameters

$size_namesstring[]
Array of image size labels keyed by their name. Default values include 'Thumbnail', 'Medium', 'Large', and ‘Full Size’.

More Information

The ‘image_size_names_choose‘ filter allows modification of the list of image sizes that are available to administrators in the WordPress Media Library.

This is most commonly used to make custom image sizes available from selection in the WordPress admin.

Source

$size_names = apply_filters(
	'image_size_names_choose',
	array(
		'thumbnail' => __( 'Thumbnail' ),
		'medium'    => __( 'Medium' ),
		'large'     => __( 'Large' ),
		'full'      => __( 'Full Size' ),
	)
);

View all references View on Trac View on GitHub

Used by Description
get_default_block_editor_settings()wp-includes/block-editor.php

Returns the default block editor settings.
image_size_input_fields()wp-admin/includes/media.php

Retrieves HTML for the size radio buttons with the specified one checked.
Custom_Background::wp_set_background_image()wp-admin/includes/class-custom-background.php
wp_prepare_attachment_for_js()wp-includes/media.php

Prepares an attachment post object for JS, where it is expected to be JSON-encoded and fit into an Attachment model.
wp_print_media_templates()wp-includes/media-template.php

Prints the templates used in the media manager.

Changelog

Version Description
3.3.0 Introduced.

User Contributed Notes

  1. Skip to note 3 content


    Rami Yushuvaev


    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

    Add a new image sizes to the Media Library .

    // Add images sizes.
function custom_theme_setup() {
	add_image_size( 'custom-size-1', 1200, 300, true );
	add_image_size( 'custom-size-2', 1000, 333, true );
}
add_action( 'after_setup_theme', 'custom_theme_setup' );

// Make custom sizes selectable from WordPress admin.
function custom_image_sizes( $size_names ) {
	$new_sizes = array(
		'custom-size-1' => __( 'Custom Size #1', 'generatewp.com' ),
		'custom-size-2' => __( 'Custom Size #2', 'generatewp.com' ),
	);
	return array_merge( $size_names, $new_sizes );
}
add_filter( 'image_size_names_choose', 'custom_image_sizes' );

  2. Skip to note 4 content


    Steven Lin


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    Example migrated from Codex:

    The following will add a new image size option to the list of selectable sizes in the Media Library.

    add_filter( 'image_size_names_choose', 'my_custom_sizes' );

function my_custom_sizes( $sizes ) {
    return array_merge( $sizes, array(
        'your-custom-size' => __('Your Custom Size Name'),
    ) );
}