Iconify Utils

Iconify Utils 是一组可复用的函数，供各类 Iconify 图标组件及相关包使用：

• 解析 IconifyJSON 格式的 Iconify 图标集。
• 将 IconifyIcon 格式（可从图标集中提取）的图标导出为 SVG。
• SVG 基础解析器。
• 解析并验证图标名称。
• 解析并验证基础颜色。
• 解析表情符号序列，生成用于在文本中查找表情符号的正则表达式。

该库采用 TypeScript 编写，提供适用于现代开发的 ES 模块，以及适用于旧版脚本的 CommonJS 模块。

安装

要安装该库，请运行：

npm install @iconify/utils --save

示例

下方每个函数的文档均包含代码示例。

此外，还有几个针对特定常用任务的更完整代码示例，可帮助您了解应使用哪些函数。

函数

图标集以 IconifyJSON 格式存储。用于处理图标集的函数：

• validateIconSet(data) 验证图标集。如果你不确定源是否为有效的图标集，请运行此函数进行验证。它会将数据转换为正确的 IconifyJSON 格式，并尝试修复错误。
• quicklyValidateIconSet(data) 与上述函数类似，但仅执行基本验证。如果你不关心元数据是否无效、不想尝试修复图标集中的错误，或者希望减小打包体积，请使用此函数。
• getIcons(data, icons) 从图标集中提取少量图标。可用于将图标集缩减为项目中实际使用的少数图标。
• getIconData(data, icon) 从图标集中提取单个图标的数据。
• minifyIconSet(data) 压缩图标集，移除冗余数据。用于减小文件大小。
• expandIconSet(data) 与上述函数功能相反。
• convertIconSetInfo(data) 将旧版图标集格式转换为正确的 IconifyInfo 类型。
• parseIconSet(data, callback) 解析图标集，为每个图标调用 callback 函数。可用于从图标集中提取所有图标。解析前请先验证图标集。
• parseIconSetAsync(data, callback) 是 parseIconSet() 的异步版本，该函数及其回调均为异步。

用于处理表示单个图标的 IconifyIcon 格式的函数：

• mergeIconData(icon, alias) 合并图标及其别名的数据。供从图标集中提取图标数据的函数使用。
• defaultIconProps 包含 IconifyIcon 对象可选属性的默认值。
• convertParsedSVG(data) 可用于将 SVG 字符串转换为 IconifyIcon 对象。

渲染图标时，可对其应用自定义设置。例如，更改尺寸、旋转或翻转图标。它们由 IconCustomisations 类型表示。用于处理自定义设置的函数：

• mergeCustomisations(defaultIconCustomisations, custom) 函数将对象转换为 FullIconCustomisations 类型。它还会验证类型，因此可用于清理用户输入。
• defaultIconCustomisations 从 lib/customisations/defaults 导出，包含默认的自定义设置。
• toBoolean(name, value, defaultValue) 将各种字符串转换为布尔值。供图标组件使用，以清理可能为布尔值或字符串的参数。
• rotateFromString(value) 将各种图标旋转表示法（如 "90deg" 或 "25%"）转换为数字。
• flipFromString(customisations, value) 将翻转字符串（如 flip="horizontal,vertical"）应用到自定义设置中。

用于渲染图标的函数：

• iconToSVG(icon, customisations) 生成渲染 SVG 所需的数据。它不会生成完整的 SVG，仅生成内容以及需添加到 SVG 元素的属性列表，便于在自定义组件中使用。
• iconToHTML(body, attributes) 将 iconToSVG() 的结果转换为 SVG 字符串。
• calculateSize(size, ratio) 计算图标尺寸。在使用 iconToSVG() 构建图标时使用。
• replaceIDs(content) 将 SVG 中的 ID 替换为唯一 ID。遮罩等元素会使用 ID，且它们必须唯一，因此在同一页面上显示多个使用相同 ID 的图标会导致混乱。此函数可避免该问题。
• getIconCSS(icon) 生成将图标用作背景图像或遮罩图像的样式表。
• getIconsCSS(iconSet, names) 生成将同一图标集中的多个图标用作背景图像或遮罩图像的样式表。
• getIconContentCSS(icon, options) 生成将图标用作伪元素内容的样式表。
• getIconsContentCSS(iconSet, names, options) 生成将同一图标集中的多个图标用作伪元素内容的样式表。
• cleanUpInnerHTML() 允许在严格环境中使用 innerHTML 将 SVG 分配给现有的 DOM 元素。

用于解析图标的函数：

• parseSVGContent(content) 解析 SVG 字符串，提取 <svg> 属性和主体内容。
• buildParsedSVG(data) 将 parseSVGContent(content) 的结果转换为与 iconToSVG() 生成的相同数据。
• convertParsedSVG(data) 将 parseSVGContent(content) 的结果转换为 IconifyIcon 对象。
• splitSVGDefs(content) 将图标内容拆分为定义部分和其他数据。供 wrapSVGContent() 使用。
• mergeDefsAndContent(defs, content) 将定义和内容重新合并为一个字符串。
• wrapSVGContent(body, start, end) 包装图标内容，但不包装定义部分。供各种函数将内容包装在组中使用。
• getSVGViewBox(value) 解析并验证 viewBox 属性，成功时返回数字数组，失败时返回 undefined。

用于处理图标名称的函数：

• matchIconName 常量是一个正则表达式，用于测试图标名称的各个部分。
• stringToIcon(value) 将图标名称（如 "mdi-light:home"）转换为 IconifyIconName 对象，并可选择性地对其进行验证。
• validateIconName(icon) 验证 IconifyIconName 对象。

用于处理颜色的函数：

• stringToColor(value) 将字符串转换为 Color 对象，出错时返回 null。可用于验证用户输入。支持颜色关键字、十六进制颜色、RGB、HSL、LAB 和 LCH 颜色。不支持变量，因为此函数旨在解析 SVG，而 SVG 不应引用任何外部变量。
• compareColors(color1, color2) 比较颜色。必要时还会将 RGB 转换为 HSL。
• colorToString(color) 将 Color 对象转换为字符串。与 stringToColor() 结合使用，可用于验证和清理用户输入。

高级用法

Iconify Utils 仅能对 IconifyJSON 和 IconifyIcon 数据进行基础解析。它并非用于处理更复杂的内容。

对于更复杂的需求，例如导入图标、验证图标代码、更改调色板、清理以及导出为各种格式，请参阅 Iconify Tools 包。