README

Raw SVG symbols in Yii2

在您的网站上嵌入像 Font Awesome 这样的图标，最好的方法可能是使用裸 SVG 作为 SVG 符号。图标的 SVG 代码嵌入在页面中。因此，无需下载额外的字体文件，也不需要在页面加载时运行 JavaScript，浏览器将以尽可能快的速度渲染图标。

然而，这需要更多的编码。直到现在；因为现在有了 yii2-icon。这为 Yii 2.0 提供了一个辅助类，可以减轻基于裸 SVG 符号的图标负担。

yii2-icon 的演示在此。 yii2-icon 的 GitHub 页面在此。

安装

使用 Composer 以常规方式安装 yii2-icon。将以下内容添加到您的 composer.json 文件的 require 部分

"sjaakp/yii2-icon": "*"

或者运行

composer require sjaakp/yii2-icon

您可以手动通过下载 ZIP 格式的源代码来安装 yii2-icon。

设置

为了使 yii2-icon 正常工作，您的网站上还需要安装一些图标集合。在许多情况下，这将通过 npm 安装，其他集合（特别是 FontAwesome Free）通过 Composer 安装。有关详细信息，请参阅图标提供者的网站。

在任何情况下，必须定义一个名为 'icons' 的应用程序参数。该参数应描述图标文件的位置。值可以是，最好是 Yii2 别名。

例如，对于通过 composer 安装的 FontAwesome Free，这将如下所示

'@vendor/fortawesome/font-awesome/svgs/{family}/{name}.svg'

{family} 将被替换为图标家族（如 'regular'、'solid' 或 'thin'）。
{name} 将被替换为图标名称（如 'bicycle'、'chess-queen' 或 'arrow-down'）。
{phosphor} 将被替换为符合 Phosphor Icons 期望的图标家族和图标名称的组合。

图标家族和名称可以在图标提供者的网站上找到。

另一个例子，对于通过 npm 安装的 FontAwesome Pro，应用程序参数 'icons' 应该是

'@app/node_modules/@fortawesome/fontawesome-pro/svgs/{family}/{name}.svg'

设置应用程序参数的首选方法是将它添加到主站点配置的 'params' 部分（通常是 web.php 或配置目录中的 config/main.php）。'params' 部分可能看起来像这样

'params' => [
    'adminEmail' => 'info@example.com',
    'supportEmail' => 'support@example.com',
    'icons'  => '@vendor/fortawesome/font-awesome/svgs/{family}/{name}.svg',
    // ... probably more parameters ...
],

如果未设置应用程序参数 'icons'，yii2-icon 将引发错误。

接下来，应修改站点的主体布局视图（可能是 'views/layouts/main.php'）。在 body 部分的顶部，yii2-icon 的类 Icon 需要渲染 SVG 符号。主要布局视图的开始部分应该看起来像这样

<?php

use ...
use sjaakp\icon\Icon;

//...
?>
...
<html ...>
<head> ... </head>
<body class=" ... ">
    <?php $this->beginBody() ?>
    <?= Icon::symbols($this) ?>

    // ...

使用 yii2-icon

如果一切设置正确，您可以在任何视图中渲染图标。例如，要渲染 regular 家族的图标，只需使用类似以下内容

<?= Icon::regular('bicycle') ?>

对于其他家族也是如此

<?= Icon::solid('heart') ?>
<?= Icon::light('bell') ?>

如果图标集合没有家族，例如 Bootstrap Icons，则可以使用以下方式渲染图标

<?= Icon::icon('camera') ?>

样式

图标可以使用 HTML 选项进行扩展，如下所示

<?= Icon::regular('bicycle', [ 'class' => 'blue' ]) ?>

默认情况下，yii2-icon 包括 FontAwesome 样式类，即使对于其他字体集合也是如此。这意味着诸如 fa-lg、fa-rotate-90 等类将直接生效。例如

<?= Icon::solid('rotate', [ 'class' => 'fa-spin' ]) ?>

类 Icon

yii2-icon 的所有功能都封装在一个抽象类 sjaakp\icon\Icon 中。它只包含抽象函数

renderIcon($fam, $name, $options = []) - 渲染来自家族 $fam 的名为 $name 的图标。返回 HTML。
symbols($view) - 在视图 $view（最好是一个布局）中渲染符号表。返回 HTML。
reset() - 重置从应用程序参数 'icons' 中获取的 yii2-icon 的状态。在多个图标集合的情况下可能很有用。

所有其他函数调用 都将被转换为对 renderIcon 的调用，其中函数名将是 $fam 的值。因此，像以下这样的函数调用

Icon::regular('bicycle', [ <options> ]);

将被解释为

Icon::renderIcon('regular', 'bicycle', [ <options> ]);

图标的渲染方式

假设我们有一个包含 <?= Icon::solid('mug-hot', [ 'class' => 'fa-rotate-90' ]) ?> 的页面。它将被渲染为

<body>
    <svg xmlns="http://www.w3.org/2000/svg"> <!-- invisible symbol table -->
        <symbol ...><path d="..."/></symbol>
        <symbol id="i-solid-mug-hot" viewBox="0 0 512 512"><path d="M400 192H32C14.25 192 ..."/></symbol>
        <symbol ...><path d="..."/></symbol> <!-- more symbols -->
    </svg>

    ...
    <!-- lots of other HTML -->
    ...

    ... <svg class="fa-rotate-90 svg-inline--fa">
            <use href="#i-solid-mug-hot"></use>
        </svg> ...

    ...

</body>

注意

如果符号表之后渲染图标，则主布局文件中的图标可能无法渲染。避免此问题的方法之一是将图标分配给 PHP 变量，如下所示

<?php
/* views/layouts/main.php */

use ...
use sjaakp\icon\Icon;

$iconHouse = Icon::solid('house');

//...
?>
...
<html ...>
<head> ... </head>
<body class=" ... ">
    <?php $this->beginBody() ?>
    <?= Icon::symbols($this) ?>

    // ...

    Render house icon: <?= $iconHouse ?>.

    // ...

高级设置

除了图标 SVG 文件位置的描述之外，应用程序参数 'icons' 的值还可以是具有以下成员的数组

location - 图标 SVG 文件的位置，如前所述。必须提供。
faCss - 可选。Icon 是否注册 Font Awesome 样式 CSS。默认：true。
template - 可选。用于形成图标 HTML id 的家族和名称的模板。默认和示例：'i-{family}-{name}'。
iconClass - 可选。分配给图标的 CSS 类。默认：'svg-inline--fa'。

一些图标资源

（注意：'@node' 是 '@app/node_modules' 的别名。）

sjaakp / yii2-icon

维护者

详细信息