Image - 类別 - FuelPHP 简体中文手册

Image 类別

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