图标库 - 纯七博客

功能

图标库（ICO / SVG）

图标库把图标当作「媒体资源」集中管理：后台上传 ICO / SVG、网格预览与灯箱查看、一键复制图片地址或短代码，并可在文章、页面与可视化构建器中随处引用。SVG 上传即自动净化，安全无忧。

2.1 入口与适用场景

启用 Qi-theme 后，图标库入口位于后台：

媒体 → 图标库：打开图标管理页，进行上传、预览、复制与删除。
权限：具备「上传文件」能力的角色（管理员、编辑、作者）均可管理图标。

适合以下场景：

统一管理一套品牌图标（SVG 矢量 / ICO 站点图标），避免把图片散落在媒体库各处。
在文章正文、页面、「自定义 HTML」区块、构建器富文本中插入图标。
为构建器的 iconbox / features / iconlist / card 等区块提供图标。

2.2 上传图标

后台进入 媒体 → 图标库。
在「上传新图标」卡片点击「选择文件」，选择本地 .ico 或 .svg 文件。
点击「上传图标」，文件即加入图标库。

存储位置：图标库上传的文件统一存放在 wp-content/uploads/icons/ 目录，与常规媒体分离，便于集中管理。

支持格式：仅接受 .ico（image/x-icon）与 .svg（image/svg+xml）。其它格式会被 WordPress 拒绝。

2.3 SVG 安全净化（自动）

SVG 本质上是 XML，可能被植入脚本或外部实体攻击。Qi-theme 在上传时自动净化每一个 SVG，你无需任何额外操作：

移除 <!DOCTYPE> 与实体定义（<!ENTITY>），防御 XXE 外部实体注入。
移除 <script> 与 <foreignObject> 等危险节点。
移除所有 on* 事件属性（如 onload、onclick）。
清除 href / xlink:href / src 中的 javascript:、vbscript:、非图片的 data: 协议。
其余 SVG 标签与属性原样保留，保证视觉效果一致。

两层保障：净化优先使用 PHP DOMDocument（无网络加载、禁用外部实体），当环境缺失或 SVG 结构异常时自动回退到正则兜底，确保危险内容无论如何都会被剥离。

2.4 管理图标

图标库以网格卡片展示所有图标，每张卡片提供：

缩略图与角标：卡片上显示图标与「ICO / SVG」类型角标。
灯箱预览：点击缩略图放大查看原比例（ICO / SVG 按原始尺寸呈现）。
复制图片地址：复制该图标的直链（如 https://你的站点/wp-content/uploads/icons/xxx.svg），可用于区块图标字段、<img> 或 CSS。
复制短代码：复制形如 [hualin_icon id="123"] 的短代码，粘贴到文章/页面正文或构建器富文本即可渲染图标。
删除：从图标库移除该图标（带二次确认，操作不可恢复）。

删除影响：删除图标后，引用该图标「图片地址」的区块仍保留地址字符串，但图片会 404 不显示；引用「短代码」处也会因 id 失效而不再渲染。删除前请确认不再被页面引用。

2.5 用短代码插入图标

在文章、页面正文或构建器富文本中，使用 [hualin_icon] 短代码即可插入图标库中的图标，最常用写法：

[hualin_icon id="123"]

可用参数如下：

参数	默认值	说明
`id`	必填	图标的媒体附件 ID（在图标库点击「复制短代码」即可获得）。
`size`	`48`	图标显示尺寸（像素），同时作用于宽高。
`align`	空	对齐方式：`left` / `center` / `right`。
`class`	空	附加到图标的 CSS 类名，便于自定义样式。
`alt`	空	图片的 alt 替代文本，利于可访问性与 SEO。
`mode`	`img`	渲染模式：`img` 以 `<img>` 输出；`inline` 内联输出 SVG（可被 CSS 着色）。

img 模式（默认）

以普通图片输出，固定尺寸、加载即用，适合大多数场景：

[hualin_icon id="123" size="64" align="left" alt="安全图标"]

inline 模式（可着色）

将 SVG 直接内联到页面，可通过 CSS 的 currentColor 或 fill 随文字颜色 / 主题色变化，适合需要换色的场景：

[hualin_icon id="123" mode="inline" class="my-icon"]
/* 自定义着色（放入子主题或自定义 CSS） */
.my-icon path, .my-icon circle { fill: currentColor; }
.section-accent .my-icon { color: #7c5cff; }

小提示：inline 模式会缓存一份净化后的 SVG，性能与安全性都兼顾；若修改了源 SVG 文件，颜色等仍由前端 CSS 控制，无需重新上传。

2.6 在可视化构建器中使用图标库

构建器内置「图标库」能力，无需离开编辑页即可插入图标，有两种方式：

方式一：区块图标字段填「图标库图片地址」

iconbox、features、iconlist、card 等区块的图标字段，支持直接填入图标库的图片地址（也可填 Emoji 或字符）。填入后，前端与构建器预览会以图标渲染：

在图标库卡片点击「复制图片地址」。
回到构建器，选中对应区块，把地址粘贴进「图标」字段。
保存后在预览中即可看到图标生效。

方式二：编辑页「📚 图标库」按钮

构建器编辑页的工具栏带有「📚 图标库」按钮。点击后弹出图标选择窗：

将光标聚焦到任意图标字段或文本输入框。
点击「📚 图标库」按钮，弹出图标网格。
在目标图标上点「插入地址」或「插入短代码」，内容即插入到当前聚焦的输入框。

两种插入的区别：「插入地址」填入图标直链，区块图标字段推荐用此项；「插入短代码」填入 [hualin_icon ...]，适合富文本 / 自定义 HTML 区块，渲染逻辑与正文一致。

2.7 常见问题

图标库为空？：请先到「媒体 → 图标库」上传至少一个 ICO / SVG；构建器弹窗为空时也会提示先去上传。
上传被拒绝？：确认文件扩展名为 .ico 或 .svg，且文件真实类型为对应 MIME；若服务器禁用相应上传类型，需检查 upload_mimes 与文件真实类型校验。
图标不显示（404）？：多为引用了已删除的图标（地址或短代码 id 失效），重新上传并在原处更新引用即可。
inline 模式图标不变色？：检查 SVG 内部是否用固定 fill 写死了颜色；可通过外层 CSS 覆盖 fill，或改用 currentColor 让它跟随文字色。
SVG 上传后样式变了？：净化仅移除危险节点/属性，不会改正常视觉；若发现异常，多为原 SVG 含事件属性或脚本被清理所致，属正常安全行为。