Function Reference/add image size

来自WordPress中文文档
跳转至: 导航搜索

wordpress.org.cn

Description

Registers a new image size. This means that WordPress will create a copy of the Featured Image (formerly known as post thumbnail) with the specified dimensions when you upload a new image.

Note: To enable featured images, or post thumbnails, the current theme must include add_theme_support( 'post-thumbnails' ); in its functions.php file. See also Post Thumbnails.

Usage

%%%<?php add_image_size( $name, $width, $height, $crop ); ?>%%%

Parameters

tt$name/tt
(string) (required) The new image size name.
Default: Nonenoinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Notes

This template is for standardizing how parameters look in the Function Reference and in Template Tags. Here is an example of this template being called: prenowiki检查到模板循环:模板:Parameter/nowiki/pre 检查到模板循环:模板:Parameter

The usage of this template is below: prenowiki检查到模板循环:模板:Parameter/nowiki/pre Let's take a closer look at the parameters..

name
The name of the parameter.
datatype
The datatype that should be given for this parameter when called.
  • string
  • integer
  • boolean
  • mixed
description
A short description of the parameter.
importance
Set this parameter to optional if the parameter is optional. Otherwise, do not declare this parameter—it defaults to required.
  • required
  • optional
default
If this parameter is optional, ttdefault/tt is the value that will be used if the parameter is not declared.

wordpress.org.cn /div /noinclude

tt$width/tt
(int) (optional) The post thumbnail width in pixels.
Default: 0noinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Notes

This template is for standardizing how parameters look in the Function Reference and in Template Tags. Here is an example of this template being called: prenowiki检查到模板循环:模板:Parameter/nowiki/pre 检查到模板循环:模板:Parameter

The usage of this template is below: prenowiki检查到模板循环:模板:Parameter/nowiki/pre Let's take a closer look at the parameters..

name
The name of the parameter.
datatype
The datatype that should be given for this parameter when called.
  • string
  • integer
  • boolean
  • mixed
description
A short description of the parameter.
importance
Set this parameter to optional if the parameter is optional. Otherwise, do not declare this parameter—it defaults to required.
  • required
  • optional
default
If this parameter is optional, ttdefault/tt is the value that will be used if the parameter is not declared.

wordpress.org.cn /div /noinclude

tt$height/tt
(int) (optional) The post thumbnail height in pixels.
Default: 0noinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Notes

This template is for standardizing how parameters look in the Function Reference and in Template Tags. Here is an example of this template being called: prenowiki检查到模板循环:模板:Parameter/nowiki/pre 检查到模板循环:模板:Parameter

The usage of this template is below: prenowiki检查到模板循环:模板:Parameter/nowiki/pre Let's take a closer look at the parameters..

name
The name of the parameter.
datatype
The datatype that should be given for this parameter when called.
  • string
  • integer
  • boolean
  • mixed
description
A short description of the parameter.
importance
Set this parameter to optional if the parameter is optional. Otherwise, do not declare this parameter—it defaults to required.
  • required
  • optional
default
If this parameter is optional, ttdefault/tt is the value that will be used if the parameter is not declared.

wordpress.org.cn /div /noinclude

tt$crop/tt
(boolean) (optional) Crop the image or not. False - Soft proportional crop mode ; True - Hard crop mode.
Default: falsenoinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Notes

This template is for standardizing how parameters look in the Function Reference and in Template Tags. Here is an example of this template being called: prenowiki检查到模板循环:模板:Parameter/nowiki/pre 检查到模板循环:模板:Parameter

The usage of this template is below: prenowiki检查到模板循环:模板:Parameter/nowiki/pre Let's take a closer look at the parameters..

name
The name of the parameter.
datatype
The datatype that should be given for this parameter when called.
  • string
  • integer
  • boolean
  • mixed
description
A short description of the parameter.
importance
Set this parameter to optional if the parameter is optional. Otherwise, do not declare this parameter—it defaults to required.
  • required
  • optional
default
If this parameter is optional, ttdefault/tt is the value that will be used if the parameter is not declared.

wordpress.org.cn /div /noinclude

Reserved Image Size Names

thumb, thumbnail, medium, large, post-thumbnail

The names "thumb" & "thumbnail" are just alias, so exactly the same.

For a detailed explanation and "why", read further inside the image_downsize() article.

However, if needed, you can always set the options yourself:

update_option('thumbnail_size_w', 160);
update_option('thumbnail_size_h', 160);
update_option('thumbnail_crop', 1);

Examples

A theme's functions.php file.

if ( function_exists( 'add_theme_support' ) ) {
	add_theme_support( 'post-thumbnails' );
        set_post_thumbnail_size( 150, 150 ); // default Post Thumbnail dimensions   
}

if ( function_exists( 'add_image_size' ) ) { 
	add_image_size( 'category-thumb', 300, 9999 ); //300 pixels wide (and unlimited height)
	add_image_size( 'homepage-thumb', 220, 180, true ); //(cropped)
}

Crop Mode

Set the image size by resizing the image proportionally (that is, without distorting it):

add_image_size( 'homepage-thumb', 220, 180 ); // 220 pixels wide by 180 pixels tall, soft proportional crop mode

Set the image size by cropping the image (either from the sides, or from the top and bottom):

add_image_size( 'homepage-thumb', 220, 180, true ); // 220 pixels wide by 180 pixels tall, hard crop mode

Using the New Image Sizes

Now that you've defined some custom image sizes, there are a variety of ways that you can use them.

For Featured Images

To use your custom image sizes for a post's featured image, you can use the_post_thumbnail() in the appropriate theme template file...

<?php 
    if ( has_post_thumbnail() ) { 
        the_post_thumbnail( 'your-custom-size' ); 
    } 
?>

For Media Library Images (Admin)

You can also make your custom sizes selectable from your WordPress admin. To do so, you have to use the image_size_names_choose hook to assign them a normal, human-readable name...

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'),
    ) );
}

For General Media (PHP/Templates)

You can output images (by size) directly from the WordPress Media Library using PHP as well. To do this, simply use wp_get_attachment_image()...

// Assuming your Media Library image has a post id of 42...
<?php echo wp_get_attachment_image( 42, 'your-custom-size' ) ?>

Note: If you just want the image URL instead of a pre-built <img> tag, you can use wp_get_attachment_image_src() instead.

Notes

Using the 'false' setting will fail to produce a new image in the upload directory if one of the image dimensions of the uploaded image are equal to the new image size.

Change Log

Source File

add_image_size() is located in onlyincludecodewp-includes/media.php/code/onlyinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Template Description

Link to the source code on http://core.trac.wordpress.org/browser/.

Parameters

  1. filename
  2. (option) path to codetag/code (version) or codetrunk/code. This option is only used for a new function.br /Default: codetrunk/code -- trunk is the latest bleeding edge development version of WordPress.

Usage

Link to the stable version: pre检查到模板循环:模板:Trac/pre

Link to trunk: pre检查到模板循环:模板:Trac/pre

/div

wordpress.org.cn.

Resources

Regenerate Thumbnails - This plugin regenerate the thumbnails for your image attachments. This is very handy if you've changed any of your thumbnail dimensions (via Settings -> Media) after previously uploading images or have changed to a theme with different featured post image dimensions.

AJAX thumbnail rebuild - This plugin allows you to re-build the post thumbnails. Useful if you use add_image_size() after already having uploaded post thumbnails. (This plugin is slow, but never has out of memory errors).

Simple Image Sizes - This plugin allows you create new sizes of thumbnails directly from the "Media" panel. It allows you to regenerate the thumbnails too. The plugin adds the thumbnails to your post sizes and you can add them directly on your posts. You can choose the sizes you wanted to regenerate and the posts types too.

Related

Post Thumbnails: has_post_thumbnail, the_post_thumbnail, get_post_thumbnail_id, get_the_post_thumbnail

includeonlydiv style=clear:both; background-color:#F7F7F7; border:1px solid #CCCCCC; color:#000000; padding:7px; margin:0.5em auto 0.5em auto; vertical-align:middle;See also index of Function Reference and index of Template Tags./div/includeonlynoinclude

Description

This Template is used by Codex:Template Messages.

Usage

pre 检查到模板循环:模板:Message /pre

Result

检查到模板循环:模板:Message

/noinclude