Html 幫助類(lèi)

任何一個(gè) web 應(yīng)用程序會(huì)生成很多 HTMl 超文本標(biāo)記。如果超文本標(biāo)記是靜態(tài)的， 那么將 PHP 和 HTML 混合在一個(gè)文件里?這種做法是非常高效的。但是，如果這些超文本標(biāo)記是動(dòng)態(tài)生成的，那么如果沒(méi)有額外的輔助工具，這個(gè)過(guò)程將會(huì)變得復(fù)雜。 Yii 通過(guò) HTML 幫助類(lèi)來(lái)提供生成超文本標(biāo)記的方法。這個(gè)幫助類(lèi)包含有一系列的用于處理通用的 HTML 標(biāo)簽和其屬性以及內(nèi)容的靜態(tài)方法。

注意：如果你的超文本標(biāo)記接近靜態(tài)的，那么最好是直接使用 HTML。 沒(méi)有必要把所有的超文本標(biāo)記都用 HTML 輔助類(lèi)來(lái)生成。

基礎(chǔ)

由于通過(guò)字符串連接來(lái)生成動(dòng)態(tài)的 HTML 會(huì)很容易變得凌亂， Yii 提供了一系列的靜態(tài)方法來(lái)操作標(biāo)簽配置并基于這些配置來(lái)創(chuàng)建對(duì)應(yīng)的標(biāo)簽。

生成標(biāo)簽

生成一個(gè)標(biāo)簽的代碼類(lèi)似如下：

<?= Html::tag('p', Html::encode($user->name), ['class' => 'username']) ?>

這個(gè)方法的第一個(gè)參數(shù)是標(biāo)簽名稱(chēng)。第二個(gè)是要裝入到開(kāi)始和結(jié)束標(biāo)簽間的內(nèi)容。 注意到我們使用?Html::encode?。那是因?yàn)閮?nèi)容不會(huì)被自動(dòng)的轉(zhuǎn)碼以允許在有需要的時(shí)候嵌套 HTML。 第三個(gè)參數(shù)是一個(gè) HTML 配置數(shù)組，或者換言之，標(biāo)簽屬性。在這個(gè)數(shù)組中，數(shù)組的下標(biāo)是屬性名稱(chēng)， 比如?class，target="_blank" href?或者?target，而值則是對(duì)應(yīng)屬性的值。

以上代碼會(huì)生成如下 HTML ：

<p class="username">samdark</p>

如果你只需要開(kāi)啟一個(gè)標(biāo)簽或者關(guān)閉一個(gè)標(biāo)簽，你可以使用?Html::beginTag()?和?Html::endTag()?方法。

標(biāo)簽屬性（ Options ）在 Html 幫助類(lèi)很多方法和大量的小部件中都有使用。在這些情況下， 有一些額外的處理我們需要知道：

• 如果一個(gè)值為 null ，那么對(duì)應(yīng)的屬性將不會(huì)被渲染。
• 如果是布爾類(lèi)型的值的屬性，將會(huì)被當(dāng)做?布爾屬性?來(lái)處理。
• 屬性的值將會(huì)用 yii\helpers\Html::encode() 方法進(jìn)行 HTML 轉(zhuǎn)碼處理。

• 如果一個(gè)屬性的值是一個(gè)數(shù)組，那么它將會(huì)被如下處理：

• • 如果這個(gè)屬性是一個(gè)如 yii\helpers\Html::$dataAttributes 所列的數(shù)據(jù)屬性， 比如?data?或者?ng，一系列的屬性列表將會(huì)被渲染，每個(gè)代表值數(shù)組中的元素。 比如：?'data' => ['id' => 1, 'name' => 'yii']?將會(huì)生成?data-id="1" data-name="yii"；?'data' => ['params' => ['id' => 1, 'name' => 'yii'], 'status' => 'ok']?生成?data-params='{"id":1,"name":"yii"}' data-status="ok"。 注意后者 中，一個(gè)子數(shù)組被輸出為 JSON 。
  • 如果這個(gè)屬性不是一個(gè)數(shù)據(jù)屬性，那么值將會(huì)被 JSON-encoded。比如：['params' => ['id' => 1, 'name' => 'yii']?生成?params='{"id":1,"name":"yii"}'。

生成 CSS 類(lèi)和樣式

當(dāng)開(kāi)始構(gòu)造一個(gè) HTML 標(biāo)簽的屬性時(shí)，我們經(jīng)常需要對(duì)默認(rèn)的屬性進(jìn)行修改。 為了添加或者刪除 CSS 類(lèi)，你可以使用如下代碼：

$options = ['class' => 'btn btn-default'];

if ($type === 'success') {
    Html::removeCssClass($options, 'btn-default');
    Html::addCssClass($options, 'btn-success');
}

echo Html::tag('div', 'Pwede na', $options);

// in case of $type of 'success' it will render// <div class="btn btn-success">Pwede na</div>

基于同樣的目的，針對(duì)?style?屬性：

$options = ['style' => ['width' => '100px', 'height' => '100px']];

// gives style="width: 100px; height: 200px; position: absolute;"
Html::addCssStyle($options, 'height: 200px; position: absolute;');

// gives style="position: absolute;"
Html::removeCssStyle($options, ['width', 'height']);

當(dāng)使用 yii\helpers\Html::addCssStyle() 方法時(shí)，你可以指定一個(gè)和 CSS 屬性相關(guān)的名值對(duì)的數(shù)組， 也可以直接是一個(gè)類(lèi)似?width: 100px; height: 200px;?的字符串。這些格式將會(huì)自動(dòng)的被 yii\helpers\Html::cssStyleFromArray() 和yii\helpers\Html::cssStyleToArray() 方法進(jìn)行轉(zhuǎn)換。方法 yii\helpers\Html::removeCssStyle() 接收一個(gè)包含要被移除的屬性數(shù)組作為參數(shù)。 如果只想移除一個(gè)屬性，你可以直接傳遞一個(gè)字符串。

標(biāo)簽內(nèi)容的轉(zhuǎn)碼和解碼

為了讓內(nèi)容能夠正確安全的顯示，一些 HTML 特殊字符應(yīng)該被轉(zhuǎn)碼。在 PHP 中， 這個(gè)操作由?htmlspecialchars?和htmlspecialchars_decode?完成。 直接使用這些方法的問(wèn)題是，你總是需要指定轉(zhuǎn)碼所需的額外標(biāo)志。由于標(biāo)志一般總是不變的，而內(nèi)容轉(zhuǎn)碼的過(guò)程為了避免一些安全問(wèn)題， 需要和應(yīng)用的默認(rèn)過(guò)程匹配， Yii 提供了兩個(gè)簡(jiǎn)單可用的對(duì) PHP 原生方法的封裝：

$userName = Html::encode($user->name);
echo $userName;

$decodedUserName = Html::decode($userName);

表單

處理表單標(biāo)簽是大量的重復(fù)性勞動(dòng)并且易錯(cuò)。因此， Yii 也提供了一系列的方法來(lái)輔助處理表單標(biāo)簽。

注意： 考慮在處理 models 以及需要驗(yàn)證的情形下，使用 yii\widgets\ActiveForm 組件。

創(chuàng)建表單

表單可以用類(lèi)似如下代碼，使用 yii\helpers\Html::beginForm() 方法開(kāi)啟：

<?= Html::beginForm(['order/update', 'id' => $id], 'post', ['enctype' => 'multipart/form-data']) ?>

方法的第一個(gè)參數(shù)為表單將要被提交的 URL 地址。它可以以 Yii 路由的形式被指定，并由 yii\helpers\Url::to() 來(lái)接收處理。 第二個(gè)參數(shù)是使用的方法，默認(rèn)為?post?方法。第三個(gè)參數(shù)為表單標(biāo)簽的屬性數(shù)組。在上面的例子中， 我們把編碼 POST 請(qǐng)求中的表單數(shù)據(jù)的方式改為?multipart/form-data。 如果是上傳文件，這個(gè)調(diào)整是必須的。

關(guān)閉表單標(biāo)簽非常簡(jiǎn)單：

<?= Html::endForm() ?>

按鈕

你可以用如下代碼生成按鈕：

<?= Html::button('Press me!', ['class' => 'teaser']) ?><?= Html::submitButton('Submit', ['class' => 'submit']) ?><?= Html::resetButton('Reset', ['class' => 'reset']) ?>

上述三個(gè)方法的第一個(gè)參數(shù)為按鈕的標(biāo)題，第二個(gè)是標(biāo)簽屬性。標(biāo)題默認(rèn)沒(méi)有進(jìn)行轉(zhuǎn)碼，如果標(biāo)題是由終端用輸入的，那么請(qǐng)自行用 yii\helpers\Html::encode() 方法進(jìn)行轉(zhuǎn)碼。

輸入欄

input 相關(guān)的方法有兩組：以?active?開(kāi)頭的被稱(chēng)為 active inputs，另一組則不以其開(kāi)頭。 active inputs 依據(jù)指定的模型和屬性獲取數(shù)據(jù)，而普通 input 則是直接指定數(shù)據(jù)。

一般用法如下：

type, input name, input value, options
<?= Html::input('text', 'username', $user->name, ['class' => $username]) ?>

type, model, model attribute name, options
<?= Html::activeInput('text', $user, 'name', ['class' => $username]) ?>

如果你知道 input 類(lèi)型，更方便的做法是使用以下快捷方法：

• yii\helpers\Html::buttonInput()
• yii\helpers\Html::submitInput()
• yii\helpers\Html::resetInput()
• yii\helpers\Html::textInput(), yii\helpers\Html::activeTextInput()
• yii\helpers\Html::hiddenInput(), yii\helpers\Html::activeHiddenInput()
• yii\helpers\Html::passwordInput() / yii\helpers\Html::activePasswordInput()
• yii\helpers\Html::fileInput(), yii\helpers\Html::activeFileInput()
• yii\helpers\Html::textarea(), yii\helpers\Html::activeTextarea()

Radios 和 checkboxes 在方法的聲明上有一點(diǎn)點(diǎn)不同：

<?= Html::radio('agree', true, ['label' => 'I agree']);
<?= Html::activeRadio($model, 'agree', ['class' => 'agreement'])

<?= Html::checkbox('agree', true, ['label' => 'I agree']);
<?= Html::activeCheckbox($model, 'agree', ['class' => 'agreement'])

Dropdown list 和 list box 將會(huì)如下渲染：

<?= Html::dropDownList('list', $currentUserId, ArrayHelper::map($userModels, 'id', 'name')) ?><?= Html::activeDropDownList($users, 'id', ArrayHelper::map($userModels, 'id', 'name')) ?>

<?= Html::listBox('list', $currentUserId, ArrayHelper::map($userModels, 'id', 'name')) ?><?= Html::activeListBox($users, 'id', ArrayHelper::map($userModels, 'id', 'name')) ?>

第一個(gè)參數(shù)是 input 的名稱(chēng)，第二個(gè)是當(dāng)前選中的值，第三個(gè)則是一個(gè)下標(biāo)為列表值， 值為列表標(biāo)簽的名值對(duì)數(shù)組。

如果你需要使用多項(xiàng)選擇， checkbox list 應(yīng)該能夠符合你的需求：

<?= Html::checkboxList('roles', [16, 42], ArrayHelper::map($roleModels, 'id', 'name')) ?><?= Html::activeCheckboxList($user, 'role', ArrayHelper::map($roleModels, 'id', 'name')) ?>

否則，用 radio list ：

<?= Html::radioList('roles', [16, 42], ArrayHelper::map($roleModels, 'id', 'name')) ?><?= Html::activeRadioList($user, 'role', ArrayHelper::map($roleModels, 'id', 'name')) ?>

Labels 和 Errors

如同 inputs 一樣，Yii 也提供了兩個(gè)方法用于生成表單 label 。 帶 ative 方法用于從 model 中取數(shù)據(jù)，另外一個(gè)則是直接接收數(shù)據(jù)。

<?= Html::label('User name', 'username', ['class' => 'label username']) ?><?= Html::activeLabel($user, 'username', ['class' => 'label username'])

為了從一個(gè)或者一組 model 中顯示表單的概要錯(cuò)誤，你可以使用如下方法：

<?= Html::errorSummary($posts, ['class' => 'errors']) ?>

為了顯示單個(gè)錯(cuò)誤：

<?= Html::error($post, 'title', ['class' => 'error']) ?>

Input 的名和值

Yii 提供了方法用于從 model 中獲取 input 的名稱(chēng)，ids，值。這些主要用于內(nèi)部調(diào)用， 但是有時(shí)候你也需要使用它們：

// Post[title]echo Html::getInputName($post, 'title');

// post-titleecho Html::getInputId($post, 'title');

// my first postecho Html::getAttributeValue($post, 'title');

// $post->authors[0]echo Html::getAttributeValue($post, '[0]authors[0]');

在上面的例子中，第一個(gè)參數(shù)為模型，而第二個(gè)參數(shù)是屬性表達(dá)式。 在最簡(jiǎn)單的表單中，這個(gè)屬性表達(dá)式就是屬性名稱(chēng)，但是在一些多行輸入的時(shí)候， 它也可以是屬性名以數(shù)組下標(biāo)前綴或者后綴（也可能是同時(shí)）。

• [0]content?代表多行輸入時(shí)第一個(gè) model 的 content 屬性的數(shù)據(jù)值。
• dates[0]?代表 dates 屬性的第一個(gè)數(shù)組元素。
• [0]dates[0]?代表多行輸入時(shí)第一個(gè) model 的 dates 屬性的第一個(gè)數(shù)組元素。

為了獲取一個(gè)沒(méi)有前綴或者后綴的屬性名稱(chēng)，我們可以如下做：

// datesecho Html::getAttributeName('dates[0]');

樣式表和腳本

Yii 提供兩個(gè)方法用于生成包含內(nèi)聯(lián)樣式和腳本代碼的標(biāo)簽。

<?= Html::style('.danger { color: #f00; }') ?>

Gives you

<style>.danger { color: #f00; }</style>


<?= Html::script('alert("Hello!");', ['defer' => true]);

Gives you

<script defer>alert("Hello!");</script>

如果你想要外聯(lián) css 樣式文件，可以如下做：

<?= Html::cssFile('@web/css/ie5.css', ['condition' => 'IE 5']) ?>

generates

<!--[if IE 5]>
    <link target="_blank" href="http://example.com/css/ie5.css" />
<![endif]-->

第一個(gè)參數(shù)是 URL。第二個(gè)參數(shù)是標(biāo)簽屬性數(shù)組。比普通的標(biāo)簽配置項(xiàng)額外多出的是，你可以指定：

• condition?來(lái)讓?<link?被條件控制注釋包裹（ IE hacker ）。 希望你在未來(lái)不再需要條件控制注釋。
• noscript?可以被設(shè)置為?true?，這樣?<link就會(huì)被?<noscript>包裹，如此那么這段代碼只有在瀏覽器不支持 JavaScript 或者被用戶(hù)禁用的時(shí)候才會(huì)被引入進(jìn)來(lái)。

為了外聯(lián) JavaScript 文件：

<?= Html::jsFile('@web/js/main.js') ?>

這個(gè)方法的第一個(gè)參數(shù)同 CSS 一樣用于指定外聯(lián)鏈接。第二個(gè)參數(shù)是一個(gè)標(biāo)簽屬性數(shù)組。 同?cssFile?一樣，你可以指定?condtion?配置項(xiàng)。

超鏈接

有一個(gè)方法可以用于便捷的生成超鏈接：

<?= Html::a('Profile', ['user/view', 'id' => $id], ['class' => 'profile-link']) ?>

第一個(gè)參數(shù)是超鏈接的標(biāo)題。它不會(huì)被轉(zhuǎn)碼，所以如果是用戶(hù)輸入數(shù)據(jù)， 你需要使用?Html::encode()?方法進(jìn)行轉(zhuǎn)碼。第二個(gè)參數(shù)是?<a標(biāo)簽的?target="_blank" href?屬性的值。 關(guān)于該參數(shù)能夠接受的更詳細(xì)的數(shù)據(jù)值，請(qǐng)參閱?Url::to()。第三個(gè)參數(shù)是標(biāo)簽的屬性數(shù)組。

在需要的時(shí)候，你可以用如下代碼生成?mailto?鏈接：

<?= Html::mailto('Contact us', 'admin@example.com') ?>

圖片

為了生成圖片標(biāo)簽，你可以如下做：

<?= Html::img('@web/images/logo.png', ['alt' => 'My logo']) ?>

generates

<img src="/docs/guide/2.0/http://example.com/images/logo.png" alt="My logo" />

除了?aliases?之外，第一個(gè)參數(shù)可以接受 路由，查詢(xún)，URLs。 同?Url::to()?一樣。

列表

無(wú)序列表可以如下生成：

<?= Html::ul($posts, ['item' => function($item, $index) {
    return Html::tag(
        'li',
        $this->render('post', ['item' => $item]),
        ['class' => 'post']
    );
}]) ?>