對於PHP中的Yii框架自帶前端資源包的使用分析

這篇文章主要介紹了PHP的Yii框架中對前端資源包的使用,列舉了Yii中一些JavaScript和CSS常用資源,需要的朋友可以參考下

Yii中的資源是和Web頁面相關的文件，可為CSS文件，JavaScript文件，圖片或影片等， 資源放在Web可存取的目錄下，直接被Web伺服器呼叫。

透過程式自動管理資源好一點，例如，當你在頁面中使用yii\jui\DatePicker 小工具時， 它會自動包含所需的CSS和JavaScript文件，而不是要求你手動找到這些文件並包含， 當你升級小工具時，它會自動使用新版本的資源文件，在本教學中，我們會詳述Yii提供的強大的資源管理功能。

資源包

Yii在資源包中管理資源，資源包簡單的說就是放在一個目錄下的資源集合， 當在視圖中註冊一個資源包，在渲染Web頁面時會包含包中的CSS和JavaScript檔案。

定義資源包

資源包指定為繼承yii\web\AssetBundle的PHP類，包名為可自動載入的PHP類名， 在資源包類中，要指定資源所在位置，包含哪些CSS和JavaScript檔案以及和其他套件的依賴關係。

如下程式碼定義基礎應用程式範本使用的主要資源包：

<?php

namespace app\assets;

use yii\web\AssetBundle;

class AppAsset extends AssetBundle
{
 public $basePath = &#39;@webroot&#39;;
 public $baseUrl = &#39;@web&#39;;
 public $css = [
  &#39;css/site.css&#39;,
 ];
 public $js = [
 ];
 public $depends = [
  &#39;yii\web\YiiAsset&#39;,
  &#39;yii\bootstrap\BootstrapAsset&#39;,
 ];
}

如上AppAsset 類別指定資源檔案放在@webroot 目錄下，對應的URL為@web，資源包包含一個CSS文件css/site.css，沒有JavaScript文件， 依賴其他兩個包yii\web\YiiAsset 和yii\bootstrap\BootstrapAsset， 關於yii\web\AssetBundle 的屬性的更多詳細如下所述：

• yii\web\AssetBundle::sourcePath: 指定套件包含資源檔案的根目錄， 當根目錄無法被Web存取時該屬性應設置，否則，應設定yii\web\AssetBundle::basePath 屬性和yii\web\AssetBundle::baseUrl。路徑別名可在此處使用;

• yii\web\AssetBundle::basePath: 指定包含資源包中資源檔案並可Web存取的目錄，當指定yii\web\AssetBundle ::sourcePath 屬性， 資源管理器會發佈包的資源到一個可Web存取並覆寫該屬性， 如果你的資源檔案在一個Web可存取目錄下，應設定該屬性，這樣就不用再發佈了。路徑別名 可在此使用。

yii\web\AssetBundle::baseUrl: 指定對應到yii\web\AssetBundle::basePath目錄的URL， 和yii\web\AssetBundle::basePath 類似，如果你指定yii\web\AssetBundle::sourcePath 屬性， 資源管理器會發佈這些資源並覆寫該屬性，路徑別名可在此處使用。
yii\web\AssetBundle::js: 一個包含該資源包JavaScript檔案的數組，注意正斜線"/"應作為目錄分隔符， 每個JavaScript檔案可指定為以下兩種格式之一：

• 相對路徑表示為本機JavaScript檔案(如js/main.js)，檔案實際的路徑在該相對路徑前加上yii\web\AssetManager::basePath，檔案實際的URL在該路徑前加上yii\web\AssetManager::baseUrl。

• 絕對URL位址表示為外部JavaScript文件，如http://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js 或// ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js.

• yii\web\AssetBundle::css: 一個包含該資源包JavaScript檔案的數組，該數組格式和yii\web\AssetBundle::js 相同。

• yii\web\AssetBundle::depends: 一個列出該資源包依賴的其他資源包（後兩節有詳細介紹）。

• yii\web\AssetBundle::jsOptions: 當呼叫yii\web\View::registerJsFile()註冊該套件 每個 JavaScript檔案時， 指定傳遞到該方法的選項。

• yii\web\AssetBundle::cssOptions: 當呼叫yii\web\View::registerCssFile()註冊該套件 每個 css檔案時， 指定傳遞到該方法的選項。

• yii\web\AssetBundle::publishOptions: 當呼叫yii\web\AssetManager::publish()發布該套件資源檔案到Web目錄時指定傳遞到該方法的選項，僅在指定了yii\web\AssetBundle::sourcePath屬性時使用。

資源位置

資源根據它們的位置可以分為：

來源資源: 資源檔案與PHP原始碼放在一起，不能被Web直接訪問，為了使用這些來源資源，它們要拷貝到一個可Web訪問的Web目錄中成為發布的資源，這個過程稱為發布資源，隨後會詳細介紹。
發佈資源: 資源檔案放在可透過Web直接存取的Web目錄中；
外部資源: 資源檔案放在你的Web應用不同的Web伺服器上；
當定義資源包類別時候，如果你指定了yii\web\AssetBundle::sourcePath 屬性，就表示任何使用相對路徑的資源會被當作來源資源；如果沒有指定該屬性，就表示這些資源為發佈資源（因此應指定yii\web\ AssetBundle::basePath 和yii\web\AssetBundle::baseUrl 讓Yii知道它們的位置）。

推荐将资源文件放到Web目录以避免不必要的发布资源过程，这就是之前的例子指定 yii\web\AssetBundle::basePath 而不是 yii\web\AssetBundle::sourcePath.

对于 扩展来说，由于它们的资源和源代码都在不能Web访问的目录下， 在定义资源包类时必须指定yii\web\AssetBundle::sourcePath属性。

注意: yii\web\AssetBundle::sourcePath 属性不要用@webroot/assets，该路径默认为 yii\web\AssetManager资源管理器将源资源发布后存储资源的路径，该路径的所有内容会认为是临时文件， 可能会被删除。
资源依赖

当Web页面包含多个CSS或JavaScript文件时，它们有一定的先后顺序以避免属性覆盖， 例如，Web页面在使用jQuery UI小部件前必须确保jQuery JavaScript文件已经被包含了， 我们称这种资源先后次序称为资源依赖。

资源依赖主要通过yii\web\AssetBundle::depends 属性来指定， 在AppAsset 示例中，资源包依赖其他两个资源包： yii\web\YiiAsset 和 yii\bootstrap\BootstrapAsset 也就是该资源包的CSS和JavaScript文件要在这两个依赖包的文件包含 之后 才包含。

资源依赖关系是可传递，也就是人说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',
     ]
    ],
   ],
  ],
 ],
];

可通过类似yii\web\AssetManager::bundles配置多个资源包，数组的键应为资源包的类名（最开头不要反斜杠）， 数组的值为对应的配置数组.

提示: 可以根据条件判断使用哪个资源，如下示例为如何在开发环境用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框架定义许多资源包，如下资源包是最常用，可在你的应用或扩展代码中引用它们。

• yii\web\YiiAsset: 主要包含yii.js 文件，该文件完成模块JavaScript代码组织功能， 也为 data-method 和 data-confirm属性提供特别支持和其他有用的功能。

• yii\web\JqueryAsset: 包含从jQuery bower 包的jquery.js文件。

• yii\bootstrap\BootstrapAsset: 包含从Twitter Bootstrap 框架的CSS文件。

• yii\bootstrap\BootstrapPluginAsset: 包含从Twitter Bootstrap 框架的JavaScript 文件来支持Bootstrap JavaScript插件。

• yii\jui\JuiAsset: 包含从jQuery UI库的CSS 和 JavaScript 文件。

如果你的代码需要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使用文件扩展名来表示资源使用哪种扩展语法，默认可以识别如下语法和文件扩展名：

• LESS: .less

• SCSS: .scss

• Stylus: .styl

• CoffeeScript: .coffee

• TypeScript: .ts

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"使用的配置文件
 * 注意在控制台环境下，一些路径别名如 &#39;@webroot&#39; 和 &#39;@web&#39; 不会存在
 * 请定义不存在的路径别名
 */
return [
 // 为JavaScript文件压缩修改 command/callback 
 &#39;jsCompressor&#39; => &#39;java -jar compiler.jar --js {from} --js_output_file {to}&#39;,
 // 为CSS文件压缩修改command/callback 
 &#39;cssCompressor&#39; => &#39;java -jar yuicompressor.jar --type css {from} -o {to}&#39;,
 // 要压缩的资源包列表
 &#39;bundles&#39; => [
  // &#39;yii\web\YiiAsset&#39;,
  // &#39;yii\web\JqueryAsset&#39;,
 ],
 // 资源包压缩后的输出
 &#39;targets&#39; => [
  &#39;all&#39; => [
   &#39;class&#39; => &#39;yii\web\AssetBundle&#39;,
   &#39;basePath&#39; => &#39;@webroot/assets&#39;,
   &#39;baseUrl&#39; => &#39;@web/assets&#39;,
   &#39;js&#39; => &#39;js/all-{hash}.js&#39;,
   &#39;css&#39; => &#39;css/all-{hash}.css&#39;,
  ],
 ],
 // 资源管理器配置:
 &#39;assetManager&#39; => [
 ],
];

应修改该文件的bundles的选项指定哪些包你想要合并，在targets选项中应指定这些包如何分组，如前述的可以指定一个或多个组。

注意: 由于在控制台应用别名 @webroot and @web 不可用，应在配置中明确指定它们。
JavaScript文件会被合并压缩后写入到js/all-{hash}.js文件，其中 {hash} 会被结果文件的哈希值替换。

jsCompressor 和 cssCompressor 选项指定控制台命令或PHP回调函数来执行JavaScript和CSS合并和压缩， Yii默认使用Closure Compiler来合并JavaScript文件， 使用YUI Compressor来合并CSS文件， 你应手工安装这些工具或修改选项使用你喜欢的工具。

根据配置文件，可执行asset 命令来合并和压缩资源文件并生成一个新的资源包配置文件assets-prod.php:

yii asset assets.php config/assets-prod.php

以上就是本文的全部内容，希望对大家的学习有所帮助，更多相关内容请关注PHP中文网！

相关推荐：

对于yii框架中Url的生产问题的解决

对于Yii2的XSS攻击防范策略的方法解析

以上是對於PHP中的Yii框架自帶前端資源包的使用分析的詳細內容。更多資訊請關注PHP中文網其他相關文章！