云策 WordPress 开发者社区

函数文档

load_image_to_edit()

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

概述

load_image_to_edit() 函数用于加载图像资源以进行编辑，根据附件 ID、MIME 类型和尺寸返回 GD 图像资源或 false。

关键要点

  • 参数：$attachment_id（整数，必需，附件 ID）、$mime_type（字符串，必需，图像 MIME 类型）、$size（字符串或整数数组，可选，图像尺寸，默认 'full'）。
  • 返回值：成功时返回 resource 或 GdImage 实例，失败时返回 false。
  • 支持 MIME 类型：image/jpeg、image/png、image/gif、image/webp（需 PHP 支持）。
  • 使用 apply_filters('load_image_to_edit', ...) 钩子过滤加载的图像。
  • 内部调用 _load_image_to_edit_path() 获取文件路径，并使用 is_gd_image() 检查图像类型。

代码示例

function load_image_to_edit( $attachment_id, $mime_type, $size = 'full' ) {
	$filepath = _load_image_to_edit_path( $attachment_id, $size );
	if ( empty( $filepath ) ) {
		return false;
	}

	switch ( $mime_type ) {
		case 'image/jpeg':
			$image = imagecreatefromjpeg( $filepath );
			break;
		case 'image/png':
			$image = imagecreatefrompng( $filepath );
			break;
		case 'image/gif':
			$image = imagecreatefromgif( $filepath );
			break;
		case 'image/webp':
			$image = false;
			if ( function_exists( 'imagecreatefromwebp' ) ) {
				$image = imagecreatefromwebp( $filepath );
			}
			break;
		default:
			$image = false;
			break;
	}

	if ( is_gd_image( $image ) ) {
		$image = apply_filters( 'load_image_to_edit', $image, $attachment_id, $size );

		if ( function_exists( 'imagealphablending' ) && function_exists( 'imagesavealpha' ) ) {
			imagealphablending( $image, false );
			imagesavealpha( $image, true );
		}
	}

	return $image;
}

注意事项

  • 对于 image/webp 类型，需确保 PHP 支持 imagecreatefromwebp() 函数。
  • 函数内部使用 imagealphablending() 和 imagesavealpha() 处理 PNG 等图像的透明度（如果可用）。
  • 自 WordPress 2.9.0 版本引入。
📄 原文内容

Loads an image resource for editing.

Parameters

$attachment_idintrequired
Attachment ID.
$mime_typestringrequired
Image mime type.
$sizestring|int[]optional
Image size. Accepts any registered image size name, or an array of width and height values in pixels (in that order). Default 'full'.

Return

resource|GdImage|false The resulting image resource or GdImage instance on success, false on failure.

Source

function load_image_to_edit( $attachment_id, $mime_type, $size = 'full' ) {
	$filepath = _load_image_to_edit_path( $attachment_id, $size );
	if ( empty( $filepath ) ) {
		return false;
	}

	switch ( $mime_type ) {
		case 'image/jpeg':
			$image = imagecreatefromjpeg( $filepath );
			break;
		case 'image/png':
			$image = imagecreatefrompng( $filepath );
			break;
		case 'image/gif':
			$image = imagecreatefromgif( $filepath );
			break;
		case 'image/webp':
			$image = false;
			if ( function_exists( 'imagecreatefromwebp' ) ) {
				$image = imagecreatefromwebp( $filepath );
			}
			break;
		default:
			$image = false;
			break;
	}

	if ( is_gd_image( $image ) ) {
		/**
		 * Filters the current image being loaded for editing.
		 *
		 * @since 2.9.0
		 *
		 * @param resource|GdImage $image         Current image.
		 * @param int              $attachment_id Attachment ID.
		 * @param string|int[]     $size          Requested image size. Can be any registered image size name, or
		 *                                        an array of width and height values in pixels (in that order).
		 */
		$image = apply_filters( 'load_image_to_edit', $image, $attachment_id, $size );

		if ( function_exists( 'imagealphablending' ) && function_exists( 'imagesavealpha' ) ) {
			imagealphablending( $image, false );
			imagesavealpha( $image, true );
		}
	}

	return $image;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘load_image_to_edit’, resource|GdImage $image, int $attachment_id, string|int[] $size )

Filters the current image being loaded for editing.

Uses Description
is_gd_image()wp-includes/media.php

Determines whether the value is an acceptable type for GD image functions.
_load_image_to_edit_path()wp-admin/includes/image.php

Retrieves the path or URL of an attachment’s attached file.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.

Show 1 moreShow less

Changelog

Version Description
2.9.0 Introduced.