資源

Yii中的資源是和Web頁面相關(guān)的文件，可為CSS文件，JavaScript文件，圖片或視頻等， 資源放在Web可訪問的目錄下，直接被Web服務器調(diào)用。

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

資源包

Yii在資源包中管理資源，資源包簡單的說就是放在一個目錄下的資源集合， 當在視圖中注冊一個資源包，在渲染W(wǎng)eb頁面時會包含包中的CSS和JavaScript文件。

定義資源包

資源包指定為繼承yii\web\AssetBundle的PHP類，包名為可自動加載的PHP類名， 在資源包類中，要指定資源所在位置，包含哪些CSS和JavaScript文件以及和其他包的依賴關(guān)系。

如下代碼定義基礎應用模板使用的主要資源包：

<?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，資源包中包含一個CSS文件?css/site.css，沒有JavaScript文件， 依賴其他兩個包 yii\web\YiiAsset 和 yii\bootstrap\BootstrapAsset， 關(guān)于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 屬性，?資源管理器?會發(fā)布包的資源到一個可Web訪問并覆蓋該屬性， 如果你的資源文件在一個Web可訪問目錄下，應設置該屬性，這樣就不用再發(fā)布了。?路徑別名?可在此處使用。
• yii\web\AssetBundle::baseUrl: 指定對應到y(tǒng)ii\web\AssetBundle::basePath目錄的URL， 和 yii\web\AssetBundle::basePath 類似，如果你指定 yii\web\AssetBundle::sourcePath 屬性，?資源管理器?會發(fā)布這些資源并覆蓋該屬性，路徑別名?可在此處使用。
• yii\web\AssetBundle::js: 一個包含該資源包JavaScript文件的數(shù)組，注意正斜杠"/"應作為目錄分隔符， 每個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文件的數(shù)組，該數(shù)組格式和 yii\web\AssetBundle::js 相同。
• yii\web\AssetBundle::depends: 一個列出該資源包依賴的其他資源包（后兩節(jié)有詳細介紹）。
• yii\web\AssetBundle::jsOptions: 當調(diào)用yii\web\View::registerJsFile()注冊該包?每個?JavaScript文件時， 指定傳遞到該方法的選項。
• yii\web\AssetBundle::cssOptions: 當調(diào)用yii\web\View::registerCssFile()注冊該包?每個?css文件時， 指定傳遞到該方法的選項。
• yii\web\AssetBundle::publishOptions: 當調(diào)用yii\web\AssetManager::publish()發(fā)布該包資源文件到Web目錄時 指定傳遞到該方法的選項，僅在指定了yii\web\AssetBundle::sourcePath屬性時使用。

資源位置

資源根據(jù)它們的位置可以分為：

• 源資源: 資源文件和PHP源代碼放在一起，不能被Web直接訪問，為了使用這些源資源，它們要拷貝到一個可Web訪問的Web目錄中 成為發(fā)布的資源，這個過程稱為發(fā)布資源，隨后會詳細介紹。
• 發(fā)布資源: 資源文件放在可通過Web直接訪問的Web目錄中；
• 外部資源: 資源文件放在你的Web應用不同的Web服務器上；

當定義資源包類時候，如果你指定了yii\web\AssetBundle::sourcePath 屬性，就表示任何使用相對路徑的資源會被 當作源資源；如果沒有指定該屬性，就表示這些資源為發(fā)布資源（因此應指定yii\web\AssetBundle::basePath 和 yii\web\AssetBundle::baseUrl 讓Yii知道它們的位置）。

推薦將資源文件放到Web目錄以避免不必要的發(fā)布資源過程，這就是之前的例子指定 yii\web\AssetBundle::basePath 而不是 yii\web\AssetBundle::sourcePath.

對于?擴展來說，由于它們的資源和源代碼都在不能Web訪問的目錄下， 在定義資源包類時必須指定yii\web\AssetBundle::sourcePath屬性。

注意: yii\web\AssetBundle::sourcePath 屬性不要用@webroot/assets，該路徑默認為 yii\web\AssetManager資源管理器將源資源發(fā)布后存儲資源的路徑，該路徑的所有內(nèi)容會認為是臨時文件， 可能會被刪除。

資源依賴

當Web頁面包含多個CSS或JavaScript文件時，它們有一定的先后順序以避免屬性覆蓋， 例如，Web頁面在使用jQuery UI小部件前必須確保jQuery JavaScript文件已經(jīng)被包含了， 我們稱這種資源先后次序稱為資源依賴。

資源依賴主要通過yii\web\AssetBundle::depends 屬性來指定， 在AppAsset?示例中，資源包依賴其他兩個資源包： yii\web\YiiAsset 和 yii\bootstrap\BootstrapAsset 也就是該資源包的CSS和JavaScript文件要在這兩個依賴包的文件包含?之后?才包含。

資源依賴關(guān)系是可傳遞，也就是人說A依賴B，B依賴C，那么A也依賴C。

資源選項

可指定yii\web\AssetBundle::cssOptions 和 yii\web\AssetBundle::jsOptions 屬性來自定義頁面包含CSS和JavaScript文件的方式， 這些屬性值會分別傳遞給 yii\web\View::registerCssFile() 和 yii\web\View::registerJsFile() 方法， 在視圖?調(diào)用這些方法包含CSS和JavaScript文件時。

注意: 在資源包類中設置的選項會應用到該包中?每個?CSS/JavaScript 文件，如果想對每個文件使用不同的選項， 應創(chuàng)建不同的資源包并在每個包中使用一個選項集。

例如，只想IE9或更高的瀏覽器包含一個CSS文件，可以使用如下選項：

public $cssOptions = ['condition' => 'lte IE9'];

這會是包中的CSS文件使用以下HTML標簽包含進來：

<!--[if lte IE9]>
<link rel="stylesheet" href="path/to/foo.css">
<![endif]-->

為鏈接標簽包含<noscript>可使用如下代碼：

public $cssOptions = ['noscript' => true];

為使JavaScript文件包含在頁面head區(qū)域（JavaScript文件默認包含在body的結(jié)束處）使用以下選項：

public $jsOptions = ['position' => \yii\web\View::POS_HEAD];

Bower 和 NPM 資源

大多數(shù) JavaScript/CSS 包通過Bower?和/或?NPM管理， 如果你的應用或擴展使用這些包，推薦你遵循以下步驟來管理庫中的資源：

1. 修改應用或擴展的?composer.json?文件將包列入require?中， 應使用bower-asset/PackageName?(Bower包) 或?npm-asset/PackageName?(NPM包)來對應庫。
2. 創(chuàng)建一個資源包類并將你的應用或擴展要使用的JavaScript/CSS 文件列入到類中， 應設置 yii\web\AssetBundle::sourcePath 屬性為@bower/PackageName?或?@npm/PackageName， 因為根據(jù)別名Composer會安裝Bower或NPM包到對應的目錄下。

注意: 一些包會將它們分布式文件放到一個子目錄中，對于這種情況，應指定子目錄作為 yii\web\AssetBundle::sourcePath屬性值，例如，yii\web\JqueryAsset使用?@bower/jquery/dist?而不是?@bower/jquery。

使用資源包

為使用資源包，在視圖中調(diào)用yii\web\AssetBundle::register()方法先注冊資源， 例如，在視圖模板可使用如下代碼注冊資源包：

use app\assets\AppAsset;
AppAsset::register($this);  // $this 代表視圖對象

如果在其他地方注冊資源包，應提供視圖對象，如在?小部件?類中注冊資源包， 可以通過?$this->view?獲取視圖對象。

當在視圖中注冊一個資源包時，在背后Yii會注冊它所依賴的資源包，如果資源包是放在Web不可訪問的目錄下，會被發(fā)布到可訪問的目錄， 后續(xù)當視圖渲染頁面時，會生成這些注冊包包含的CSS和JavaScript文件對應的<link>?和?<script>?標簽， 這些標簽的先后順序取決于資源包的依賴關(guān)系以及在 yii\web\AssetBundle::css和yii\web\AssetBundle::js 的列出來的前后順序。

自定義資源包

Yii通過名為?assetManager的應用組件實現(xiàn)[[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,   // 一定不要發(fā)布該資源
                    'js' => [
                        '//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js',
                    ]
                ],
            ],
        ],
    ],
];

可通過類似yii\web\AssetManager::bundles配置多個資源包，數(shù)組的鍵應為資源包的類名（最開頭不要反斜杠）， 數(shù)組的值為對應的配置數(shù)組.

提示: 可以根據(jù)條件判斷使用哪個資源，如下示例為如何在開發(fā)環(huán)境用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 數(shù)組中每個相關(guān)資源文件會和該部署進行對比， 如果數(shù)組任何鍵對比為資源文件的最后文件名（如果有的話前綴為 yii\web\AssetBundle::sourcePath），對應的值為替換原來的資源。 例如，資源文件my/path/to/jquery.js?匹配鍵?jquery.js.

注意: 只有相對相對路徑指定的資源對應到資源部署，替換的資源路徑可以為絕對路徑，也可為和yii\web\AssetManager::basePath相關(guān)的路徑。

資源發(fā)布

如前所述，如果資源包放在Web不能訪問的目錄，當視圖注冊資源時資源會被拷貝到一個Web可訪問的目錄中， 這個過程稱為資源發(fā)布，yii\web\AssetManager會自動處理該過程。

資源默認會發(fā)布到@webroot/assets目錄，對應的URL為@web/assets， 可配置yii\web\AssetManager::basePath 和 yii\web\AssetManager::baseUrl 屬性自定義發(fā)布位置。

除了拷貝文件方式發(fā)布資源，如果操作系統(tǒng)和Web服務器允許可以使用符號鏈接，該功能可以通過設置 yii\web\AssetManager::linkAssets 為 true 來啟用。

return [
    // ...
    'components' => [
        'assetManager' => [
            'linkAssets' => true,
        ],
    ],
];

使用以上配置，資源管理器會創(chuàng)建一個符號鏈接到要發(fā)布的資源包源路徑，這比拷貝文件方式快并能確保發(fā)布的資源一直為最新的。

常用資源包

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，應盡量使用這些預定義資源包而非自己創(chuàng)建， 如果這些包的默認配置不能滿足你的需求，可以自定義配置，詳情參考自定義資源包。

資源轉(zhuǎn)換

除了直接編寫CSS 和/或 JavaScript代碼，開發(fā)人員經(jīng)常使用擴展語法來編寫，再使用特殊的工具將它們轉(zhuǎn)換成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資源管理器會自動運行預處理工具將使用擴展語法 的資源轉(zhuǎn)換成CSS/JavaScript，當視圖最終渲染頁面時，在頁面中包含的是CSS/Javascipt文件，而不是原始的擴展語法代碼文件。

Yii使用文件擴展名來表示資源使用哪種擴展語法，默認可以識別如下語法和文件擴展名：

• LESS:?.less
• SCSS:?.scss
• Stylus:?.styl
• CoffeeScript:?.coffee
• TypeScript:?.ts

Yii依靠安裝的預處理工具來轉(zhuǎn)換資源，例如，為使用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 屬性指定支持的擴展語法， 數(shù)組的鍵為文件擴展名（前面不要.），數(shù)組的值為目標資源文件擴展名和執(zhí)行資源轉(zhuǎn)換的命令， 命令中的標記?{from}?和{to}會分別被源資源文件路徑和目標資源文件路徑替代。

補充: 除了以上方式，也有其他的方式來處理擴展語法資源，例如，可使用編譯工具如grunt?來監(jiān)控并自動轉(zhuǎn)換擴展語法資源，此時，應使用資源包中編譯后的CSS/Javascript文件而不是原始文件。

合并和壓縮資源

一個Web頁面可以包含很多CSS 和/或 JavaScript 文件，為減少HTTP 請求和這些下載文件的大小， 通常的方式是在頁面中合并并壓縮多個CSS/JavaScript 文件為一個或很少的幾個文件，并使用壓縮后的文件而不是原始文件。

補充: 合并和壓縮資源通常在應用在產(chǎn)品上線模式，在開發(fā)模式下使用原始的CSS/JavaScript更方便調(diào)試。

接下來介紹一種合并和壓縮資源文件而不需要修改已有代碼的方式：

1. 找出應用中所有你想要合并和壓縮的資源包，
2. 將這些包分成一個或幾個組，注意每個包只能屬于其中一個組，
3. 合并/壓縮每個組里CSS文件到一個文件，同樣方式處理JavaScript文件，
4. 為每個組定義新的資源包：
   • 設置yii\web\AssetBundle::css 和 yii\web\AssetBundle::js 屬性分別為壓縮后的CSS和JavaScript文件；
   • 自定義設置每個組內(nèi)的資源包，設置資源包的yii\web\AssetBundle::css 和 yii\web\AssetBundle::js 屬性為空, 并設置它們的 yii\web\AssetBundle::depends 屬性為每個組新創(chuàng)建的資源包。

使用這種方式，當在視圖中注冊資源包時，會自動觸發(fā)原始包所屬的組資源包的注冊，然后，頁面就會包含以合并/壓縮的資源文件， 而不是原始文件。

示例

使用一個示例來解釋以上這種方式：

鑒定你的應用有兩個頁面X 和 Y，頁面X使用資源包A，B和C，頁面Y使用資源包B，C和D。

有兩種方式劃分這些資源包，一種使用一個組包含所有資源包，另一種是將（A,B,C）放在組X，（B，C，C）放在組Y， 哪種方式更好？第一種方式優(yōu)點是兩個頁面使用相同的已合并CSS和JavaScript文件使HTTP緩存更高效，另一方面，由于單個組包含所有文件， 已合并的CSS和Javascipt文件會更大，因此會增加文件傳輸時間，在這個示例中，我們使用第一種方式，也就是用一個組包含所有包。

補充: 將資源包分組并不是無價值的，通常要求分析現(xiàn)實中不同頁面各種資源的數(shù)據(jù)量，開始時為簡便使用一個組。

在所有包中使用工具(例如?Closure Compiler,?YUI Compressor) 來合并和壓縮CSS和JavaScript文件， 注意合并后的文件滿足包間的先后依賴關(guān)系，例如，如果包A依賴B，B依賴C和D，那么資源文件列表以C和D開始，然后為B最后為A。

合并和壓縮之后，會得到一個CSS文件和一個JavaScript文件，假定它們的名稱為all-xyz.css?和?all-xyz.js，?xyz?為使文件名唯一以避免HTTP緩存問題的時間戳或哈希值。

現(xiàn)在到最后一步了，在應用配置中配置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']],
            ],
        ],
    ],
];

如自定義資源包?小節(jié)中所述，如上配置改變每個包的默認行為， 特別是包A、B、C和D不再包含任何資源文件，都依賴包含合并后的all-xyz.css?和?all-xyz.js文件的包all， 因此，對于頁面X會包含這兩個合并后的文件而不是包A、B、C的原始文件，對于頁面Y也是如此。

最后有個方法更好地處理上述方式，除了直接修改應用配置文件，可將自定義包數(shù)組放到一個文件，在應用配置中根據(jù)條件包含該文件，例如：

return [
    'components' => [
        'assetManager' => [
            'bundles' => require(__DIR__ . '/' . (YII_ENV_PROD ? 'assets-prod.php' : 'assets-dev.php')),  
        ],
    ],
];

如上所示，在產(chǎn)品上線模式下資源包數(shù)組存儲在assets-prod.php文件中，不是產(chǎn)品上線模式存儲在assets-dev.php文件中。

使用?asset?命令

Yii提供一個名為asset控制臺命令來使上述操作自動處理。

為使用該命令，應先創(chuàng)建一個配置文件設置哪些資源包要合并以及分組方式，可使用asset/template?子命令來生成一個模板， 然后修改模板成你想要的。

yii asset/template assets.php

該命令在當前目錄下生成一個名為assets.php的文件，文件的內(nèi)容類似如下：

<?php
/**
 * 為控制臺命令"yii asset"使用的配置文件
 * 注意在控制臺環(huán)境下，一些路徑別名如 '@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' => [
    ],
];

應修改該文件的bundles的選項指定哪些包你想要合并，在targets選項中應指定這些包如何分組，如前述的可以指定一個或多個組。

注意: 由于在控制臺應用別名?@webroot?and?@web?不可用，應在配置中明確指定它們。

JavaScript文件會被合并壓縮后寫入到js/all-{hash}.js文件，其中 {hash} 會被結(jié)果文件的哈希值替換。

jsCompressor?和?cssCompressor?選項指定控制臺命令或PHP回調(diào)函數(shù)來執(zhí)行JavaScript和CSS合并和壓縮， Yii默認使用Closure Compiler來合并JavaScript文件， 使用YUI Compressor來合并CSS文件， 你應手工安裝這些工具或修改選項使用你喜歡的工具。

根據(jù)配置文件，可執(zhí)行asset?命令來合并和壓縮資源文件并生成一個新的資源包配置文件assets-prod.php:

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

生成的配置文件可以在應用配置中包含，如最后一小節(jié)所描述的。

補充: 使用asset?命令并不是唯一一種自動合并和壓縮過程的方法，可使用優(yōu)秀的工具grunt來完成這個過程。