图标库扩展

1. 插件用途

图标库扩展用于统一导入、管理、浏览、下载并使用平台图标。插件支持两类图标来源：

Iconify 图标集：通过 Iconify 官方前缀或图标集名称导入，可按分类和样式筛选。
SVG 文件上传：一次上传一个或多个 SVG 文件，作为自定义图标分组使用。

导入的图标会通过平台文件服务保存，并可在平台原有的图标选择器中使用。

2. 进入插件

进入 设置 > 图标库扩展。插件包含两个页签：

Icon sources：导入和管理 Iconify、SVG 图标来源。
Global icon library：查看平台内置图标和已导入图标。

管理图标来源需要具备设置页面的访问权限。

图标来源列表包含分组名称、排序、来源类型、Iconify 前缀、启用状态、同步状态、完整范围进度、备注和操作列。操作列固定在表格右侧。

3. 插件安装后的内置图标

插件安装后会自动创建并加入队列以下三个 Phosphor 图标来源：

分组名称	前缀	样式	排序
Phosphor Regular	`ph`	Regular	1
Phosphor Fill	`ph`	Fill	2
Phosphor Duotone	`ph`	Duotone	3

这三个安装任务会在后台执行。为了避免安装时连续弹出多条消息，它们完成时不会分别显示成功提示；手动创建的导入任务仍会正常提示成功或失败。

4. 导入 Iconify 图标集

在 Icon sources 页签中，点击 Import Iconify collection。

填写以下信息：

Group name：图标在全局图标库和图标选择器中的分组名称，必须唯一。
Iconify prefix or collection name：可填写官方前缀，例如 ph；也可填写图标集名称，例如 Lucide Lab，系统会自动识别对应图标集。
Order：控制该来源在平台内置图标样式页签之后的显示顺序，数值越小越靠前。
Remark：可选，用于记录维护说明。

填写后先点击 Preview。预览只校验和读取图标集信息，不会写入图标。

预览会显示图标集名称、官方 Iconify 前缀、图标集直达链接、已导入数量和剩余数量。Preview 与 Import 会互斥：当前预览有效时，Preview 不可用、Import 可用；修改导入范围后，Import 会再次禁用，必须重新预览。

按分类或样式筛选

部分 Iconify 图标集提供分类、样式或两者。保持为空时导入整个图标集；选择一个或多个值后，只导入对应范围。变更分类或样式后，需要再次点击 Preview 刷新数量。

例如 Phosphor 提供 Thin、Light、Regular、Bold、Fill 和 Duotone 等样式。实际可选分类和样式取决于所选 Iconify 图标集。

开始或续导图标

确认预览结果后，点击 Import，任务会进入后台队列，弹窗关闭后可在来源列表查看状态。

当相同来源和导入范围已经存在时，插件只会导入剩余图标。虽然新任务只处理剩余部分，来源列表始终按完整范围显示进度。例如已导入 500 / 1512 时继续导入，进度会从 500 / 1512 到 1512 / 1512，不会把总数变成剩余的 1012。

当预览显示 Remaining: 0 时，当前范围已经全部导入，不能再创建重复导入任务。

5. 上传自定义 SVG 图标

在 Icon sources 页签中，点击 Upload SVG files。

填写唯一的 Group name，可选填写 Order 和 Remark，然后选择一个或多个 .svg 文件。插件会读取 SVG 内容，并以文件名生成图标条目。点击 Import 后，上传任务进入后台队列。

建议使用清晰、稳定的文件名，因为图标名称会展示在全局图标库中，也可作为搜索关键字。

6. 来源状态、进度和队列操作

Sync status 用于显示来源当前的后台状态：

状态	含义	可执行操作
Waiting	导入任务已经进入队列，尚未开始。	暂停导入或删除来源。
Syncing	后台正在导入图标。	暂停导入或删除来源。
Paused	该来源的导入任务已经暂停。	继续导入或删除来源；暂停时不可编辑，也不可启用或停用。
Partial	已导入一部分图标，当前范围尚未完成。	再次导入剩余范围，或删除来源。
Success	当前范围已全部导入完成。	编辑、启用/停用或删除。
Failed	导入任务因错误而停止。	重试、删除。
Delete queued	删除任务已入队，但尚未被后台任务领取。	取消删除。
Deleting	正在删除图标和文件。	删除已开始，不能取消。

来源进度始终使用完整导入范围。一个续导任务可能只处理剩余图标，但列表仍会显示完整总数。队列异步执行，因此前一个任务运行时，后续任务显示 Waiting 属于正常现象。

暂停和继续导入

来源处于 Waiting 或 Syncing 时，可以点击 Pause imports，暂停该来源的所有待处理导入任务。状态变为 Paused 后，点击 Resume imports 可将已暂停任务重新放回队列。

Paused 状态仍然允许删除来源。为避免队列状态与来源信息不一致，暂停时不能编辑来源，也不能切换启用状态。

重试失败任务

来源显示 Failed 时，操作列会显示 Retry。点击后会按失败任务保存的原始参数重新创建任务，包括 Iconify 前缀、分类、样式或 SVG 文件内容，随后回到 Waiting 并按正常队列继续执行。

删除来源和取消删除

在操作列点击 Delete，然后在确认框中确认。

删除会通过后台任务清理来源及其所有图标资产。后台任务尚未开始前，行状态显示 Delete queued，并提供 Cancel deletion；取消后，来源恢复到删除前的同步状态。任务进入 Deleting 后，删除已开始，不能再取消。

删除前请确认业务菜单、页面或操作中没有继续使用该来源下的图标。

7. 编辑、启用和停用来源

在操作列点击 Edit。

来源类型、来源标识和 Iconify 前缀用于确定来源身份，只能查看。可修改的内容为：

Group name：必须保持唯一。
Order：修改该来源页签的显示顺序。
Remark：可选维护说明。

点击 Disable 可将来源从运行时图标选择器中隐藏，但不会删除已保存图标；点击 Enable 可恢复使用。停用来源不会影响管理页面中对该来源的查看和维护。

8. 查看全局图标库

打开 Global icon library 页签。

最前面的页签为平台内置图标样式：

Outlined style
Filled style
Two-tone style

内置样式页签之后是导入来源的页签，按来源的 Order 数值排序。图标以每行 6 个卡片展示，预览尺寸为 60 px，下方显示图标名称。列表支持分页和每页数量切换。

搜索和下载图标

使用搜索框可在当前页签中按图标名称或图标编码搜索。鼠标移入图标卡片时，卡片会以平台主色高亮，并显示下载按钮。

点击下载图标可将当前显示图标保存为 SVG 文件。平台内置图标和已导入图标都支持下载。

9. 在业务配置中使用图标

插件会替换平台的 IconPicker。在菜单、操作等使用平台原有图标选择器的配置页面中，会自动提供增强版选择器，包含：

按 Outlined、Filled、Two-tone 分组的平台内置图标。
按来源 Order 排序的已启用导入图标分组。
图标搜索功能。
与全局图标库一致的图标名称和预览。

在对应页签选择图标后，按原有方式保存业务配置即可。停用来源会让其导入图标从运行时选择器中隐藏，但不会删除图标资产；重新启用后即可恢复。

选择菜单图标

以菜单为例，进入界面配置模式后，按以下步骤选择图标：

将鼠标移到需要设置的菜单项，点击菜单项的设置按钮，然后选择 Edit。
在编辑弹窗的 Icon 区域点击 Select icon。
在弹出的选择器中切换图标来源页签，或使用搜索框按名称查找图标；点击目标图标即可选中。
点击 Save 保存菜单配置。

选择器前 3 个页签分别为线框风格、实底风格和双色风格，后续页签为已启用的导入图标来源，例如图中的 Phosphor Fill。来源被停用后，其页签不会显示在选择器中。

保存后，所选图标会显示在菜单标题左侧：

10. 推荐操作流程

插件安装后，先检查三个内置 Phosphor 来源，并等待其显示 Success。
导入新的 Iconify 图标集或 SVG 文件时，使用清晰且唯一的分组名称，并设置合适的排序值。
每次导入 Iconify 前先 Preview，特别是在调整分类或样式之后。
通过来源列表观察后台任务。需要暂时停止时暂停来源，准备好后继续导入。
失败任务使用 Retry；删除任务仅在 Delete queued 状态下可以取消。
在全局图标库中先浏览、搜索或下载图标，再在菜单、页面和操作中选用。

11. 常见问题

任务长时间停留在 Waiting，或进度没有变化

导入任务由后台 worker 异步处理。先刷新页面查看最新状态；如果长时间仍为 Waiting，请管理员检查应用服务和任务 worker 是否正常运行。

Iconify 预览无法识别图标集

请确认填写的是官方 Iconify 前缀或准确图标集名称，并确认服务端可以访问 Iconify 服务。可通过预览中的图标集链接核对最终识别到的前缀。

已导入图标没有出现在业务图标选择器中

检查来源是否为 Success 且 Enabled，然后刷新当前业务配置页面。还需要确认来源没有处于 Paused、Deleting 或 Disabled 状态。

无法保存分组名称

分组名称必须唯一。新建或编辑来源时，请改用未被其他来源使用的名称。

剩余数量为零，无法再次导入

Remaining 为零表示当前图标集范围已经导入完成。只有修改导入范围，例如选择其他分类或样式后，才会产生新的可导入图标。