Yii资源包加载JS/CSS

1.资源包

Yii 在资源包中管理资源，资源包简单的说就是放在一个目录下的资源集合， 当在视图中注册一个资源包， 在渲染 Web 页面时会包含包中的 CSS 和 JavaScript 文件。

2.定义资源包

资源包指定为继承 yii\web\AssetBundle 的 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',
        ['css/print.css', 'media' => 'print'],
    ];
    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， 关于 yii\web\AssetBundle 的属性的更多详细如下所述：

• sourcePath：指定包包含资源文件的根目录， 当根目录不能被 Web 访问时该属性应设置，否则，应设置 basePath 属性和 baseUrl。 路径别名 可在此处使用；（sourcepath指的是绝对路径；而basepath与baseurl指的是路径与url）
• basePath：指定包含资源包中资源文件并可Web访问的目录， 当指定 sourcePath 属性， 资源管理器 会发布包的资源到一个可 Web 访问并覆盖该属性， 如果你的资源文件在一个 Web 可访问目录下，应设置该属性，这样就不用再发布了。 路径别名 可在此处使用。
• baseUrl：指定对应到 basePath 目录的 URL， 和 basePath 类似， 如果你指定 sourcePath 属性， 资源管理器 会发布这些资源并覆盖该属性，路径别名 可在此处使用。
• css：列出此包中包含的 CSS 文件的数组。 请注意，只应使用正斜杠“/”作为目录分隔符。每个文件都可以单独指定为字符串， 也可以与属性标记及其值一起指定在数组中。
• 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。
• depends：一个列出该资源包依赖的 其他资源包（后两节有详细介绍）。
• jsOptions：当调用 yii\web\View::registerJsFile() 注册该包 每个 JavaScript 文件时， 指定传递到该方法的选项。
• cssOptions：当调用 yii\web\View::registerCssFile() 注册该包 每个 CSS 文件时， 指定传递到该方法的选项。
• publishOptions：当调用 yii\web\AssetManager::publish() 发布该包资源文件到 Web 目录时 指定传递到该方法的选项，仅在指定了 sourcePath 属性时使用。

3.资源位置

资源根据它们的位置可以分为：

• 源资源: 资源文件和 PHP 源代码放在一起，不能被 Web 直接访问，为了使用这些源资源， 它们要拷贝到一个可 Web 访问的 Web 目录中 成为发布的资源，这个过程称为发布资源，随后会详细介绍。（）
• 发布资源: 资源文件放在可通过 Web 直接访问的 Web 目录中；（百度地图api）
• 外部资源: 资源文件放在与你的 Web 应用不同的 Web 服务器上；类似于csn之类的

当定义资源包类时候，如果你指定了sourcePath 属性， 就表示任何使用相对路径的资源会被当作源资源； 如果没有指定该属性，就表示这些资源为发布资源（因此应指定basePath 和 baseUrl 让 Yii 知道它们的位置）。

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

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

4.资源依赖

当 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。

5.资源选项 

可指定 cssOptions 和 jsOptions 属性来自定义页面包含 CSS 和 JavaScript 文件的方式， 这些属性值会分别传递给 yii\web\View::registerCssFile() 和 yii\web\View::registerJsFile() 方法， 在视图调用这些方法包含 CSS 和 JavaScript 文件时。

1.
例如，只想 IE9 或更高的浏览器包含一个 CSS 文件，可以使用如下选项：

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

这会使包中的 CSS 文件使用以下 HTML 标签包含进来：

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

2.
为链接标签包含 <noscript> 可使用如下代码：
为链接标签包含 <noscript> 可使用如下代码：

3.
为使 JavaScript 文件包含在页面 head 区域（JavaScript 文件默认包含在 body 的结束处） 
使用以下选项：
public $jsOptions = ['position' => \yii\web\View::POS_HEAD];

4.限制发布
默认情况下，当发布资源包时，所有在 yii\web\AssetBundle::$sourcePath 目录里的内容都会发布。 你
可以通过配置 publishOptions 属性来自定义这种行为。 比如，为了只发布 yii\web\AssetBundle::$sourcePath 其中的某些内容或子目录里的内容， 可以在资源类中试试下面的做
法：
上述的代码为 "fontawesome" package 定义了资源包。 通过配置发布选项的 only 下标，只有 fonts 和 
css 子目录会发布。


<?php
namespace app\assets;

use yii\web\AssetBundle;

class FontAwesomeAsset extends AssetBundle 
{
    public $sourcePath = '@bower/font-awesome'; 
    public $css = [ 
        'css/font-awesome.min.css', 
    ];
    public $publishOptions = [
        'only' => [
            'fonts/',
            'css/',
        ]
    ];
}  

6.使用资源包

6.1 简述使用

为使用资源包，先在视图中调用 yii\web\AssetBundle::register() 方法注册资源， 例如，在视图模板可使用如下代码注册资源包：

use app\assets\AppAsset;
AppAsset::register($this);  // $this 代表视图对象

信息： yii\web\AssetBundle::register() 方法返回资源包对象，该对象包含了发布资源的信息比如 basePath 或 baseUrl。

如果在其他地方注册资源包，应提供视图对象，如在 小部件 类中注册资源包， 可以通过 $this->view 获取视图对象。

当在视图中注册一个资源包时，在背后 Yii 会注册它所依赖的资源包， 如果资源包是放在 Web 不可访问的目录下，会被发布到可访问的目录， 后续当视图渲染页面时， 会生成这些注册包包含的 CSS 和 JavaScript 文件对应的 <link> 和 <script> 标签， 这些标签的先后顺序取决于资源包的依赖关系以及在 yii\web\AssetBundle::$css 和 yii\web\AssetBundle::$js 的列出来的前后顺序。

6.2 动态资源包

作为常规 PHP 类，资源包可以承担一些与之相关的额外逻辑，并可以动态调整其内部参数。 比如：你也许用到某些复杂的 JavaScript 库，它提供一些用于国际化的包，并分成单独的源文件：每个文件对应于国际化中所支持的语言。 为了让这个 JavaScript 库正常工作，你需要把这些单独的语言源文件加载到页面中。 这可以通过覆盖 yii\web\AssetBundle::init()方法来实现：

namespace app\assets;

use yii\web\AssetBundle;
use Yii;

class SophisticatedAssetBundle extends AssetBundle
{
    public $sourcePath = '/path/to/sophisticated/src';
    public $js = [
        'sophisticated.js' // file, which is always used
    ];

    public function init()
    {
        parent::init();
        $this->js[] = 'i18n/' . Yii::$app->language . '.js'; // dynamic file added
    }
}

特定的资源包也可以通过 yii\web\AssetBundle::register() 返回的实例进行调整。 例如：

use app\assets\SophisticatedAssetBundle;
use Yii;

$bundle = SophisticatedAssetBundle::register(Yii::$app->view);
$bundle->js[] = 'i18n/' . Yii::$app->language . '.js'; // dynamic file added

6.3自定义资源包

6.3.1展示

Yii 通过配置名为 assetManager 的应用组件来使用 yii\web\AssetManager， 通过配置 yii\web\AssetManager::$bundles属性，可以自定义资源包的行为， 例如，yii\web\JqueryAsset 资源包默认从 jquery Bower 包中使用 jquery.js 文件， 为了提高可用性和性能，你可能需要从 CDN 服务器上获取 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 配置多个资源包， 数组的键应为资源包的类名（最开头不要反斜杠）， 数组的值为对应的配置数组.

6.3.2判断

提示： 可以根据条件判断使用哪个资源，如下示例为如何在开发环境用 jquery.js， 否则用jquery.min.js：

'yii\web\JqueryAsset' => [
    'js' => [
        YII_ENV_DEV ? 'jquery.js' : 'jquery.min.js'
    ]
],

6.3.3禁用

可以将资源包名称设置为 false 来禁用一个或多个资源包， 当视图中注册一个禁用资源包， 视图不会包含任何
该包的资源以及不会注册它所依赖的包， 例如，为禁用 yii\web\JqueryAsset，可以使用如下配置：

return [
    // ...
    'components' => [
        'assetManager' => [
            'bundles' => [
                'yii\web\JqueryAsset' => false,
            ],
        ],
    ],
];

6.3.4优先级

可以设置 yii\web\AssetManager::$bundles 为 false 来禁用 所有 的资源包。

需要记住，使用 yii\web\AssetManager::$bundles 进行自定义时，只在创建资源包时起作用，例如，在对象的构造函数阶段。 这意味着在此之后对该资源包对象所做的任何调整都将覆盖在配置数组中 yii\web\AssetManager::$bundles 的配置。 特别是：在 yii\web\AssetBundle::init() 方法内或在注册的资源包对象上进行的调整优先于 AssetManager 配置。 下面给个例子来说明在配置数组中对 yii\web\AssetManager::$bundles 的配置是不起作用的：

// Program source code:

namespace app\assets;

use yii\web\AssetBundle;
use Yii;

class LanguageAssetBundle extends AssetBundle
{
    // ...

    public function init()
    {
        parent::init();
        $this->baseUrl = '@web/i18n/' . Yii::$app->language; // 将不能通过 `AssetManager` 来管理！
    }
}
// ...

$bundle = \app\assets\LargeFileAssetBundle::register(Yii::$app->view);
$bundle->baseUrl = YII_DEBUG ? '@web/large-files': '@web/large-files/minified'; // 将不能通过 `AssetManager` 来管理！


// Application config :

return [
    // ...
    'components' => [
        'assetManager' => [
            'bundles' => [
                'app\assets\LanguageAssetBundle' => [
                    'baseUrl' => 'http://some.cdn.com/files/i18n/en' // 这行代码不起作用！
                ],
                'app\assets\LargeFileAssetBundle' => [
                    'baseUrl' => 'http://some.cdn.com/files/large-files' // 这行代码不起作用！
                ],
            ],
        ],
    ],
];

下面说的是  资源包里面的配置优先于资源组管理组件的配置

// Program source code:

namespace app\assets;

use yii\web\AssetBundle;
use Yii;

class LanguageAssetBundle extends AssetBundle
{
    // ...

    public function init()
    {
        parent::init();
        $this->baseUrl = '@web/i18n/' . Yii::$app->language; // 将不能通过 `AssetManager` 来管理！
    }
}
// ...

$bundle = \app\assets\LargeFileAssetBundle::register(Yii::$app->view);
$bundle->baseUrl = YII_DEBUG ? '@web/large-files': '@web/large-files/minified'; // 将不能通过 `AssetManager` 来管理！


// Application config :

return [
    // ...
    'components' => [
        'assetManager' => [
            'bundles' => [
                'app\assets\LanguageAssetBundle' => [
                    'baseUrl' => 'http://some.cdn.com/files/i18n/en' // 这行代码不起作用！
                ],
                'app\assets\LargeFileAssetBundle' => [
                    'baseUrl' => 'http://some.cdn.com/files/large-files' // 这行代码不起作用！
                ],
            ],
        ],
    ],
];

7.资源映射

有时你想“修复”多个资源包中资源文件的错误或者不兼容，例如包 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',
            ],
        ],
    ],
];

assetMap 的键为你想要修复的资源名，值为你想要使用的资源路径， 当视图注册资源包，在 css 和 js 数组中每个相关资源文件会和该部署进行对比， 如果数组任何键对比为资源文件的最后文件名 （如果有的话前缀为 yii\web\AssetBundle::$sourcePath），对应的值为替换原来的资源。 例如，资源文件 my/path/to/jquery.js 匹配键 jquery.js.

注意： 只有相对路径指定的资源对应到资源部署，替换的资源路径可以为绝对路径， 也可为和 yii\web\AssetManager::$basePath 相关的路径。

8.资源发布

如前所述，如果资源包放在 Web 不能访问的目录， 当视图注册资源时资源会被拷贝到一个 Web 可访问的目录中， 这个过程称为资源发布，asset manager 会自动处理该过程。

资源默认会发布到 @webroot/assets 目录，对应的 URL 为 @web/assets， 可配置 basePath 和 baseUrl 属性自定义发布位置。

除了拷贝文件方式发布资源，如果操作系统和 Web 服务器允许可以使用符号链接，该功能可以通过设置 linkAssets 为 true 来启用。

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

如前所述，如果资源包放在 Web 不能访问的目录， 当视图注册资源时资源会被拷贝到一个 Web 可访问的目录中， 这个过程称为资源发布，asset manager 会自动处理该过程。

9.清除缓存

对于运行在生产模式的 Web 应用程序，通常会为资源包和其他静态资源开启 HTTP 缓存。 但这种做法有个不好的地方就是，当你更新某个资源并部署到生产环境时， 客户端可能由于 HTTP 缓存而仍然使用旧版本的资源。 为了克服该不足，你可以试试清除缓存特性，它由 2.0.3 版本引入，只需如下配置 yii\web\AssetManager 即可：

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

通过上述配置后，每个已发布资源的 URL 都会附加一个最后更新时间戳的信息。 比如，yii.js 的 URL 可能是 /assets/5515a87c/yii.js?v=1423448645"， 这里的参数 v 表示 yii.js 文件的最后更新时间戳。 现在一旦你更新了某个资源，它的 URL 也会改变进而强制客户端获取该资源的最新版本。

10.常用资源包

Yii框架定义许多资源包，如下资源包是最常用， 可在你的应用或扩展代码中引用它们。

• yii\web\YiiAsset：主要包含 yii.js 文件，该文件完成模块 JavaScript 代码组织功能， 也为 data-method 和 data-confirm 属性提供特别支持和其他有用的功能。 有关 yii.js 的更多信息可以在 客户端脚本部分 中找到。
• 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，应尽量使用这些预定义资源包而非自己创建， 如果这些包的默认配置不能满足你的需求，可以自定义配置， 详情参考自定义资源包。

11.资源转换

除了直接编写 CSS 或 JavaScript 代码，开发人员经常使用扩展语法来编写，再使用特殊的工具将它们转换成 CSS/JavaScript。 例如，对于 CSS 代码可使用 LESS 或 SCSS， 对于 JavaScript 可使用 TypeScript。

可将使用扩展语法的资源文件列到资源包的 css 和 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',
    ];
}

当在视图中注册一个这样的资源包，asset manager 资源管理器会自动运行预处理工具将使用扩展语法 的资源转换成 CSS/JavaScript，当视图最终渲染页面时， 在页面中包含的是 CSS/Javascipt 文件， 而不是原始的扩展语法代码文件。

Yii 使用文件扩展名来表示资源使用哪种扩展语法， 默认可以识别如下语法和文件扩展名：

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

Yii 依靠安装的预处理工具来转换资源，例如， 为使用 LESS，应安装 lessc 预处理命令。

可配置 yii\web\AssetManager::$converter 自定义预处理命令和支持的扩展语法， 如下所示：