blade-ui-kit/blade-icons

一个用于在Laravel Blade视图中轻松使用图标的包。

维护者

详细信息

github.com/blade-ui-kit/blade-icons

主页

源代码

问题

资助包维护！
driesvints
Paypal

安装次数: 12,018,916

依赖者: 171

建议者: 2

安全性: 0

星标: 2,152

关注者: 29

分支: 138

开放性问题: 2

1.7.1 2024-08-14 14:25 UTC

Requires

Requires (Dev)

MIT 8f787baf09d88cdfd6ec4dbaba11ebfa885f0595

laraveliconssvgblade

This package is auto-updated.

Last update: 2024-09-14 14:45:15 UTC

README

Blade Icons

Tests Coding Standards Latest Stable Version Total Downloads

一个用于在Laravel Blade视图中轻松使用SVG图标的包。最初由 Adam Wathan 开发的 "Blade SVG"。

转换...

<!-- camera.svg -->
<svg fill="none" viewBox="0 0 24 24" stroke="currentColor" class="w-6 h-6">
  <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3 9a2 2 0 012-2h.93a2 2 0 001.664-.89l.812-1.22A2 2 0 0110.07 4h3.86a2 2 0 011.664.89l.812 1.22A2 2 0 0018.07 7H19a2 2 0 012 2v9a2 2 0 01-2 2H5a2 2 0 01-2-2V9z"/>
  <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 13a3 3 0 11-6 0 3 3 0 016 0z"/>
</svg>

为...

<x-icon-camera class="w-6 h-6" />

或者为...

@svg('camera', 'w-6 h-6')

寻找特定的图标？试试我们的图标搜索： https://blade-ui-kit.com/blade-icons#search

任何赞助以 资助开发 都非常感激 ❤️

图标包

Blade Icons 是一个基础包，让您轻松在应用程序中使用SVG图标。此外，还有一些第三方图标集包。感谢社区为此作出贡献！

我们不接受自行构建新图标包的请求，但您可以 开始构建自己的。

要求

  • PHP 7.4 或更高版本
  • Laravel 8.0 或更高版本

安装

使用 composer 安装包

composer require blade-ui-kit/blade-icons

然后，发布配置并取消注释 默认 图标集

php artisan vendor:publish --tag=blade-icons

请确保为该图标集定义的路径存在。默认情况下是 resources/svg。您的 SVG 图标需要放置在这个目录中。

升级

在升级库时，请参阅 升级指南。

缓存

当使用 Blade Icons，尤其是第三方图标集时，您通常会处理大量的图标集。这可能会极大地减慢您的应用程序速度，尤其是在使用 Blade 组件 时。为了解决这个问题，Blade Icons 内置了缓存支持。要启用图标缓存，可以运行以下命令

php artisan icons:cache

这将在 bootstrap/cache 中创建一个类似于 packages.php 缓存文件的 blade-icons.php 文件。它将包含所有已知集合和图标及其路径位置清单。

缓存图标意味着您将无法添加额外的图标，更改图标集的路径或安装/删除图标包。要这样做，请确保首先清除图标缓存，并在更改这些设置后刷新缓存。

php artisan icons:clear

将 icons:cache 命令作为部署流程的一部分并始终在生产中缓存图标是个好主意。

或者，您可以选择完全禁用 Blade 组件。

此外，在添加新图标、重命名图标路径中的目录时，在刷新页面之前清除视图总是一个好主意。

php artisan view:clear

配置

定义集合

Blade Icons 支持多个集合。您可以通过在 blade-icons.php 配置文件的 sets 设置中传递键/值组合来定义这些集合

<?php

return [
    'sets' => [
        'default' => [
            'path' => 'resources/svg',
        ],
    ],
];

您可以随意添加任意数量的集合。Blade Icons 为您的应用程序提供了一个 default 集合，您可以根据自己的喜好进行调整。

图标路径

如果您想从应用程序中的不同目录添加图标，例如 resources/images/svg，您可以设置为这样

<?php

return [
    'sets' => [
        'default' => [
            'path' => 'resources/images/svg',
        ],
    ],
];

警告

请始终确保您指向的是现有目录。

多个路径

除了单个路径外，您还可以使用 paths 选项为单个集合定义多个路径

<?php

return [
    'sets' => [
        'default' => [
            'paths' => [
                'resources/images/icon-set',
                'resources/images/other-icon-set',
            ],
        ],
    ],
];

这使您可以从单个集合中分组来自不同路径的图标，其中您可以定义相同的前缀和默认类。

警告

当使用多个路径而不是单个路径时，Blade Icons 将返回当图标名称存在于多个路径时找到的第一个图标。如果您想检索正确的图标，请确保在注册多个路径时使用唯一的图标名称。

文件系统磁盘

如果您在外部文件系统存储上托管图标，可以将图标集的 disk 选项设置为您的 filesystems.php 配置文件中定义的磁盘。例如，您可能将图标存储在 AWS S3 存储桶中，该存储桶在您的 filesystems.php 配置文件中以 s3-icons 作为磁盘密钥设置

<?php

return [
    'sets' => [
        'default' => [
            'path' => '/',
            'disk' => 's3-icons',
        ],
    ],
];

从现在起，我们的默认集合将从此 S3 存储桶中提取图标。请注意，我们已经将路径调整为 /，因为我们将图标存储在这个 S3 存储桶的根目录中。如果您有多个图标集上传到同一磁盘，您可以相应地设置路径

<?php

return [
    'sets' => [
        'heroicons' => [
            'path' => 'heroicons',
            'disk' => 's3-icons',
            'prefix' => 'heroicon',
        ],
        'zondicons' => [
            'path' => 'zondicons',
            'disk' => 's3-icons',
            'prefix' => 'zondicon',
        ],
    ],
];

回退图标

如果您想在找不到图标时提供一个回退图标，您可以在特定集合上定义 fallback 选项

<?php

return [
    'sets' => [
        'default' => [
            'fallback' => 'cake',
        ],
    ],
];

现在，当您尝试解析默认图标集的非现有图标时，它将返回渲染的“蛋糕”图标。

您还可以提供一个全局回退图标。当找不到图标且集合没有自己的回退图标定义时，将使用此图标。它可以引用任何已注册图标集中的任何图标。

<?php

return [
    'fallback' => 'heroicon-cake',
];

注意

在使用回退图标时有一个需要注意的地方，那就是当使用Blade 组件时它们可能不起作用。在这种情况下，Laravel 将抛出一个找不到组件的异常。如果您想使用回退图标，请考虑其他使用方式。

图标前缀

在默认图标集中，icon前缀将被应用到每个图标上，但您可以在blade-icons.php配置文件中调整这一点。

<?php

return [
    'sets' => [
        'default' => [
            'prefix' => 'icon',
        ],
    ],
];

为每个集合定义前缀是必需的，并且每个前缀应该是唯一的。

当使用Blade 指令或助手引用图标时，您可以选择省略前缀以引用default集合中的图标。当引用其他集合的图标时，使用前缀是必需的。

如果默认集合中的一个图标名称与集合的前缀冲突，则首先检索默认集合中的图标。

请注意，最好将图标本身的名字中不要包含前缀。所以，如果您有一个名为icon的前缀，并且您的图标命名为icon-example.svg，您应该将它们重命名为example.svg。否则，您可能会遇到意外的名称解析问题。

同样重要的是要注意，图标前缀不能包含破折号（-），因为这是我们用来将其与图标名称其他部分分开的分隔符。

默认类

您可以选择定义将应用于每个图标的类，通过在blade-icons.php配置文件中填写class设置来实现。

<?php

return [
    'class' => 'icon icon-default',
];

如果您不希望默认应用任何类，请将其留为空字符串。此外，相同的选项在集合中也可用，因此您可以为每个集合设置默认类。

应用类的顺序是<全局类> <集合类> <显式类>。您可以通过传递具有属性的自定义类来始终覆盖此顺序。组件类不能被覆盖。

默认属性

您还可以选择在blade-icons.php配置文件的attributes设置中定义一些属性，这些属性将添加到每个图标中。

<?php

return [
    'attributes' => [
        'width' => 50,
        'height' => 50,
    ],
];

这始终需要是一个关联数组。此外，集合中也有相同的选项，因此您可以为每个集合设置默认属性。

应用类的顺序是默认属性 / 集合属性 / 显式属性，后者覆盖前者。无法覆盖SVG图标上已定义的现有属性。如果您已经为要覆盖的图标定义了属性，请先删除它们。

用法

有几种方法可以将图标插入到您的Blade模板中。我们个人推荐使用Blade组件，但如果您愿意，也可以使用Blade指令。

组件

开始使用集合中的图标最简单的方法是使用Blade组件。

<x-icon-camera/>

可以使用点符号引用子目录中的图标。

<x-icon-solid.camera/>

您还可以向图标组件传递类（默认类也将应用）。

<x-icon-camera class="icon-lg"/>

或任何其他属性

<x-icon-camera class="icon-lg" id="settings-icon" style="color: #555" data-baz/>

注意

使用Blade组件，即使在引用默认集合中的图标时，也始终需要使用前缀。

延迟图标

当您在页面上许多地方使用相同的图标时，DOM元素的数量可能会急剧增加。为了解决这个问题，您可以将defer属性添加到组件中。

<x-icon-camera defer />

这将把图标推送到“bladeicons”堆栈，您应该在页面的底部加载此堆栈。

   ...
    <svg hidden class="hidden">
        @stack('bladeicons')
    </svg>
</body>
</html>

警告

仅使用<x-icon>组件可以延迟图标。此功能与@svg Blade指令或svg()助手函数不兼容。

在JavaScript中使用延迟图标

您可以通过提供自定义的defer值作为标识符来重用blade中的图标，在您的JavaScript渲染视图中

<x-icon-camera defer="my-custom-hash" />

然后，在您的JavaScript中，创建一个带有use和href="#icon-{your-hash}"属性的svg元素。

function icon() {
    return <svg><use href="#icon-my-custom-hash"></use></svg>
}

默认组件

如果您不想使用上面的组件语法，您也可以使用Blade Icons附带的默认Icon组件。只需通过$name属性传递图标名称即可

<x-icon name="camera"/>

如果您想为该组件使用不同的名称，您可以在blade-icons.php配置文件中自定义components.default选项

<?php

return [
    'components' => [
        'default' => 'svg',
    ],
];

然后按照以下方式引用默认图标

<x-svg name="camera"/>

如果您想完全禁用此默认组件，可以将它的名称设置为null

<?php

return [
    'components' => [
        'default' => null,
    ],
];

禁用组件

尽管它们默认启用，但如果您根本不希望使用组件，您可以选择通过将blade-icons.php配置文件中的components.disabled设置设置为true来完全禁用它们

<?php

return [
    'components' => [
        'disabled' => true,
    ],
];

当您只使用指令或辅助函数时，这样做是有意义的，并且可以提高整体性能。

指令

如果您不喜欢组件，您可以使用Blade指令。如果您在配置中定义了默认的icon类，并且想使用icon-lg类渲染一个camera图标，可以这样做

@svg('camera', 'icon-lg')

任何附加属性都可以作为第三个数组参数传递，并且它们将被渲染在svg元素上

@svg('camera', 'icon-lg', ['id' => 'settings-icon'])

如果没有要定义的类，您也可以将这些属性作为第二个参数传递

@svg('camera', ['id' => 'settings-icon'])

如果您想覆盖默认的类，请将类作为属性传递

@svg('camera', ['class' => 'icon-lg'])

也支持没有键的属性

@svg('camera', ['data-foo'])

辅助函数

如果您想使用，可以使用svg辅助函数来暴露用于设置SVG属性的流畅语法

{{ svg('camera')->id('settings-icon')->dataFoo('bar')->dataBaz() }}

可访问性

如果图标应该具有语义意义，可以使用title属性添加文本替代。请参考此文档的用法部分了解如何添加属性。

对于几乎所有用例，您的图标都将扮演图像的角色。这意味着您需要决定图标是否有任何语义意义，或者其语义意义是什么，您可以使用WCAG alt文本决策树。

如果图标具有语义意义，使用title属性将应用于SVG元素以下功能

  • <title>的子元素具有包含传递值的唯一ID
  • 包含传递值的title属性
  • role="img"
  • aria-labelledby用于引用标题元素的唯一ID

示例用法

<x-icon-camera title="camera" />

@svg('camera', ['title' => 'camera'])

示例结果

<svg 
	 title="Camera" 
	 role="img" 
	 xmlns="http://www.w3.org/2000/svg"
	 viewBox="0 0 448 512"
>
	<title>
		Camera
	</title>
	<path fill="currentColor" d="M438.6 278.6c12.5-12.5 12.5-32.8 0-45.3l-160-160c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3L338.8 224 32 224c-17.7 0-32 14.3-32 32s14.3 32 32 32l306.7 0L233.4 393.4c-12.5 12.5-12.5 32.8 0 45.3s32.8 12.5 45.3 0l160-160z"></path>
</svg>

如果图标没有语义意义，您可能希望隐藏图标以减少整个文档的杂乱。您可以通过在图标中添加aria-hidden="true"来实现这一点。

构建软件包

如果您对构建自己的第三方软件包以集成图标集感兴趣，这很容易做到。我们为您创建了一个模板仓库，以供您开始使用。您可以在其readme中找到入门说明。

如果您想了解如何创建软件包，我们可以推荐这两门优秀的课程

请确保从您包的服务提供者的 register 方法中加载您的 SVG 文件。提供 SVG 文件的路径，并提供您自己独特的集合名称和组件前缀。

use BladeUI\Icons\Factory;

public function register(): void
{
    $this->callAfterResolving(Factory::class, function (Factory $factory) {
        $factory->add('heroicons', [
            'path' => __DIR__.'/../resources/svg',
            'prefix' => 'heroicon',
        ]);
    });
}

现在您可以使用组件、指令或助手引用这些图标。

<x-heroicon-o-bell/>

@svg('heroicon-o-bell')

{{ svg('heroicon-o-bell') }}

别忘了在您的包的 composer.json 中将 blade-ui-kit/blade-icons 添加为依赖项。

生成图标

Blade Icons 还提供了一种简单的方法来为您的包生成图标。通过定义一个包含预定义源路径和目标路径的配置文件，您可以轻松更新您的图标。

首先，在图标包的 config 目录中创建一个 generation.php 配置文件。接下来，您可以定义一个数组来指定您要生成的每个图标集合。以下是这个文件的完整版本，其中包含每个选项的解释。只需提供 source 和 destination 选项即可。

<?php

use Symfony\Component\Finder\SplFileInfo;

return [
    [
        // Define a source directory for the sets like a node_modules/ or vendor/ directory...
        'source' => __DIR__.'/../node_modules/heroicons/outline',

        // Define a destination directory for your icons. The below is a good default...
        'destination' => __DIR__.'/../resources/svg',

        // Strip an optional prefix from each source icon name...
        'input-prefix' => 'o-',

        // Set an optional prefix to applied to each destination icon name...
        'output-prefix' => 'o-',

        // Strip an optional suffix from each source icon name...
        'input-suffix' => '-o',

        // Set an optional suffix to applied to each destination icon name...
        'output-suffix' => '-o',

        // Enable "safe" mode which will prevent deletion of old icons...
        'safe' => true,

        // Call an optional callback to manipulate the icon with the pathname of the icon,
        // the settings from above and the original icon file instance...
        'after' => static function (string $icon, array $config, SplFileInfo $file) {
            // ...
        },
    ],

    // More icon sets...
];

查看 Heroicons 包的示例 config/generation.php 文件。

配置好配置文件后，您可以从图标包目录的根目录使用以下命令生成图标：

vendor/bin/blade-icons-generate

更新日志

查看本存储库中的所有最新更改的 CHANGELOG。

维护者

Blade Icons 由 Dries Vints 开发和维护。

许可证

Blade Icons 是开源软件，受 MIT 许可证 许可。