Image - 类別

优质

小牛编辑

132浏览

2023-12-01

Image 类别是用来方便地添加对图片的常见操作，如调整尺寸、剪裁等。

侷限性

Image 类别有一些应该被意识到的侷限性。首先，GD 函式库处理透明度非常糟糕。由于这样，Image::rotate() 不能使用透明背景。在 imagemagick 中圆图也有缺陷，因为有透明边角的图像会在角落得到不透明的圆圈。

在 GD 中使用多个转换，可能会导致不正常的结果。

配置

Image 类别接受以下的配置选项。从 fuel/core/config/image.php 複製档案到 fuel/app/config/image.php

参数	类型	预设	描述
driver	字串	`'gd'`	可以是任何有效函式库的名称，目前只有 'gd'、'imagemagick' 和 'imagick'
bgcolor	字串	`null`	十六进位（例如：#ff0、#4f32de）的背景。要透明背景设为 null。
watermark_alpha	整数	`75`	任何应用到图像的浮水印透明度。範围从 0-100。
quality	整数	`100`	给 jpeg 和 png 图像的品质。
filetype	字串	`null`	定义一个覆写预设图像类型如果没给副档名。如果设为 null，它会继承原本的副档名。
imagemagick_dir	字串	`'/usr/bin/'`	imagemagick 可执行档案的储存位置。必须添加前导斜线。
temp_dir	字串	`'/tmp/'`	要储存被编辑图像档案的临时目录。
temp_append	字串	`'fuel_image'`	要附加到临时图像的字串，避免冲突。
debug	布林	`false`	打开除错模式，它会跳过设定表头并在图像上输出除错资讯。

预设定

预设定是 Image 类别中的功能，允许定义一组任务在配置中，并呼叫该预设定。一个例子是：

在 app/config/image.php

/**
 * 这些预设定能让你呼叫控制操作。
 */
'presets' => array(
	'mypreset' => array(
		'bgcolor' => '#f00', // 设定背景颜色为红色
		'filetype' => 'jpg', // 输出为 jpeg。
		'quality' => 75,
		'actions' => array(
array('crop_resize', 200, 200),
array('watermark', '$1'), // 注意 $1 是一个变数。
array('output', 'png')
		)
	)
)

在你的控制器中：

// 这里的 'watermark.gif' 取代 array('watermark', '$1') 中的 $1
Image::load('filename.gif')->preset('mypreset', 'watermark.gif');

forge($config = array())

forge 方法建立一个新的 Image_Driver 实例。

静态是

参数

参数	预设	描述
`$config`	`array()`	一个给 Image_Driver 实例的配置选项阵列

回传 Image_Driver

範例

$image = Image::forge();

// 或带选择性的配置
$image = Image::forge(array(
	'quality' => 80
));
$image
	->load('image.png')
	->output('image.jpeg');

config($index, $value = null)

变更一个配置选项的值。

静态是

参数

参数	预设	描述
`$index`	必要	要被设定的索引，或一个配置选项阵列。
`$value`	`null`	要被设定的值，如果 $index 不是一个阵列。

回传 Image_Driver

範例

// 调整图像的尺寸，并变更背景。
Image::load('filename.gif')
	->config('bgcolor', '#f00')
	->resize(100, 100, true, true);

load($filename, $return_data = false, $force_extension = false)

load 方法试图载入一个图像来编辑。

静态是

参数

参数	预设	描述
`$filename`	必要	指向要被载入的图像档案路径。
`$return_data`	`false`	侦测是否回传图像资料，只支援 GD。
`$force_extension`	`false`	是否强制图像副档名（成为 $force_extension），只支援 GD。

回传 Image_Driver

範例

// 载入图像
Image::load('filename.gif');

// 上传一个图像并直接传递到 Image::load 方法。
Upload::process(array(
	'path' => DOCROOT.DS.'files'
));

if (Upload::is_valid())
{
	$data = Upload::get_files(0);

	// 使用该上传档案的资料，我们可以强制图像的副档名
	// 透过 $force_extension
	Image::load($data['file'], false, $data['extension'])
		->crop_resize(200, 200)
		->save('image');
}

crop($x1, $y1, $x2, $y2)

使用座标或百分比来裁切图像。

静态是

参数

参数	预设	描述
`$x1`	必要	第一个裁切的 X 轴位置。
`$y1`	必要	第一个裁切的 Y 轴位置。
`$x2`	必要	第二个裁切的 X 轴位置。
`$y2`	必要	第二个裁切的 Y 轴位置。

回传 Image_Driver

範例

// 为了这个範例的目的，图像的宽和高是 200x200

// 裁切图像从 (20, 20) 到 (180, 180)
Image::load('filename.gif')
	->crop(20, 20, 180, 180);

// 裁切图像从 (40, 40) 到 (160, 160) 使用负数。
Image::load('filename.gif')
	->crop(40, 40, -40, -40);

// 裁切图像从 (30, 30) 到 (170, 170) 混合使用百分比及负数。
Image::load('filename.gif')
	->crop('15%', '15%', '-15%', '-15%');

resize($width, $height = null, $keepar = true, $pad = false)

调整图像尺寸。如果宽度或高度是 null，它会保留原有的宽高比来调整。

静态是

参数

参数	预设	描述
`$width`	必要	图像的新宽度。
`$height`	`null`	图像的新高度。
`$keepar`	`true`	如果设为 true，将保留与原图像相同的宽高比。
`$pad`	`false`	如果设为 true 且 $keepar 为 true，它会用配置的 bgcolor 来填充图像。

回传 Image_Driver

範例

// 使用绝对值调整尺寸
Image::load('filename.gif')
	->resize(100, 100);

// 使用百分比调整尺寸
Image::load('filename.gif')
	->resize('50%', '50%');

// 拉伸图像以适应
Image::load('filename.gif')
	->resize(100, 100, false);

// 填充图像以保持输入的尺寸及宽高比。
Image::load('filename.gif')
	->resize(100, 200, true, true);

crop_resize($width, $height = null)

调整图像尺寸并裁切成适应所给的宽和高。

静态是

参数

参数	预设	描述
`$width`	必要	图像的新宽度。
`$height`	`null`	图像的新高度。

回传 Image_Driver

範例

// 用法範例，裁切一个 300x200 图像为 200x200 会在顶部及底部移除 50px
Image::load('filename.gif')
	->crop_resize(200, 200);

rotate($degrees)

顺时针方向旋转图像。

静态是

参数

参数	预设	描述
`$degrees`	必要	图像要转动的角度。接受正数及负数。

回传 Image_Driver

範例

// 顺时针方向旋转 90 度
Image::load('filename.gif')
	->rotate(90);

// 逆时针方向旋转 90 度
Image::load('filename.gif')
	->rotate(-90);

// 接受 (-359, 359) 範围之外的数字。
Image::load('filename')
	->rotate(450);

flip($direction)

垂直和／或水平翻转图像。

静态是

参数

参数	预设	描述
`$direction`	必要	翻转方向。接受 "horizontal"、"vertical" 或 "both"

回传 Image_Driver

範例

// 垂直翻转
Image::load('filename.gif')
	->flip('vertical');

// 水平翻转
Image::load('filename.gif')
	->flip('horizontal');

// 水平及垂直翻转。
Image::load('filename')
	->flip('both');

watermark($filename, $position, $padding = 5)

添加浮水印到图像。

静态是

参数

参数	预设	描述
`$filename`	必要	要使用做为浮水印的图像档案位置。
`$position`	必要	浮水印的位置，接受 "(top\|center\|middle\|bottom) (left\|center\|middle\|bottom)"。
`$padding`	`5`	从边缘的填充量（像素）。

回传 Image_Driver

範例

// 加入浮水印到图像的左上角随着 15 像素的填充
Image::load('filename.gif')
	->watermark('watermark.ext', "top left", 15);

// 加入浮水印到图像的右下角
Image::load('filename.gif')
	->watermark('watermark.ext', "bottom right");

// 加入浮水印到图像的中央
Image::load('filename.gif')
	->watermark('watermark.ext', "center middle");
// "center middle" 等同于 "center center"、"middle middle"、或 "middle center"

border($size, $color = null)

添加边线到图像。

静态是

参数

参数	预设	描述
`$size`	必要	边线尺寸（像素）。
`$color`	`null`	边线颜色，预设为背景颜色。

回传 Image_Driver

範例

// 製造一个 10px 黑色边线
Image::load('filename.gif')
	->border(10, '#000000');

// 製造一个 15px 红、绿、蓝的边线。
Image::load('filename.gif')
	->border(5, '#FF0000')
	->border(5, '#00FF00')
	->border(5, '#0000FF');

mask($maskimage)

透过混合遮罩的半透明度与载入的图像来应用遮罩到图像。

静态是

参数

参数	预设	描述
`$maskimage`	必要	要用来遮罩的的图像位置。

回传 Image_Driver

範例

// 用 mask.ext 遮罩图像
Image::load('filename.gif')
	->mask('mask.ext');

rounded($radius, $sides = null, $antialias = null)

应用圆角到图像。

静态是

参数

参数	预设	描述
`$radius`	必要	圆角半径（像素）。
`$sides`	`null`	接受以空白分隔的 "tl tr bl br" 任何组合，或 null 给所有边
`$antialias`	`1`	实际的圆到反锯齿的距离。0 停用反锯齿。

回传 Image_Driver

範例

// 加入所有边 10px 的圆角到图像
Image::load('filename.gif')
	->rounded(10);

// 加入顶部 10px 的圆角到图像
Image::load('filename.gif')
	->rounded(10, "tl tr");

// 加入所有边 10px 没有反锯齿的圆角到图像
Image::load('filename.gif')
	->rounded(10, null, 0);

sizes($filename = null)

回传目前载入图像的尺寸，或在 $filename 给的图像。

静态是

参数

参数	预设	描述
`$filename`	`null`	要取得尺寸的档案位置。

回传 stdClass

範例

// 取得呈现图像的尺寸
$sizes = Image::sizes('filename.gif');

// 回传
Object
(
    [width] => 500
    [height] => 400
)

extension()

回传档案的副档名，它代表在建构时被发现的类型。

静态	否
参数	没有
回传	字串
範例	`// 回传 'jpg' $ext = Image::load('uploaded_file.jpg') ->extension(); // 储存 PNG 为 JPG Image::load('placeholder.png') ->output($ext);`

grayscale()

将图像转成灰阶版本。

静态	是
参数	没有
回传	Image_Driver
範例	`// 灰阶图像 Image::load('filename.gif') ->grayscale();`

save($filename = null, $permissions = null)

储存图像，并选择性的试图设定权限。

静态是

参数

参数	预设	描述
`$filename`	`null`	要储存图像的位置。如果档案名称为 null，载入的图像档案名称会被使用。如果没添加副档名，将被附加基于载入档案的副档名。
`$permissions`	`null`	接受一个 unix 风格的权限（例如：755），或 null 不设定权限

回传空

範例

// 存为 filename2.ext
Image::load('filename.gif')
	->save('filename2');

// 存为 filename2.png
Image::load('filename.gif')
	->save('filename2.png');

// 存为 filename2.ext 当试图应用权限时
Image::load('filename.gif')
	->save('filename2', 755);

save_pa($prepend, $append = null, $extension = null, $permissions = null)

用一个附加在前和／或附加在后的档案名称储存图像到相同位置，并选择性的尝试设定权限。

静态是

参数

参数	预设	描述
`$append`	必要	要添加到档案名称开头的字串。
`$prepend`	`null`	要添加到档案名称结尾且在副档名之前的字串。
`$extension`	`null`	可以设定新的图像副档名，如果为 null，预设是载入的图像副档名。
`$permissions`	`null`	接受一个 unix 风格的权限（例如：755），或 null 不设定权限

回传空

範例

// 存为 prepend_filename_append.gif
Image::load('filename.gif')
	->save_pa('prepend_', '_append');

output($filetype)

直接输出图像，并设定表头。

静态是

参数

参数	预设	描述
`$filetype`	`null`	要输出图像的档案类型（如：png、gif、jpeg、等等）。预设是载入档案的副档名。

回传空

範例

// 输出为 gif
Image::load('filename.gif')
	->output();

// 输出为 jpeg
Image::load('filename.gif')
	->output('jpeg');