更新记录

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 云打包验证。

1.0.7（2026-06-05）

• 收录 iOS 运行期行为对齐：监听 src / cachePolicy / iconId 变化，网络 SVG 回包增加请求序号、缓存 key 和 src 快照校验，组件注册表支持运行期重绑与卸载清理。
• 收录 Harmony 三端视觉一致修复：演示页轻量兜底统一模拟原生预览框底色、描边、48px 图标墙尺寸和 96px Motion 尺寸，图标墙不再显示成与标题不一致的大色块。
• 收录主题切换与描边修复：主题按钮只改变图标主题色板，描边细 / 描边粗 会真实影响 App 安全 SVG 子集和 Harmony/旧基座兜底预览。
• 同步 package.json、README 当前版本、商业交付状态文件和发布证据包到 1.0.7，保持上架资料、源码包和验收指令版本一致。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

lizhao-icon-pro

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

当前版本：1.0.10

1.0.10 iOS 云打包复修

本版本继续收口 iOS 云打包 SwiftCompile 兼容问题：iOS 组件不再直接读取 this.opacity 参与 root style 和 native alpha，避免 UTS 生成 Swift 时把组件基类 DCUniComponent.opacity: CGFloat 与 NSNumber prop 桥接混用。

从简单到复杂

适合做什么

• 用 <lizhao-icon-pro /> 显示内置图标、业务图标和 SVG 文本。
• 给图标配置主题、状态、徽标、旋转、透明度和动画。
• 注册自己的业务图标集，让图标可搜索、可预加载、可缓存。
• 给旧项目图标名配置别名，降低迁移成本。
• 查看缓存统计、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);
  }
});

常用功能精简示例

下面这些片段适合直接复制到 .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 名称索引：

• 图标集与搜索：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，再渲染大批量图标。
• 若后续接入三方 SVG parser、专用原生缓存目录或路径级动画，需要重新制作自定义基座。

作者系列UTS插件

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