README

Yii2 ActiveRecord 行为

附带 Cropper 小部件

Illustrated 2.0 是一个针对 Yii2 框架的行为，可以使任何 ActiveRecord 变得“形象化”。它将 ActiveRecord 与一个或多个图像文件链接起来。这些图像具有严格的宽高比，允许视图和其他页面具有整洁的布局。图像可以保存为多个分辨率。

Illustrated 2.0 行为与封装的 CropperWidget 小部件协作。这使得用户在将其上传到服务器之前可以裁剪图像。

这里是 Illustrated 2.0 行为及其相关 CropperWidget 的演示。

注意，当前版本（2.0.0）与之前版本相比有重大变化。它应该更容易使用。请仔细阅读此文档。

安装

使用 Composer 安装 Illustrated 2.0。将以下内容添加到您的 composer.json 文件的 require 部分中

"sjaakp/yii2-illustrated-behavior": "*"

或者运行

composer require sjaakp/yii2-illustrated-behavior "*"

您可以通过下载 ZIP 格式的源代码来手动安装 Illustrated 2.0。

注意，Illustrated 2.0 需要 PHP 版本 8.1 或更高。

Illustrated 的使用

Illustrated 2.0 的使用方式与任何 Behavior 的 ActiveRecord 相似。代码应类似于以下内容

<?php

use sjaakp\illustrated\Illustrated;

class <model> extends \yii\db\ActiveRecord { 
	... 
	public function behaviors(){
		return [
			[
				"class" => Illustrated::class,
				"attributes" => [
					"picture" => [	// attribute name of the illustration
						...		// options for 'picture'
					],
					...		// other illustrations
				],
				... 	// other Illustrated options
			],
 			...		// other behaviors
		];
	}
	...
}

具有 Illustrated 2.0 行为的 ActiveRecord 可以有一个或多个插图。

每个插图都有其固定的宽高比，因此 ActiveRecord 的视图将具有一致的布局。

每个插图都与 ActiveRecord 中的一个属性和数据库表中的一个相应字段相关联。此属性存储上传的图像的文件名。Illustrated 2.0 使用其自己的命名方案。上传的图像文件名永远不会超过 11 个字符。

在其基本操作中，Illustrated 2.0 为每个插图存储一个上传文件的版本。但是，可以使其存储多个具有不同分辨率的版本。这对于响应式图像非常完美。更多信息在这里。

CropperWidget 的使用

CropperWidget 是一个输入小部件。它旨在上传插图。它可以像这样用于 ActiveForm

use sjaakp\illustrated\CropperWidget;
 
<?php $form = ActiveForm::begin([
		'options' => ['enctype' => 'multipart/form-data']	// important, needed for file upload
	]); ?>

	...		// other form fields

	<?= $form->field($model, 'picture')->widget(CropperWidget::class, [
		   ...		// CropperWidget options
    	]) ?>
	...
	<?= Html::submitButton('Submit') ?>

<?php ActiveForm::end(); ?>

CropperWidget 显示了文件上传的控件以及裁剪和旋转图像的控件。它基于我的 Cropper 2.0 JavaScript 小部件。

注意，ActiveForm 必须将选项 'enctype' 设置为 'multipart/form-data'。

CropperWidget 最重要的选项是 aspect。它设置裁剪图像的宽高比。

可以设置为以下字符串之一

'tower' 等同于 0.429，9:21
'high' 等同于 0.563，9:16
'phi_portrait' 等同于 0.618，1:φ，黄金比例
'din_portrait' 等同于 0.707，1:√2，DIN/ISO 216 纸张尺寸
'portrait' 等同于 0.75，3:4
'square' 等同于 1.0，1:1
'landscape' 等同于 1.333，4:3
'din_landscape' 等同于 1.414，√2:1
'phi_landscape' 等同于 1.618，φ:1
'wide' 等同于 1.718，16:9
'cinema' 等同于 2.333，21:9

或者，您可以将 aspect 设置为介于 0.2 和 5.0 之间的浮点数。

CropperWidget 还有其他一些选项。请参阅 Cropper 2.0 的文档。

示例

要将宽高比设置为 'portrait'（0.75），可以使用以下方法

use sjaakp\illustrated\CropperWidget;
 
<?php $form = ActiveForm::begin([
		'options' => ['enctype' => 'multipart/form-data']
	]); ?>

	...   
	<?= $form->field($model, 'picture')->widget(CropperWidget::class, [
		'aspect' => 'portrait'
    	]) ?>

	...

<?php ActiveForm::end(); ?>

Illustrated 2.0 函数

这些函数成为拥有 Illustrated 2.0 行为的 ActiveRecord 的方法。

getImgHtml()

function getImgHtml( $attribute, $options = [] )

获取上传和裁剪后的插图的完整 HTML <img> 元素。如果设置了 cropWidth 且 cropSteps 大于零，则包含 srcset。

注意，要使 srcset 生效，您必须在 $options 中设置 sizes 值。有关详细信息，请参阅此处。

attribute：插图的属性名。
options：HTML 选项 img 标签。参阅 yii\helpers\Html::img。默认：[]（空数组）。

在视图中显示存储在属性 'picture' 中的插图的简单方法是

...	
<?= $model->getImgHtml('picture') ?>
...

getSrc()

function getSrc( $attribute, $step = 0 )

获取上传和裁剪后的插图（其中一个变体）的源 URL。如果不可用则返回 null。

attribute：插图的属性名。
step：插图的 'step' 或变体，0 是最大的。要获取最小的变体（对缩略图很有用），将 step 设置为 -1。

getSrcSet()

function getSrcSet( $attribute )

获取上传和裁剪后的插图的 srcset。如果未设置 cropWidth，则返回 ""。

attribute：插图的属性名。

deleteFiles()

function deleteFiles( $attribute )

删除图像文件并清除 attribute。

attribute：插图的属性名。

Illustrated 2.0 选项

attributes

array 插图属性列表 key => value。

数组成员 key 是存储裁剪后图像文件名的属性的名称。

value 是一个包含以下属性（所有都是可选的）的数组

cropWidth：int - 裁剪图像的宽度，以像素为单位。
- 如果未设置，则裁剪后的图像以最大可能的分辨率和文件大小保存。
cropSteps：int - 裁剪图像的大小变体的数量。每个变体的宽度是前一个变体的一半。
- 示例：如果 cropWidth = 1280，且 cropSteps = 5，则将保存宽度为 1280、640、320、160 和 80 像素的变体，每个变体保存在其自己的子目录中。
- 如果 cropSteps = 0 或未设置，则只保存一个裁剪后的图像，宽度为 cropWidth。
- 如果未设置 cropWidth，则忽略 cropSteps。
rejectTooSmall: bool - 如果为 true，则拒绝裁剪过小的图片。如果没有设置，则默认为 true，即拒绝小图片。

mime

保存的裁剪图片的 MIME 类型。如果为 null，则裁剪图片将与原始图片使用相同的 MIME 类型。默认：'image/avif'。 AVIF 是一种较新的（2019年）图像文件格式，在很多方面优于 JPEG。它被所有现代浏览器支持。

baseUrl

存放裁剪图片的 URL（或别名）。

如果为 null（默认值），则 URL 为 '@web/<$illustrationDirectory>/<table name>'，其中 <table name> 是 ActiveRecord 的表名。

illustrationDirectory

存放裁剪图片的 '@webroot' 下的子目录名称。默认：'illustrations'。如果 directory 不是 null，则 illustrationDirectory 会被忽略。

noImage

如果没有图片可用时返回的 HTML，即 $imgAttribute 为空。默认：''（空文本）。

fileValidation

包含文件属性验证额外参数的数组。默认情况下，仅测试文件类型和文件数量。

您可以在此处添加最大文件大小等信息。请参阅 FileValidator。默认：[]（空数组）。

tooSmallError

对于裁剪过小的图片的错误信息模板。参数：原始文件名、宽度和高度。默认：'图片 "%s" 过小 (%d×%d)'。

uploadError

上传错误的信息模板。参数：错误号。请参阅此处。默认：'上传错误 %d.'。

CropperWidget 选项

options

Cropper 2.0 控件的客户端选项，例如 aspect。请参阅 Cropper 文档。

translations

Cropper 2.0 控件的可选翻译。请参阅 Cropper 文档。

常见问题解答

为什么我会收到像 'Trying to get property of non-object' 这样的错误？

你可能没有给表单提供 'enctype' => 'multipart/form-data' 选项。

为什么我尝试更新插图文档时无法更改插图裁剪？

这是设计上的原因。不建议重新裁剪已经裁剪过的图片。你可能需要重新加载原始图片。

sjaakp / yii2-illustrated-behavior

维护者

详细信息