README

此库用于操作 JSON 图标集合。

此库适用于 PHP 和 Node.js，两个版本的代码几乎相同。

安装

要安装此库，请运行此命令

composer require iconify/json-tools

此包中包含两个类： Collection 和 SVG

Collection 类

Collection 类表示一个图标集。

要包含它，请使用以下代码

use \Iconify\JSONTools\Collection;

Collection 类能做什么？

• 读取和写入 JSON 集合。
• 添加、删除、列出图标集中的图标。
• 检索图标数据。
• 为 Iconify 图标集创建图标包。

初始化类实例

有两种方式可以创建实例：带有图标集前缀和不带有图标集前缀。

如果您打算从 JSON 文件加载数据，则可以在构造函数中省略图标集前缀，因为 JSON 文件包含图标集前缀。

$collection = new Collection();

$collectionWithPrefix = new Collection('custom-icons');

加载 JSON 数据

有几种函数可以加载 JSON 文件中的图标集

• loadFromFile() - 加载集合。
• loadJSON() - 从字符串或数组加载 JSON 数据。
• loadIconifyCollection() - 从 iconify/json 仓库加载 Iconify 集合。

loadFromFile()

此函数从 JSON 文件加载图标集。

函数参数

• $file - 从中加载数据的文件。
• $defaultPrefix - 如果 JSON 文件没有前缀，则为可选的默认前缀。
• $cacheFile - 解析的图标集的缓存文件。此选项在库的 Node.js 版本中不存在。使用此选项可以加快加载速度。

返回值

• 布尔值 - 成功时为 true，失败时为 false

$collection = new Collection();
if (!$collection->loadFromFile('json/custom-icons.json')) {
    throw new \Exception('Failed to load custom-icons.json');
}

$collection = new Collection();
if (!$collection->loadFromFile('json/custom-icons.json', null, 'cache/custom-icons.php')) {
    throw new \Exception('Failed to load custom-icons.json');
}

loadJSON()

此函数从字符串或数组加载图标集。

函数参数

• $data - JSON 字符串或数组。
• $prefix - 如果 JSON 文件不包含前缀，则为可选前缀。

返回值

• 布尔值 - 成功时为 true，失败时为 false

$collection = new Collection();
// Use this if collection has prefix
if (!$collection->loadJSON($data)) {
    throw new \Exception('Failed to load JSON data');
}

$collection = new Collection();
// Use this if collection is missing prefix
if (!$collection->loadJSON($data, 'custom-icons')) {
    throw new \Exception('Failed to load JSON data');
}

loadIconifyCollection()

此函数从 iconify/json 仓库加载 Iconify 集合。

函数参数

• $name - 图标集的名称。
• $dir - 图标集的可选根目录。如果您想从自定义目录加载 Iconify 图标集而不是从 iconify/json 仓库加载，请使用此选项。

返回值

• 布尔值 - 成功时为 true，失败时为 false

$collection = new Collection();
if (!$collection->loadIconifyCollection('mdi')) {
    throw new \Exception('Failed to load Material Design Icons');
}

缓存图标集

PHP 在每次页面加载时都会加载图标集，因此避免多次解析相同的数据是有意义的。这就是为什么 PHP 版本的库具有缓存函数。

loadFromCache()

此函数从缓存中加载图标集。

函数参数

• $filename - 缓存文件名。
• $time - 原始 JSON 文件的最后修改时间戳（使用 filemtime() 函数检索）。此参数用于在 JSON 文件自上次保存缓存以来已更新时使缓存无效。

返回值

• 布尔值 - 成功时为 true，失败时为 false

$collection = new Collection();
$file = Collection::findIconifyCollection('mdi');
if (!$collection->loadFromCache('cache/mdi.php', filemtime($file))) {
    if (!$collection->loadFromFile($file)) {
        throw new \Exception('Cannot load Material Design Icons');
    }
    $collection->saveCache('cache/mdi.php', filemtime($file));
}

saveCache()

将图标集数据存储在缓存中。

此函数不返回任何内容。

有关可用示例，请参阅上面 loadFromCache() 示例。

获取图标数据

可以使用几个函数从图标集中检索图标数据

• getIconData() - 返回单个图标的完整数据。它可以用于生成 SVG（请参阅下面的 SVG 类文档）。
• getIcons() - 返回图标JSON数据，可用于导入到另一个JSON集合或使用Iconify.addCollection()添加到Iconify。
• scriptify() - 返回JavaScript包文件，可用于在浏览器中使用Iconify加载图标。

getIconData()

此函数返回一个图标的JSON数据。它返回完整的数据，包括可选字段，因此结果可以用于生成SVG。

函数参数

• $name - 图标名称。

返回值

• 数组 - 图标数据

$data = $collection->getIconData('arrow-left');
$svg = new SVG($data);
echo $svg->getSVG();

getIcons()

此函数返回选定图标的JSON数据。如果没有使用参数，它将返回整个图标集的JSON数据。

参数

• $icons - 图标名称数组。

$data = $collection->getIcons(['arrow-left', 'arrow-right', 'home']);
file_put_contents('bundle.json', json_encode($data));

此函数还可以用于复制集合

$data = $collection->getIcons();
$newCollection = new Collection();
$newCollection->loadJSON($data);

使用不带参数的$collection->getIcons()与访问$collection->items数组相同。

scriptify()

这与getIcons()类似，但它生成JavaScript文件而不是JSON数据，参数作为一个数组传递。

函数参数

• $options - 选项数组。

返回值

• 字符串 - 您可以与您的脚本捆绑的JavaScript代码。

选项数组键

• icons - 要检索的图标数组。如果没有设置或为null，将检索所有图标。
• optimize - 布尔值。如果设置为true，则JSON数据将优化以减小输出大小。
• pretty - 布尔值。如果设置为true，则JSON数据将包含使输出易于阅读的空格。
• callback - 字符串。JavaScript回调，用于包装JSON数据。默认值是Iconify.addCollection。

创建包含一个集合中选定图标的捆绑代码（对于不同集合重复相同代码以创建网站使用的所有图标的捆绑）

$collection = new Collection();
if (!$collection->loadIconifyCollection('mdi')) {
    throw new \Exception('Cannot load Material Design Icons');
}
$code = $collection->scriptify([
    'icons' => ['account', 'account-alert', 'home', 'book-open'],
    'pretty' => false,
    'optimize' => true
]);
file_put_contents('bundle-mdi.js', $code);

添加/删除图标

addIcon()

此函数将新图标添加到图标集。

函数参数

• $name - 图标名称。
• $data - 图标数据。

返回值

• 布尔值 - 成功时为true，失败时为false。如果图标缺少'body'属性或图标集没有前缀，则可能失败。

$collection = new Collection('custom-icons');
$collection->addIcon('arrow', [
    'body' => '<path d="" />',
    'width' => 24,
    'height' => 24
]);

addAlias()

此函数为现有图标添加别名。

函数参数

• $name - 别名名称。
• $parent - 父图标名称。
• $data - 可选数据，用于覆盖父图标的默认数据（如旋转或翻转）。

返回值

• 布尔值 - 成功时为true，失败时为false。如果父图标缺失，则可能失败。

$collection = new Collection('custom-icons');
$collection->addIcon('arrow-left', [
    'body' => '<path d="" />',
    'width' => 24,
    'height' => 24
]);
$collection->addAlias('arrow-right', 'arrow-left', [
    'hFlip' => true
]);
$collection->addAlias('arrow-right-alias', 'arrow-right');

setDefaultIconValue()

设置所有图标的默认值。

函数参数

• $key - 属性名称。
• $value - 默认值。

$collection->setDefaultIconValue('height', 24);

removeIcon()

从图标集中删除图标或别名。

函数参数

• $name - 图标名称。
• $checkAliases - 如果为true，则图标集将检查使用删除的图标作为父图标的别名，并将这些别名也删除。如果确定没有别名引用此图标，则设置为false，否则设置为true。

$collection = new Collection();
$collection->loadIconifyCollection('fa-solid');
$collection->removeIcon('home');

iconExists()

检查图标或别名是否存在。

函数参数

• $name - 图标名称。

返回值

• 布尔值 - true或false

if (!$collection->iconExists('home')) {
    throw new \Exception('Missing "home" icon!');
}

listIcons()

列出图标集中的所有图标。

函数参数

• $includeAliases - 设置为true以将别名包含在结果中。

返回值

• 数组 - 图标列表

$collection = new Collection();
$collection->loadIconifyCollection('vaadin');
echo 'Available icons in vaadin collection: ', implode(', ', $collection->listIcons(true)), "\n";

其他函数

items

这是一个属性，而不是函数。您可以使用它来访问原始JSON数据。值与使用不带参数的getIcons()相同，但是编辑getIcons()的结果不会影响集合数据，因为它复制了数组。

编辑$collection->items数组将更改集合数据。

prefix()

返回图标集前缀，如果图标集没有前缀，则返回false。

返回值

• 字符串|布尔值 - 前缀，错误时返回false。

$prefix = $collection->prefix();

findIconifyCollection()

此函数从iconify/json存储库中定位Iconify图标集。

函数参数

• $name - 图标集的前缀。
• $dir - 可选的根目录，用于存储 Iconify 图标集。如果您想从自定义目录加载 Iconify 图标集，而不是从 iconify/json 存储库中加载，请使用此选项。

返回值

• string - 文件的位置。

echo 'fa-solid.json can be found at ', Collection::findIconifyCollection('fa-solid'), "\n";

optimize()

Optimize 是一个静态函数，用于优化 JSON 数据。它通过引用修改第一个参数中传递的数组。

函数参数

• $data - 要优化的 JSON 数据，通过引用传递。
• $props - 可选的属性数组，用于优化。如果没有设置，将使用默认的属性列表。

$data = $collection->getIcons();
Collection::optimize($data);

deOptimize()

此函数是前面函数的相反。它将优化的 JSON 数据转换为完整的 JSON 数据，使得检索每个图标的详细信息变得容易。

函数参数

• $data - 要反优化的 JSON 数组。

$data = json_decode(file_get_contents('ant-design.json'), true);
Collection::deOptimize($data);

SVG 类

SVG 类生成图标的代码。

要包含它，请使用以下代码

use \Iconify\JSONTools\SVG;

初始化类实例

$svg = new SVG($data);

获取 SVG 图标

SVG 类有一个函数：getSVG()。它返回作为字符串的 SVG。

use \Iconify\JSONTools\Collection;
use \Iconify\JSONTools\SVG;

$collection = new Collection();
$collection->loadIconifyCollection('mdi');
$svg = new SVG($collection->getIconData('home'));
echo $svg->getSVG();

getSVG() 有一个参数：自定义属性数组。可能的数组键

• inline - 如果为 true 或 "true" 或 "1"（字符串或布尔值），则代码将包含 vertical-align 样式，使其表现得像字型。参见 inline vs block 文章。
• width，height - 图标的尺寸。如果只设置了一个属性，另一个属性将使用图标的宽高比设置。值可以是字符串（例如 "1em"，"24px" 或数字）。如果值为 "auto"，则使用图标的原始尺寸。如果宽度和高度都没有设置，则高度默认为 "1em"。
• hFlip，vFlip - 如果为 true 或 "true" 或 "1"（字符串或布尔值），则图标将水平翻转和/或垂直翻转。
• flip - "hFlip" 和 "vFlip" 的替代方案，字符串。值可以是 "horizontal"，"vertical" 或 "horizontal,vertical"。
• rotate - 旋转。值可以是度数 "90deg"（只有 90、180 和 270 度的旋转可用），百分比 "25%"（25%、50% 和 75% 是 90deg、180deg 和 270deg 的别名）或数字 1-3（1 - 90deg，2 - 180deg，3 - 270deg）。
• align - 对齐。如果您设置了自定义宽度和高度，这将很有用。与其他图像不同，SVG 在缩放时保留纵横比（除非另有说明）。值是逗号或空格分隔的字符串，可能的字符串（例如："left,top,crop"）。
  • left，right，center - 水平对齐
  • top，middle，bottom - 垂直对齐
  • crop - 裁剪超出边界的部分
  • meet - 缩放图标以适应整个图标（与裁剪相反）
• color - 用于替换 currentColor 的自定义颜色字符串。当将图标用作背景图像时，这很有用，因为背景图像不能使用 currentColor。
• box - 如果为 true 或 "true" 或 "1"（字符串或布尔值），则图标将包含与其视口匹配的额外矩形。当将图标导出到编辑器时，这使得图标更容易缩放或放置在草图中的位置很有用，因为编辑器通常会忽略 viewBox。

$svg->getSVG([
    'height' => '24px'
]);
$svg->getSVG([
    'height' => '24px',
    'width' => '24px',
    'align' => 'center,middle,meet',
    'color' => '#ff8000',
    'rotate' => '90deg', // same as "'rotate' =>  1" or "'rotate' => '25%'"
    'flip' => 'horizontal', // same as "'hFlip' => true"
    'box' => true
]);
$svg->getSVG([
    'height' => 'auto' // height and width will be set from viewBox attribute, using original icon's dimensions
]);

许可证

该库以 MIT 许可证发布。

© 2018 - 2020 Vjacheslav Trushkin