更新记录

1.0.3（2026-06-03）

• 修复图标墙中图标与文字仍未完全左右居中的问题：图标卡片顶部和标题统一使用卡片全宽中轴，<lizhao-icon-pro /> 原生组件节点改为参与 flex 居中，不再以绝对定位贴左上角。
• 修复 Android 原生组件 size 二次按 rpx 放大导致外层 48px 图标槽裁切的问题，componentSizePx()、描边宽度和预览尺寸统一按 px 语义处理，避免图标底板和业务图形看起来偏左上。
• 同步插件内完整示例 uni_modules/lizhao-icon-pro/examples/iconPro.nvue，下载插件后看到的示例代码与项目演示页保持一致。
• 强化发布守卫：结构守卫和商业守卫新增图标居中回归检查，禁止旧的 margin-left: 32rpx / 56rpx、不稳定 align-self 和原生图标节点绝对定位左上角再次进入 Demo。

1.0.2（2026-06-02）

• 升级发布版本到 1.0.2，同步 package.json、README 当前版本号与商业交付状态文件，准备插件市场发布。
• 修复 iOS 端 component-uts 原生组件只返回空白 UIView 的问题，NVLoad 现在会创建可见原生图标树，并补齐底板、预览层、内置业务图标、安全 SVG 图层、加载环、角标、点击手势、状态/主题刷新和 NVMeasure 尺寸测量。
• 修复 iOS 端 rotate 属性没有作用到原生图标的问题，现在通过 CGAffineTransform(rotationAngle:) 写入原生预览层，旋转按钮和插件属性保持一致。
• 修复 Demo Motion 区按钮只改变外层页面效果的问题，旋转、脉冲、震动、加载态、成功态会直接驱动 <lizhao-icon-pro /> 的 size / rotate / opacity / loading / badge / status / animated 属性。
• 修复 Motion 控制组件 iconId 与上下文 API 不一致的问题，组件、createIconProContext('control-icon') 和批量状态接口统一使用 control-icon，避免按钮命中最后注册的其他图标。
• 修复 iOS 图标墙和 Motion 大图标被 Android 专用偏移影响的问题，相关偏移已限定为 APP-ANDROID，iOS 使用组件自身居中。
• 强化发布守卫：结构守卫和商业守卫新增 iOS 原生 UIView 图标树、业务图标、安全 SVG、加载态、角标、点击手势和尺寸测量检查。

1.0.1（2026-06-02）

• 升级发布版本到 1.0.1，同步 package.json、README 当前版本号与发布日志。
• README 的完整示例已按当前 pages/iconPro/iconPro.nvue 演示页重写，覆盖首屏展示、3 分钟接入、主题与批量状态、图标墙、Motion 动画、多源 SVG 和常用 API。
• 优化发布文档的客户阅读体验，默认说明客户可见能力与接入方式，不再把内部调试按钮、兜底图形和固定联系方式作为对外内容。
• 补充当前 Demo 的关键用法：color / colors / theme 显式传参、图标墙三列展示、Motion 外层动画承载、多源 SVG 的 svgText / base64 / network 示例和常用 API 按钮说明。
• 记录当前发布边界：App Android / iOS 为核心能力，Web / 小程序为轻量降级；网络 SVG、动画与缓存能力建议在自定义基座中做真机验收。

平台兼容性

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.3

适合做什么

• 用 <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);
  },
  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. 缓存预加载与缓存统计

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

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

const preloadResult = preloadIconsDirect("dashboard,commerce,secure", "", "memory-disk");
console.log("预加载结果", preloadResult.loaded, preloadResult.cacheHits);

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

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

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");

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

<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"]
    }
  ]
});

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、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 / 小程序为轻量降级能力。
• 收藏、最近使用、业务图标集、业务别名和自定义主题在 App 端可持久化；降级平台不承诺同等持久化效果。
• 复杂页面建议先调用 preloadIcons 或 createIconProPreloadPlan，再渲染大批量图标。
• 若后续接入三方 SVG parser、专用原生缓存目录或路径级动画，需要重新制作自定义基座。