Yii의 리소스는 웹 페이지와 관련된 파일로 CSS 파일, JavaScript 파일, 이미지 또는 비디오 등이 될 수 있습니다. 리소스는 웹에 액세스할 수 있는 디렉터리에 배치되며 웹 서버에서 직접 호출됩니다.
예를 들어, 페이지에서 yiijuiDatePicker 위젯을 사용하면 필요한 CSS 및 JavaScript 파일을 수동으로 찾아서 포함시키는 대신 자동으로 리소스를 관리하는 것이 좋습니다. 위젯을 업그레이드하면 자동으로 새 버전의 리소스 파일이 사용됩니다. 이 튜토리얼에서는 Yii가 제공하는 강력한 리소스 관리 기능을 자세히 설명합니다.
리소스팩
Yii는 리소스 패키지에서 리소스를 관리합니다. 리소스 패키지는 단순히 디렉터리에 있는 리소스 모음입니다. 리소스 패키지가 뷰에 등록되면 웹 페이지를 렌더링할 때 패키지의 CSS 및 JavaScript 파일이 포함됩니다.
리소스 패키지 정의
리소스 패키지는 yiiwebAssetBundle을 상속하는 PHP 클래스로 지정됩니다. 패키지 이름은 자동으로 로드할 수 있는 PHP 클래스 이름이며, 리소스 패키지 클래스에는 CSS 및 JavaScript가 포함된 리소스의 위치를 지정해야 합니다. 포함된 파일 및 다른 패키지와의 종속성.
다음 코드는 기본 애플리케이션 템플릿에서 사용되는 기본 리소스 패키지를 정의합니다.
<?php namespace app\assets; use yii\web\AssetBundle; class AppAsset extends AssetBundle { public $basePath = '@webroot'; public $baseUrl = '@web'; public $css = [ 'css/site.css', ]; public $js = [ ]; public $depends = [ 'yii\web\YiiAsset', 'yii\bootstrap\BootstrapAsset', ]; }
위와 같이 AppAsset 클래스에서 지정한 리소스 파일은 @webroot 디렉터리에 위치하며 해당 URL은 @web입니다. 리소스 패키지에는 JavaScript 파일이 아닌 CSS 파일인 css/site.css가 포함되어 있습니다. 다른 두 패키지 yiiwebYiiAsset 및 yiibootstrapBootstrapAsset 정보 yiiwebAssetBundle의 속성에 대한 자세한 내용은 아래에 설명되어 있습니다.
yiiwebAssetBundle::baseUrl: yiiwebAssetBundle::basePath 디렉터리에 해당하는 URL을 지정합니다. yiiwebAssetBundle::basePath 속성을 지정하면 리소스 관리자가 이러한 리소스를 게시하고 이 속성을 재정의합니다. 여기서 경로 별칭을 사용할 수 있습니다.
yiiwebAssetBundle::js: 리소스 번들의 JavaScript 파일을 포함하는 배열입니다. 슬래시 "/"를 디렉터리 구분 기호로 사용해야 합니다. 각 JavaScript 파일은 다음 두 가지 형식 중 하나로 지정할 수 있습니다.
리소스 위치
리소스는 위치에 따라 분류될 수 있습니다.소스 리소스: 리소스 파일과 PHP 소스 코드는 함께 배치되며 웹에서 직접 액세스할 수 없습니다. 이러한 소스 리소스를 사용하려면 웹에서 액세스할 수 있는 웹 디렉터리에 복사하여 게시된 리소스로 만들어야 합니다. 퍼블리싱이라고 합니다. 리소스에 대해서는 나중에 자세히 소개하겠습니다.
리소스 게시: 리소스 파일은 웹을 통해 직접 액세스할 수 있는 웹 디렉터리에 배치됩니다.
외부 리소스: 리소스 파일은 웹 애플리케이션과 다른 웹 서버에 배치됩니다.
리소스 번들 클래스를 정의할 때 yiiwebAssetBundle::sourcePath 속성을 지정하면 상대 경로를 사용하는 모든 리소스가 소스 리소스로 사용된다는 의미입니다. 이 속성을 지정하지 않으면 해당 리소스가 게시된 리소스라는 의미입니다. yiiwebAssetBundle::basePath를 지정하고 yiiwebAssetBundle::baseUrl을 Yii에게 알려야 합니다.
확장 기능의 경우 해당 리소스와 소스 코드가 웹에서 접근할 수 없는 디렉터리에 있으므로 리소스 번들 클래스를 정의할 때 yiiwebAssetBundle::sourcePath 속성을 지정해야 합니다.
참고: yiiwebAssetBundle::sourcePath 속성에 @webroot/assets를 사용하지 마십시오. 이 경로는 yiiwebAssetManager 리소스 관리자가 소스 리소스를 게시한 후 저장하는 경로로 기본 설정됩니다. 삭제될 수 있습니다.
리소스 종속성
리소스 종속성은 주로 yiiwebAssetBundle::dependent 속성을 통해 지정됩니다. AppAsset 예에서 리소스 번들은 두 개의 다른 리소스 번들인 yiiwebYiiAsset 및 yiibootstrapBootstrapAsset에 종속됩니다. 파일이 포함된 후에 두 개의 종속성 번들이 포함됩니다.
리소스 종속성은 전이적입니다. 즉, 사람들이 A가 B에 의존하고 B가 C에 의존한다고 말하면 A도 C에 의존합니다.
리소스 옵션
可指定yii\web\AssetBundle::cssOptions 和 yii\web\AssetBundle::jsOptions 属性来自定义页面包含CSS和JavaScript文件的方式, 这些属性值会分别传递给 yii\web\View::registerCssFile() 和 yii\web\View::registerJsFile() 方法, 在视图 调用这些方法包含CSS和JavaScript文件时。
注意: 在资源包类中设置的选项会应用到该包中 每个 CSS/JavaScript 文件,如果想对每个文件使用不同的选项, 应创建不同的资源包并在每个包中使用一个选项集。
例如,只想IE9或更高的浏览器包含一个CSS文件,可以使用如下选项:
public $cssOptions = ['condition' => 'lte IE9'];
这会是包中的CSS文件使用以下HTML标签包含进来:
<!--[if lte IE9]> <link rel="stylesheet" href="path/to/foo.css"> <![endif]-->
为链接标签包含2b0b25ff593c5b6c03403dd6234ffb2c可使用如下代码:
public $cssOptions = ['noscript' => true];
为使JavaScript文件包含在页面head区域(JavaScript文件默认包含在body的结束处)使用以下选项:
public $jsOptions = ['position' => \yii\web\View::POS_HEAD];
Bower 和 NPM 资源
大多数 JavaScript/CSS 包通过Bower 和/或 NPM管理, 如果你的应用或扩展使用这些包,推荐你遵循以下步骤来管理库中的资源:
修改应用或扩展的 composer.json 文件将包列入require 中, 应使用bower-asset/PackageName (Bower包) 或 npm-asset/PackageName (NPM包)来对应库。
创建一个资源包类并将你的应用或扩展要使用的JavaScript/CSS 文件列入到类中, 应设置 yii\web\AssetBundle::sourcePath 属性为@bower/PackageName 或 @npm/PackageName, 因为根据别名Composer会安装Bower或NPM包到对应的目录下。
注意: 一些包会将它们分布式文件放到一个子目录中,对于这种情况,应指定子目录作为 yii\web\AssetBundle::sourcePath属性值,例如,yii\web\JqueryAsset使用 @bower/jquery/dist 而不是 @bower/jquery。
使用资源包
为使用资源包,在视图中调用yii\web\AssetBundle::register()方法先注册资源, 例如,在视图模板可使用如下代码注册资源包:
use app\assets\AppAsset; AppAsset::register($this); // $this 代表视图对象
如果在其他地方注册资源包,应提供视图对象,如在 小部件 类中注册资源包, 可以通过 $this->view 获取视图对象。
当在视图中注册一个资源包时,在背后Yii会注册它所依赖的资源包,如果资源包是放在Web不可访问的目录下,会被发布到可访问的目录, 后续当视图渲染页面时,会生成这些注册包包含的CSS和JavaScript文件对应的2cdf5bf648cf2f33323966d7f58a7f3f 和 3f1c4e4b6b16bbbd69b2ee476dc4f83a 标签, 这些标签的先后顺序取决于资源包的依赖关系以及在 yii\web\AssetBundle::css和yii\web\AssetBundle::js 的列出来的前后顺序。
自定义资源包
Yii通过名为 assetManager的应用组件实现[[yii\web\AssetManager] 来管理应用组件, 通过配置yii\web\AssetManager::bundles 属性,可以自定义资源包的行为, 例如,yii\web\JqueryAsset 资源包默认从jquery Bower包中使用jquery.js 文件, 为了提高可用性和性能,你可能需要从Google服务器上获取jquery文件,可以在应用配置中配置assetManager,如下所示:
return [ // ... 'components' => [ 'assetManager' => [ 'bundles' => [ 'yii\web\JqueryAsset' => [ 'sourcePath' => null, // 一定不要发布该资源 'js' => [ '//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js', ] ], ], ], ], ];
提示: 可以根据条件判断使用哪个资源,如下示例为如何在开发环境用jquery.js,否则用jquery.min.js:
'yii\web\JqueryAsset' => [ 'js' => [ YII_ENV_DEV ? 'jquery.js' : 'jquery.min.js' ] ],
可以设置资源包的名称对应false来禁用想禁用的一个或多个资源包,当视图中注册一个禁用资源包, 视图不会包含任何该包的资源以及不会注册它所依赖的包,例如,为禁用yii\web\JqueryAsset,可以使用如下配置:
return [ // ... 'components' => [ 'assetManager' => [ 'bundles' => [ 'yii\web\JqueryAsset' => false, ], ], ], ];
可设置yii\web\AssetManager::bundles为false禁用 所有 的资源包。
资源部署
有时你想"修复" 多个资源包中资源文件的错误/不兼容,例如包A使用1.11.1版本的jquery.min.js, 包B使用2.1.1版本的jquery.js,可自定义每个包来解决这个问题,更好的方式是使用资源部署特性来部署不正确的资源为想要的, 为此,配置yii\web\AssetManager::assetMap属性,如下所示:
return [ // ... 'components' => [ 'assetManager' => [ 'assetMap' => [ 'jquery.js' => '//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js', ], ], ], ];
yii\web\AssetManager::assetMap的键为你想要修复的资源名,值为你想要使用的资源路径, 当视图注册资源包,在yii\web\AssetBundle::css 和 yii\web\AssetBundle::js 数组中每个相关资源文件会和该部署进行对比, 如果数组任何键对比为资源文件的最后文件名(如果有的话前缀为 yii\web\AssetBundle::sourcePath),对应的值为替换原来的资源。 例如,资源文件my/path/to/jquery.js 匹配键 jquery.js.
注意: 只有相对相对路径指定的资源对应到资源部署,替换的资源路径可以为绝对路径,也可为和yii\web\AssetManager::basePath相关的路径。
资源发布
如前所述,如果资源包放在Web不能访问的目录,当视图注册资源时资源会被拷贝到一个Web可访问的目录中, 这个过程称为资源发布,yii\web\AssetManager会自动处理该过程。
资源默认会发布到@webroot/assets目录,对应的URL为@web/assets, 可配置yii\web\AssetManager::basePath 和 yii\web\AssetManager::baseUrl 属性自定义发布位置。
除了拷贝文件方式发布资源,如果操作系统和Web服务器允许可以使用符号链接,该功能可以通过设置 yii\web\AssetManager::linkAssets 为 true 来启用。
return [ // ... 'components' => [ 'assetManager' => [ 'linkAssets' => true, ], ], ];
使用以上配置,资源管理器会创建一个符号链接到要发布的资源包源路径,这比拷贝文件方式快并能确保发布的资源一直为最新的。
常用资源包
Yii框架定义许多资源包,如下资源包是最常用,可在你的应用或扩展代码中引用它们。
如果你的代码需要jQuery, jQuery UI 或 Bootstrap,应尽量使用这些预定义资源包而非自己创建, 如果这些包的默认配置不能满足你的需求,可以自定义配置,详情参考自定义资源包。
资源转换
除了直接编写CSS 和/或 JavaScript代码,开发人员经常使用扩展语法来编写,再使用特殊的工具将它们转换成CSS/Javascript。 例如,对于CSS代码可使用LESS 或 SCSS, 对于JavaScript 可使用 TypeScript。
可将使用扩展语法的资源文件列到资源包的yii\web\AssetBundle::css 和 yii\web\AssetBundle::js中,如下所示:
class AppAsset extends AssetBundle { public $basePath = '@webroot'; public $baseUrl = '@web'; public $css = [ 'css/site.less', ]; public $js = [ 'js/site.ts', ]; public $depends = [ 'yii\web\YiiAsset', 'yii\bootstrap\BootstrapAsset', ]; }
当在视图中注册一个这样的资源包,yii\web\AssetManager资源管理器会自动运行预处理工具将使用扩展语法 的资源转换成CSS/JavaScript,当视图最终渲染页面时,在页面中包含的是CSS/Javascipt文件,而不是原始的扩展语法代码文件。
Yii使用文件扩展名来表示资源使用哪种扩展语法,默认可以识别如下语法和文件扩展名:
Yii依靠安装的预处理工具来转换资源,例如,为使用LESS,应安装lessc 预处理命令。
可配置yii\web\AssetManager::converter自定义预处理命令和支持的扩展语法,如下所示:
return [ 'components' => [ 'assetManager' => [ 'converter' => [ 'class' => 'yii\web\AssetConverter', 'commands' => [ 'less' => ['css', 'lessc {from} {to} --no-color'], 'ts' => ['js', 'tsc --out {to} {from}'], ], ], ], ], ];
如上所示,通过yii\web\AssetConverter::commands 属性指定支持的扩展语法, 数组的键为文件扩展名(前面不要.),数组的值为目标资源文件扩展名和执行资源转换的命令, 命令中的标记 {from} 和{to}会分别被源资源文件路径和目标资源文件路径替代。
补充: 除了以上方式,也有其他的方式来处理扩展语法资源,例如,可使用编译工具如grunt 来监控并自动转换扩展语法资源,此时,应使用资源包中编译后的CSS/Javascript文件而不是原始文件。
合并和压缩资源
一个Web页面可以包含很多CSS 和/或 JavaScript 文件,为减少HTTP 请求和这些下载文件的大小, 通常的方式是在页面中合并并压缩多个CSS/JavaScript 文件为一个或很少的几个文件,并使用压缩后的文件而不是原始文件。
补充: 合并和压缩资源通常在应用在产品上线模式,在开发模式下使用原始的CSS/JavaScript更方便调试。
接下来介绍一种合并和压缩资源文件而不需要修改已有代码的方式:
找出应用中所有你想要合并和压缩的资源包,
将这些包分成一个或几个组,注意每个包只能属于其中一个组,
合并/压缩每个组里CSS文件到一个文件,同样方式处理JavaScript文件,
为每个组定义新的资源包:
设置yii\web\AssetBundle::css 和 yii\web\AssetBundle::js 属性分别为压缩后的CSS和JavaScript文件;
自定义设置每个组内的资源包,设置资源包的yii\web\AssetBundle::css 和 yii\web\AssetBundle::js 属性为空, 并设置它们的 yii\web\AssetBundle::depends 属性为每个组新创建的资源包。
使用这种方式,当在视图中注册资源包时,会自动触发原始包所属的组资源包的注册,然后,页面就会包含以合并/压缩的资源文件, 而不是原始文件。
示例
使用一个示例来解释以上这种方式:
鉴定你的应用有两个页面X 和 Y,页面X使用资源包A,B和C,页面Y使用资源包B,C和D。
有两种方式划分这些资源包,一种使用一个组包含所有资源包,另一种是将(A,B,C)放在组X,(B,C,C)放在组Y, 哪种方式更好?第一种方式优点是两个页面使用相同的已合并CSS和JavaScript文件使HTTP缓存更高效,另一方面,由于单个组包含所有文件, 已合并的CSS和Javascipt文件会更大,因此会增加文件传输时间,在这个示例中,我们使用第一种方式,也就是用一个组包含所有包。
补充: 将资源包分组并不是无价值的,通常要求分析现实中不同页面各种资源的数据量,开始时为简便使用一个组。
在所有包中使用工具(例如 Closure Compiler, YUI Compressor) 来合并和压缩CSS和JavaScript文件, 注意合并后的文件满足包间的先后依赖关系,例如,如果包A依赖B,B依赖C和D,那么资源文件列表以C和D开始,然后为B最后为A。
合并和压缩之后,会得到一个CSS文件和一个JavaScript文件,假定它们的名称为all-xyz.css 和 all-xyz.js, xyz 为使文件名唯一以避免HTTP缓存问题的时间戳或哈希值。
现在到最后一步了,在应用配置中配置yii\web\AssetManager 资源管理器如下所示:
return [ 'components' => [ 'assetManager' => [ 'bundles' => [ 'all' => [ 'class' => 'yii\web\AssetBundle', 'basePath' => '@webroot/assets', 'baseUrl' => '@web/assets', 'css' => ['all-xyz.css'], 'js' => ['all-xyz.js'], ], 'A' => ['css' => [], 'js' => [], 'depends' => ['all']], 'B' => ['css' => [], 'js' => [], 'depends' => ['all']], 'C' => ['css' => [], 'js' => [], 'depends' => ['all']], 'D' => ['css' => [], 'js' => [], 'depends' => ['all']], ], ], ], ];
如自定义资源包 小节中所述,如上配置改变每个包的默认行为, 特别是包A、B、C和D不再包含任何资源文件,都依赖包含合并后的all-xyz.css 和 all-xyz.js文件的包all, 因此,对于页面X会包含这两个合并后的文件而不是包A、B、C的原始文件,对于页面Y也是如此。
最后有个方法更好地处理上述方式,除了直接修改应用配置文件,可将自定义包数组放到一个文件,在应用配置中根据条件包含该文件,例如:
return [ 'components' => [ 'assetManager' => [ 'bundles' => require(__DIR__ . '/' . (YII_ENV_PROD ? 'assets-prod.php' : 'assets-dev.php')), ], ], ];
如上所示,在产品上线模式下资源包数组存储在assets-prod.php文件中,不是产品上线模式存储在assets-dev.php文件中。
使用 asset 命令
Yii提供一个名为asset控制台命令来使上述操作自动处理。
为使用该命令,应先创建一个配置文件设置哪些资源包要合并以及分组方式,可使用asset/template 子命令来生成一个模板, 然后修改模板成你想要的。
yii asset/template assets.php
该命令在当前目录下生成一个名为assets.php的文件,文件的内容类似如下:
<?php /** * 为控制台命令"yii asset"使用的配置文件 * 注意在控制台环境下,一些路径别名如 '@webroot' 和 '@web' 不会存在 * 请定义不存在的路径别名 */ return [ // 为JavaScript文件压缩修改 command/callback 'jsCompressor' => 'java -jar compiler.jar --js {from} --js_output_file {to}', // 为CSS文件压缩修改command/callback 'cssCompressor' => 'java -jar yuicompressor.jar --type css {from} -o {to}', // 要压缩的资源包列表 'bundles' => [ // 'yii\web\YiiAsset', // 'yii\web\JqueryAsset', ], // 资源包压缩后的输出 'targets' => [ 'all' => [ 'class' => 'yii\web\AssetBundle', 'basePath' => '@webroot/assets', 'baseUrl' => '@web/assets', 'js' => 'js/all-{hash}.js', 'css' => 'css/all-{hash}.css', ], ], // 资源管理器配置: 'assetManager' => [ ], ];
병합하려는 패키지를 지정하려면 파일의 번들 옵션을 수정해야 합니다. 대상 옵션에서 이러한 패키지를 그룹화하는 방법을 지정해야 합니다. 위에서 언급한 것처럼 하나 이상의 그룹을 지정할 수 있습니다.
참고: @webroot 및 @web 별칭은 콘솔 애플리케이션에서 사용할 수 없으므로 구성에서 명시적으로 지정해야 합니다.
JavaScript 파일은 병합 및 압축되어 js/all-{hash}.js 파일에 기록됩니다. 여기서 {hash}는 결과 파일의 해시 값으로 대체됩니다.
jsCompressor 및 cssCompressor 옵션은 JavaScript 및 CSS 병합 및 압축을 수행하는 콘솔 명령 또는 PHP 콜백 함수를 지정합니다. Yii는 기본적으로 Closure Compiler를 사용하여 JavaScript 파일을 병합하고 YUI Compressor를 사용하여 CSS 파일을 병합해야 합니다. 즐겨 사용하는 도구를 사용하는 옵션.
구성 파일에 따라 자산 명령을 실행하여 리소스 파일을 병합 및 압축하고 새 리소스 패키지 구성 파일 자산-prod.php를 생성할 수 있습니다.
yii 자산 자산.php config/assets-prod.php