nothingworks/blade-svg

此包已被废弃，不再维护。作者建议使用 blade-ui-kit/blade-icons 包代替。

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

维护者

详细信息

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

主页

源代码

问题

资助包维护！
driesvints
Paypal

安装: 1,374,521

依赖项: 6

建议者: 0

安全: 0

星标: 2,161

关注者: 29

分支: 139

开放问题: 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-23 06:17:16 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

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

缓存图标意味着您将无法添加额外的图标、更改图标集的路径或安装/删除图标包。要执行此操作，请确保首先清除图标缓存，并在您做出这些更改后清除缓存

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 存储桶的根目录中。如果您有多个图标集上传到同一磁盘，您可以相应地设置您的路径

<?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值，在JavaScript渲染的视图中重用blade中的图标。

<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许可证。