更新记录

1.0.12（2026-09-06）

• 2026-09-06：补充 Android 远程图标集接口的具体参数类型导出和示例回调类型，修复 uni-app x 页面编译时参数类型不可见的问题。
• 新增 previewRemoteIconSetUpdate，可在同步前只读查看当前与候选版本、图标和别名增改删、安装冲突与明细截断；预览不会修改注册表、同步状态或回滚槽。
• 新增 rollbackRemoteIconSet 与 9030011，为每个远程图标集保存一个上一稳定版本，并以原子事务交换当前/上一清单；回滚后可再次回滚撤销。
• 仅真实更新覆盖有效旧清单时推进回滚槽；首次安装、304、缓存降级和失败同步保持原快照，状态查询增加上一版本与快照时间。
• Android 使用具体对象桥接，iOS 复用可回滚安装适配器与安全回调派发，Web/微信/支付宝提供同语义轻量实现；Harmony 明确返回不支持。
• 更新 uni-app、uni-app x 示例和客户文档，推荐“先预览、确认同步、必要时回滚”的发布流程。
• 本版本不新增原生依赖、权限或 Manifest，但公开 UTS 导出与 App 生成代码变化；Android/iOS 发布前需重新原生联编并使用匹配的新自定义基座验证。

1.0.10（2026-06-17）

• 复修 iOS 云打包 CGFloat / NSNumber 类型冲突：iOS 组件移除对 this.opacity 的直接访问，避免生成物继续和 DCUniComponent.opacity 桥接混用。
• 保留 1.0.9 的数组可变性、可空数组解包和统计字段 NSNumber 兼容修复；本版本只做 iOS 组件透明度冲突收口。
• 本版本仅修改 utssdk/app-ios 平台实现和发布资料，不修改公共接口、Android、Harmony、web/mp/app-plus 实现或 uni-app 示例。
• 发布前建议重新提交 iOS 云打包自定义基座或正式包复验。

1.0.9（2026-06-16）

• 修复 iOS 云打包 SwiftCompile：批量注册、缓存预加载和失败明细收集中会追加元素的数组统一使用可变数组，避免 Swift 生成物对不可变数组执行追加。
• 修复 iOS 可空数组桥接：图标集、失败明细和预加载结果遍历前统一解包或兜底为空数组，避免可空数组直接参与循环。
• 修复 iOS 端长度与统计字段：数组长度统一通过 helper 转为 NSNumber 兼容值，避免 Int -> NSNumber 参数不匹配。
• 保留 registerIconSetJson、registerIconSetJsonDirect、failResults、durationMs 等 1.0.8 接入增强能力，本轮只做 iOS 云打包兼容收口。
• 增强 iOS 云打包回归守卫；本版本需重新提交 iOS 云打包验证。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

lizhao-icon-pro

lizhao-icon-pro 是一个面向 uni-app / uni-app x 的 UTS SVG 图标组件插件。它把图标展示、SVG 文本解析、主题、状态、徽标、动画、缓存、图标搜索和诊断能力放在一个组件里，适合做 App 首页、工作台、商城、后台管理、设备控制台等需要大量业务图标的页面。

从简单到复杂

适合做什么

• 用 <lizhao-icon-pro /> 显示内置图标、业务图标和 SVG 文本。
• 给图标配置主题、状态、徽标、旋转、透明度和动画。
• 注册自己的业务图标集，让图标可搜索、可预加载、可缓存。
• 从设计平台、CMS 或业务后台同步带版本的远程图标集，网络失败时保留当前可用版本。
• 给旧项目图标名配置别名，降低迁移成本。
• 查看缓存统计、SVG 兼容体检、运行诊断和配置快照。

支持平台

安装与引入

插件类型是 component-uts，组件标签为：

<lizhao-icon-pro />

API 从插件根目录引入：

import { preloadIcons, searchIcons } from "@/uni_modules/lizhao-icon-pro";

App 端建议在 .nvue 或 uni-app x 页面中使用原生组件。普通 .vue 页面在部分环境里可能把原生组件当作普通标签解析，导致渲染或生命周期不符合预期。

权限说明

自定义基座说明

商业能力摘要

• App 端支持 disk / memory-disk 真实持久缓存，getIconCacheStats 可查看缓存统计，configureIconCache 可配置 maxEntries / ttlMs。
• 支持业务偏好持久化：收藏和最近使用重启后保留，业务别名重启后保留，业务图标集持久化适合多业务线统一管理。
• App 缓存事件可通过 diskFallback=false 判断是否命中真实持久缓存，网络 SVG 下载建议在自定义基座中完成真机验证。
• 提供商业诊断快照、图标库画像报告、性能画像报告、使用洞察报告、客户接入向导、品牌主题设计令牌、主题视觉质检、客户验收计划、品牌主题交付包、图标迁移计划、智能预加载计划。
• 使用洞察报告包含采纳评分、风险评分等运营指标，方便判断客户图标体系是否需要继续治理。
• 支持业务别名、业务资产审计、运行事件日志、售后诊断包、上线交付报告、配置快照、商业自检和 SVG 兼容体检。
• 支持兜底图标策略，旧项目图标名或业务别名无法命中时可返回明确建议，不会静默伪造成功。
• HTTPS 网络 SVG 可用于真机下载验证；复杂 SVG 真实路径解析以 SVG 安全子集为边界，描边宽度会影响安全子集图层边框。
• 运行期事件日志只保留运行期内存日志，组件错误会明确返回中文说明，避免出现 Cannot read properties of null 这类难以排查的空错误。

快速使用

显示内置图标

<template>
  <lizhao-icon-pro
    icon-id="homeIcon"
    name="dashboard"
    theme="brand"
    status="normal"
    :size="64"
    @tap="onIconTap"
  />
</template>

<script>
export default {
  methods: {
    onIconTap() {
      console.log("点击了图标");
    }
  }
};
</script>

显示 SVG 文本

<template>
  <lizhao-icon-pro
    icon-id="customSvg"
    name=""
    :svg-text="svgText"
    :size="72"
    :colors="['#0F766E', '#F97316', '#111827']"
  />
</template>

<script>
export default {
  data() {
    return {
      svgText: "<svg viewBox=\"0 0 64 64\"><rect x=\"12\" y=\"16\" width=\"40\" height=\"30\"/><circle cx=\"45\" cy=\"24\" r=\"7\"/><path d=\"M18 48h28\"/></svg>"
    };
  }
};
</script>

预加载常用图标

import { preloadIcons } from "@/uni_modules/lizhao-icon-pro";

preloadIcons({
  names: ["dashboard", "commerce", "secure"],
  cachePolicy: "memory-disk",
  success(res) {
    console.log("预加载完成", res.loaded, res.failed, res.failResults);
  },
  fail(err) {
    console.log("预加载失败", err);
  }
});

远程图标集同步

当图标由设计平台、CMS 或业务后台统一维护时，可以让插件直接同步一份带版本的 HTTPS 清单。插件会保存服务端返回的 ETag / Last-Modified，后续请求通过 If-None-Match / If-Modified-Since 判断是否需要更新。

建议在应用启动或业务图标入口采用“先预览、确认后同步”的接入顺序：先调用 previewRemoteIconSetUpdate 查看版本和图标/别名增改删，该调用绝不注册图标或写同步状态；用户或业务规则确认后再调用 syncRemoteIconSet。服务端返回 304 时，插件会重新校验本地有效清单并恢复运行期注册表，因此应用重启后不需要重复下载完整清单。

新清单会先完成大小、协议、图标名称、HTTPS 资源和 SVG 安全检查，通过后才替换当前图标集。网络或 HTTP 失败时可以回退最近一次有效清单，并明确返回 cacheFallback=true 和 warnings；不会把缓存回退伪装成在线更新成功。

清单格式

{
  "schemaVersion": 1,
  "setId": "commerce",
  "displayName": "商城图标集",
  "version": "2026.07.28.1",
  "icons": [
    {
      "name": "commerce:cart",
      "svgText": "<svg viewBox=\"0 0 64 64\"><path d=\"M12 18h40v30H12z\"/></svg>",
      "category": "商城",
      "keywords": ["购物车", "订单"],
      "color": "#0F766E"
    }
  ],
  "aliases": [
    {
      "alias": "legacy-cart",
      "target": "commerce:cart"
    }
  ]
}

uni-app 示例

import {
  getRemoteIconSetStatus,
  previewRemoteIconSetUpdate,
  rollbackRemoteIconSet,
  syncRemoteIconSet
} from "@/uni_modules/lizhao-icon-pro";

// 先预览候选版本；预览不修改当前图标集、同步状态或回滚槽。
previewRemoteIconSetUpdate({
  url: "https://static.example.com/icons/commerce.json",
  expectedSetId: "commerce",
  detailLimit: 100,
  success(res) {
    console.log("版本", res.currentVersion, "->", res.candidateVersion);
    console.log("图标差异", res.iconDiff, "别名差异", res.aliasDiff);
    console.log("是否允许安装", res.installable, res.blockingReason);
  }
});

// 确认后同步；失败不会覆盖当前有效版本。
syncRemoteIconSet({
  url: "https://static.example.com/icons/commerce.json",
  expectedSetId: "commerce",
  fallbackToCache: true,
  success(res) {
    console.log(
      "同步结果",
      res.status,
      res.version,
      res.iconCount,
      res.cacheFallback,
      res.warnings
    );
  },
  fail(err) {
    console.log("同步失败", err.errCode, err.errMsg);
  },
  complete() {
    console.log("远程同步流程结束");
  }
});

// 状态查询只读本地记录，不会再次请求网络。
getRemoteIconSetStatus({
  setId: "commerce",
  success(res) {
    console.log("当前同步状态", res.items);
  }
});

// 仅在 hasRollbackSnapshot=true 时调用；回滚后仍可再次调用来撤销本次回滚。
rollbackRemoteIconSet({
  setId: "commerce",
  success(res) {
    console.log("回滚完成", res.fromVersion, "->", res.toVersion);
  }
});

uni-app x 示例

import {
  IconProRemoteIconSetSyncResult,
  previewRemoteIconSetUpdate,
  rollbackRemoteIconSet,
  syncRemoteIconSet
} from "@/uni_modules/lizhao-icon-pro";

// uni-app x 使用同一公开合同，回调保留强类型结果。
syncRemoteIconSet({
  url: "https://static.example.com/icons/commerce.json",
  expectedSetId: "commerce",
  success: (res: IconProRemoteIconSetSyncResult) => {
    console.log("同步状态：" + res.status + "，版本：" + res.version);
  },
  fail: (err) => {
    console.log("同步失败：" + err.errCode.toString());
  },
  complete: () => {
    console.log("远程同步流程结束");
  }
});

previewRemoteIconSetUpdate(options) 参数

预览结果包含 currentVersion / candidateVersion、当前和候选数量、iconDiff / aliasDiff、installable / blockingReason。每个 diff 提供排序后的 added / changed / removed、完整数量、未变化数量和截断标记；运行期 lastUsedAt 不作为图标内容变化。

rollbackRemoteIconSet(options) 参数

插件只保存一个上一稳定版本。成功回滚后，回滚前版本会成为新的上一版本，因此可以再次回滚撤销操作；首次安装、304、缓存降级和失败同步不会覆盖已有回滚槽。

syncRemoteIconSet(options) 参数

返回值

Web 使用时，清单服务需要允许浏览器 CORS；微信和支付宝小程序需要把清单域名加入业务域名白名单。远程同步只下载 JSON 清单，不会在一次调用中并发下载每个网络 SVG；需要预热网络 SVG 时继续调用 preloadIcons。

常用功能精简示例

下面这些片段适合直接复制到 .nvue 或 uni-app x 页面中快速接入。完整销售演示源码仍放在 uni_modules/lizhao-icon-pro/examples/iconPro.nvue，这一节只保留客户最常用的能力。

1. 内置图标、主题、状态和徽标

<template>
  <view class="icon-row">
    <lizhao-icon-pro
      icon-id="dashboardIcon"
      name="dashboard"
      theme="brand"
      status="normal"
      :size="64"
      color="#0F766E"
      @tap="onIconTap"
    />

    <lizhao-icon-pro
      icon-id="orderIcon"
      name="commerce"
      theme="commerce"
      status="selected"
      badge="9"
      :size="64"
      :colors="['#F97316', '#FDBA74', '#111827']"
    />
  </view>
</template>

<script>
export default {
  methods: {
    onIconTap() {
      console.log("图标被点击");
    }
  }
};
</script>

2. SVG 文本、Base64 和网络 SVG

<template>
  <view class="icon-row">
    <lizhao-icon-pro
      icon-id="sourceSvgIcon"
      name=""
      :svg-text="sourceSvgText"
      :size="72"
      :colors="['#0F766E', '#F97316', '#2563EB']"
      cache-policy="memory"
    />

    <lizhao-icon-pro
      icon-id="base64SvgIcon"
      name=""
      :src="base64SvgSource"
      :size="72"
      cache-policy="memory-disk"
    />

    <lizhao-icon-pro
      icon-id="networkSvgIcon"
      name=""
      src="https://cdn.jsdelivr.net/npm/lucide-static@0.468.0/icons/cloud.svg"
      :size="72"
      cache-policy="memory-disk"
      @load="onNetworkLoad"
      @error="onNetworkError"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      sourceSvgText: "<svg viewBox=\"0 0 64 64\"><rect x=\"12\" y=\"18\" width=\"32\" height=\"24\"/><circle cx=\"46\" cy=\"20\" r=\"7\"/><path d=\"M18 50h28\"/></svg>",
      base64SvgSource: "data:image/svg+xml;base64,PHN2ZyB2aWV3Qm94PSIwIDAgNjQgNjQiPjxyZWN0IHg9IjE0IiB5PSIyMCIgd2lkdGg9IjM2IiBoZWlnaHQ9IjI0Ii8+PC9zdmc+"
    };
  },
  methods: {
    onNetworkLoad() {
      console.log("网络 SVG 已加载");
    },
    onNetworkError(err) {
      console.log("网络 SVG 加载失败", err);
    }
  }
};
</script>

3. 注册业务图标集并搜索

import { registerIconSet, searchIcons } from "@/uni_modules/lizhao-icon-pro";

registerIconSet({
  setName: "crm",
  displayName: "CRM 业务图标",
  override: true,
  icons: [
    {
      name: "crm:customer",
      svgText: "<svg viewBox=\"0 0 64 64\"><circle cx=\"32\" cy=\"22\" r=\"10\"/><path d=\"M16 52c4-12 28-12 32 0\"/></svg>",
      category: "客户",
      color: "#0F766E",
      keywords: ["customer", "user", "客户"]
    }
  ],
  success(res) {
    console.log("业务图标集已注册", res.count);
  }
});

searchIcons({
  keyword: "客户",
  limit: 10,
  success(res) {
    console.log("搜索命中", res.total, res.icons);
  }
});

4. 批量导入业务图标集

如果业务图标来自后台配置、设计资产导出或旧项目迁移，可以直接传 JSON 字符串。JSON 支持两种格式：数组，或包含 icons 字段的对象。

import { registerIconSetJsonDirect } from "@/uni_modules/lizhao-icon-pro";

const crmIconJson = JSON.stringify({
  icons: [
    {
      name: "crm:lead",
      svgText: "<svg viewBox=\"0 0 64 64\"><path d=\"M14 20h36v26H14z\"/><path d=\"M22 30h20M22 38h14\"/></svg>",
      category: "客户",
      color: "#2563EB",
      keywords: ["lead", "线索"]
    },
    {
      name: "crm:deal",
      svgText: "<svg viewBox=\"0 0 64 64\"><circle cx=\"24\" cy=\"28\" r=\"10\"/><path d=\"M36 22h14v24H22v-8\"/></svg>",
      category: "交易",
      color: "#F97316",
      keywords: ["deal", "商机"]
    }
  ]
});

const result = registerIconSetJsonDirect("crm-json", "CRM JSON 图标集", crmIconJson, true, false);
console.log("批量导入业务图标集", result.count, result.failed, result.failResults);

5. 缓存预加载与缓存统计

import {
  configureIconCache,
  preloadIconsDirect,
  getIconCacheStatsDirect
} from "@/uni_modules/lizhao-icon-pro";

configureIconCache({
  cachePolicy: "memory-disk",
  maxEntries: 128,
  ttlMs: 600000
});

const preloadResult = preloadIconsDirect("dashboard,commerce,secure,not-exists", "", "memory-disk");
console.log("预加载结果", preloadResult.loaded, preloadResult.failed, preloadResult.cacheHits);
console.log("预加载失败明细", preloadResult.failResults);

const cacheStats = getIconCacheStatsDirect(true);
console.log("缓存统计", cacheStats.memoryCount, cacheStats.diskCount, cacheStats.hitRate);

6. 收藏、最近使用和批量状态

import {
  setIconFavoriteDirect,
  listRecentIcons,
  applyIconStateBatchDirect
} from "@/uni_modules/lizhao-icon-pro";

setIconFavoriteDirect("dashboard", true);

listRecentIcons({
  limit: 5,
  success(res) {
    console.log("最近使用", res.names);
  }
});

applyIconStateBatchDirect("dashboardIcon,orderIcon", "selected");

7. 创建上下文控制动画和主题

<template>
  <lizhao-icon-pro
    icon-id="motionIcon"
    name="spark"
    theme="brand"
    status="normal"
    :size="72"
  />
</template>

<script>
import { createIconProContext } from "@/uni_modules/lizhao-icon-pro";

export default {
  onReady() {
    const iconContext = createIconProContext("motionIcon", this);
    iconContext.playAnimation("pulse");
    iconContext.setTheme("commerce");
    iconContext.setStatus("success");
  },
  onUnload() {
    const iconContext = createIconProContext("motionIcon", this);
    iconContext.stopAnimation();
  }
};
</script>

组件属性

组件事件

常用 API

带 Direct 后缀的 API 是直连接口，适合 App 页面按钮、演示页面和自动化冒烟测试。它们通常使用字符串、数字、布尔值等标量参数，不依赖回调对象。

常用 API 说明

registerIconSet(options)

注册业务图标集。注册后，图标可以参与搜索、预加载、缓存统计和诊断。

返回值：

示例：

import { registerIconSet } from "@/uni_modules/lizhao-icon-pro";

registerIconSet({
  setName: "business",
  displayName: "业务图标",
  override: true,
  icons: [
    {
      name: "business:ticket",
      svgText: "<svg viewBox=\"0 0 64 64\"><path d=\"M12 20h40v24H12z\"/></svg>",
      color: "#F97316",
      category: "订单",
      keywords: ["ticket", "coupon", "order"]
    }
  ]
});

registerIconSetJson(options)

批量导入业务图标集。适合后台下发、设计工具导出或旧项目迁移。非法图标会写入 failResults，默认跳过非法项继续注册合法项；如果希望出现任意非法项就整体失败，可传 failOnInvalid: true。

返回值：

示例：

import { registerIconSetJsonDirect } from "@/uni_modules/lizhao-icon-pro";

const result = registerIconSetJsonDirect(
  "crm-json",
  "CRM JSON 图标集",
  JSON.stringify({ icons: [{ name: "crm:lead", svgText: "<svg viewBox=\"0 0 64 64\"><path d=\"M12 20h40v24H12z\"/></svg>" }] }),
  true,
  false
);

console.log("批量导入业务图标集", result.count, result.failResults);

searchIcons(options)

搜索内置图标、业务图标、收藏图标或最近使用图标。

返回值：

preloadIcons(options)

预加载常用图标，适合列表页、工作台、首页进入前调用。

返回值：

configureIconCache(options)

配置图标缓存策略。App 端可使用 disk 或 memory-disk 做持久缓存。

返回值：

inspectIconSvg(options)

检查 SVG 是否适合当前组件解析。它不会执行 SVG 脚本，也不会主动下载网络 SVG。

完整示例页面

完整演示源码已放在插件目录内，下载插件后可以直接查看：

uni_modules/lizhao-icon-pro/examples/iconPro.nvue

这个示例文件展示首屏真实组件展示、3 分钟接入、主题与批量状态、图标墙、Motion 动画控制、多源 SVG 渲染和常用 API 演示。复制到项目页面时建议保留 nvue 承载方式，并从插件根目录引入 API：

import { getIconProCapabilities } from '@/uni_modules/lizhao-icon-pro';

示例默认隐藏内部诊断工具、兜底绘制层和额外调试按钮。需要排查运行细节时，可以在页面参数中开启：

完整 API 索引

公开 API 名称索引：

• 图标集与搜索：syncRemoteIconSet、getRemoteIconSetStatus、registerIconSet、registerIconSetDirect、registerIconSetJson、registerIconSetJsonDirect、listIconSets、searchIcons。
• 收藏、最近和状态：setIconFavorite、setIconFavoriteDirect、listRecentIcons、applyIconStateBatch、applyIconStateBatchDirect。
• 主题与缓存：registerIconTheme、getIconTheme、preloadIcons、preloadIconsDirect、clearIconCache、configureIconCache、getIconCacheStats、getIconCacheStatsDirect。
• 诊断与报告：getIconProDiagnostics、getIconProDiagnosticsDirect、getIconProLibraryReport、getIconProLibraryReportDirect、getIconProPerformanceReport、getIconProPerformanceReportDirect、getIconProUsageInsights、getIconProUsageInsightsDirect。
• 迁移、预热和 SVG：createIconProMigrationPlan、createIconProMigrationPlanDirect、createIconProPreloadPlan、createIconProPreloadPlanDirect、inspectIconSvg、inspectIconSvgDirect、runIconProSelfTest、runIconProSelfTestDirect。
• 业务别名与资产：registerIconAliases、registerIconAliasesDirect、resolveIconAlias、resolveIconAliasDirect、auditIconProAssets、auditIconProAssetsDirect。
• 事件与交付：getIconProEventLog、getIconProEventLogDirect、clearIconProEventLog、clearIconProEventLogDirect、exportIconProSupportBundle、exportIconProSupportBundleDirect、exportIconProDeliveryReport、exportIconProDeliveryReportDirect。
• 客户接入和主题包：createIconProOnboardingGuide、createIconProOnboardingGuideDirect、exportIconProDesignTokens、exportIconProDesignTokensDirect、inspectIconProTheme、inspectIconProThemeDirect、auditIconProAccessibility、auditIconProAccessibilityDirect、createIconProAcceptancePlan、createIconProAcceptancePlanDirect、exportIconProThemePackage、exportIconProThemePackageDirect。
• 配置与上下文：exportIconProConfig、exportIconProConfigDirect、importLastIconProConfigDirect、getIconProCapabilities、createIconProContext。

错误码

注意事项

• svgText 的优先级高于 src，适合直接传入业务 SVG 文本。
• 当前 SVG 解析聚焦安全子集，不执行 SVG 脚本，不承诺完整支持滤镜、渐变、mask、clipPath、symbol/use 等复杂 SVG 特性。
• 网络 SVG 只建议使用 HTTPS 地址；网络异常、响应不是 SVG 或解析失败时会进入错误回调。
• disk / memory-disk 在 App 端用于持久缓存；Web / 小程序为轻量降级能力。
• 预加载结果会返回 failResults，可以直接展示预加载失败明细；网络 SVG 在 preloadIconsDirect 中不会同步下载，会提示改用 preloadIcons 或组件加载。
• 收藏、最近使用、业务图标集、业务别名和自定义主题在 App 端可持久化；降级平台不承诺同等持久化效果。
• 复杂页面建议先调用 preloadIcons 或 createIconProPreloadPlan，再渲染大批量图标。
• 同一远程 URL 的 setId 不允许漂移，同一 setId 也不能由两个远程 URL 互相覆盖。
• 若后续接入三方 SVG parser、专用原生缓存目录或路径级动画，需要重新制作自定义基座。

作者系列 UTS 插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。