dros/src/components/Icon

Icon 组件 - 产品层级功能

概述

Icon 组件支持多种图标来源，包括本地图标、产品层级图标和外部URL图标。组件提供完整的降级机制和灵活的图标管理方式。

层级优先级

图标解析按以下优先级顺序查找：

1. URL图标 (最高优先级) - 直接指定的外部URL图标
2. Custom层 - 全局用户自定义图标
3. Product-Custom层 - 产品内用户自定义图标
4. Product-Base层 - 产品基础图标
5. Base层 (最低优先级) - 全局基础图标，作为兜底

目录结构

新的嵌套结构（推荐）

assets/Icons/
├── base/                           # 全局基础图标层
│   └── {moduleName}/              # 模块名（如 module-common）
│       └── theme-{theme}/         # 主题目录（如 theme-default）
│           └── {size}/            # 尺寸目录（1x, 2x, 3x）
│               └── {iconFiles}    # 图标文件
├── product/                       # 产品层级（嵌套结构）
│   └── {productId}/              # 产品ID（如 animal, medical）
│       ├── base/                 # 产品基础图标
│       │   └── {moduleName}/     # 模块名
│       │       └── theme-{theme}/ # 主题目录
│       │           └── {size}/   # 尺寸目录
│       │               └── {iconFiles} # 图标文件
│       └── custom/               # 产品内用户自定义
│           └── {userId}/         # 用户ID
│               └── {moduleName}/ # 模块名
│                   └── theme-{theme}/ # 主题目录
│                       └── {size}/    # 尺寸目录
│                           └── {iconFiles} # 图标文件
└── custom/                        # 全局用户自定义图标层
    └── {userId}/                  # 用户ID
        └── {moduleName}/          # 模块名
            └── theme-{theme}/     # 主题目录
                └── {size}/        # 尺寸目录
                    └── {iconFiles} # 图标文件

向后兼容的旧结构

系统仍支持旧的平级product结构，会自动将其视为product-base层级：

assets/Icons/
├── product/
│   └── {productId}/              # 产品ID
│       └── {moduleName}/         # 直接是模块名（兼容模式）
│           └── theme-{theme}/    # 主题目录
│               └── {size}/       # 尺寸目录
│                   └── {iconFiles} # 图标文件

使用方法

基础用法

import Icon from './components/Icon';

// 使用基础图标
<Icon module="module-common" name="icon-save" size="2x" />;

URL图标支持

Icon 组件现在支持直接使用外部URL作为图标源，这是最简单直接的方式，优先级高于所有其他图标解析参数。

基本URL用法

// 使用外部URL图标
<Icon
  url="https://example.com/icons/save-icon.png"
  module="common"  // 仍需提供module和name作为fallback标识
  name="save-icon"
  alt="Save Icon"
  size="2x"
  widthPx={24}
/>

相对路径URL

// 使用相对路径URL
<Icon
  url="/icons/local-icon.svg"
  module="common"
  name="local-icon"
  alt="Local Icon"
/>

动态URL图标

// 动态URL（例如从API获取）
const dynamicIconUrl = userPreferences.iconUrl;

<Icon
  url={dynamicIconUrl}
  module="user"
  name="user-preferred-icon"
  alt="User Icon"
  onError={(e) => {
    console.error('图标加载失败:', e);
    // 可以在这里设置fallback图标
  }}
/>

URL图标的优势

1. 简单直接：无需复杂的图标注册机制
2. 动态支持：支持运行时动态切换图标
3. 外部资源：可以使用CDN、云存储等外部资源
4. 用户上传：支持用户上传的自定义图标
5. 优先级最高：当提供URL时，会绕过所有本地图标解析

URL图标支持的属性

URL图标支持所有标准的 <img> 标签属性：

<Icon
  url="https://example.com/icons/advanced-icon.svg"
  module="common"
  name="advanced-icon"
  alt="Advanced Icon"
  widthPx={32}
  heightPx={32}
  className="custom-icon-class"
  style={{ borderRadius: '4px' }}
  loading="lazy"
  crossOrigin="anonymous"
  onError={(e) => handleIconError(e)}
  onLoad={(e) => handleIconLoad(e)}
/>

错误处理

URL图标包含内置的错误处理机制：

<Icon
  url="https://example.com/icons/possibly-broken-icon.png"
  module="common"
  name="possibly-broken-icon"
  onError={(e) => {
    // 自定义错误处理逻辑
    console.warn('图标加载失败，使用备用图标');
    // 可以在这里设置状态来切换到备用图标
  }}
/>

类型安全

组件包含URL类型验证：

// ✅ 正确的用法
<Icon url="https://example.com/icon.png" module="common" name="icon" />

// ❌ 错误的用法（会在控制台显示警告）
<Icon url={123} module="common" name="icon" />  // url必须是字符串

// ❌ 无效的URL格式（会在控制台显示警告，但仍会尝试渲染）
<Icon url="invalid-url" module="common" name="icon" />

URL图标与本地图标的优先级

当同时提供URL和其他图标参数时，优先级如下：

1. URL图标（最高优先级）
2. Custom层用户自定义图标
3. Product-Custom层图标
4. Product-Base层图标
5. Base层图标（最低优先级）

// 即使module和name对应的本地图标存在，也会使用URL
<Icon
  url="https://example.com/icons/priority-icon.svg"
  module="common"
  name="existing-local-icon"  // 这个本地图标会被忽略
/>

产品特定图标

// 使用医疗产品的图标
<Icon
  productId="medical"
  module="module-exam"
  name="icon-xray"
  size="2x"
/>

// 使用牙科产品的图标
<Icon
  productId="dental"
  module="module-exam"
  name="icon-xray"
  size="2x"
/>

用户自定义图标（最高优先级）

// 用户自定义图标会覆盖产品和基础图标
<Icon
  userId="doctor123"
  productId="medical"
  module="module-common"
  name="icon-save"
  size="2x"
/>

完整参数示例

<Icon
  userId="user123" // 可选：用户ID
  productId="medical" // 可选：产品ID
  module="module-exam" // 必需：模块名
  name="icon-xray" // 必需：图标基础名
  theme="dark" // 可选：主题（默认 'default'）
  size="3x" // 可选：尺寸（默认 '2x'）
  state="hover" // 可选：状态（默认 'default'）
  useAntdIcon={true} // 可选：是否使用 Ant Design 包装
  widthPx={32} // 可选：像素大小
  className="custom-icon" // 可选：CSS 类名
/>

降级机制

当指定的图标不存在时，系统会按以下顺序降级：

1. 层级降级：custom → product → base
2. 主题降级：指定主题 → default
3. 尺寸降级：3x → 2x → 1x
4. 状态降级：指定状态 → default
5. 扩展名优先级：svg → webp → png → jpg → jpeg

文件命名规范

支持带状态后缀的文件命名：

• icon-name.svg - 默认状态
• icon-name_hover.svg - 悬停状态
• icon-name_active.svg - 激活状态
• icon-name_disabled.svg - 禁用状态

产品ID 建议

推荐使用有意义的产品ID：

• medical - 医疗产品
• dental - 牙科产品
• veterinary - 兽医产品
• industrial - 工业产品

实际应用场景

场景1：多产品线图标差异化

// 医疗产品的X光图标可能更注重人体解剖结构
<Icon productId="medical" module="module-exam" name="icon-xray" />

// 兽医产品的X光图标可能更适合动物解剖结构
<Icon productId="veterinary" module="module-exam" name="icon-xray" />

场景2：品牌定制

// 不同产品可以有不同的品牌色彩和风格
<Icon productId="premium" module="module-common" name="icon-logo" />
<Icon productId="standard" module="module-common" name="icon-logo" />

场景3：功能差异

// 高级产品可能有更多功能图标
<Icon productId="pro" module="module-advanced" name="icon-ai-analysis" />

// 基础产品降级到通用图标
<Icon productId="basic" module="module-advanced" name="icon-ai-analysis" />
// 如果 basic 产品没有此图标，会自动降级到 base 层

测试

运行测试组件查看产品层级功能：

import TestProductLayer from './components/Icon/test-product-layer';

// 在你的应用中渲染测试组件
<TestProductLayer />;

注意事项

1. 性能：图标索引在构建时生成，运行时查找性能为 O(1)
2. 兼容性：完全向后兼容，现有代码无需修改
3. 扩展性：可以轻松添加新的产品ID和图标
4. 类型安全：完整的 TypeScript 类型支持

更新日志

v2.1.0 - URL图标支持

• ✅ 新增 url 参数支持，可直接使用外部URL作为图标源
• ✅ URL图标拥有最高优先级，绕过所有本地图标解析
• ✅ 支持绝对URL、相对URL和动态URL
• ✅ 添加URL类型验证和错误处理机制
• ✅ 支持所有标准 <img> 标签属性
• ✅ 完全向后兼容，现有代码无需修改

v2.0.0 - 产品层级支持

• ✅ 新增 productId 参数支持
• ✅ 新增 product 层级目录结构
• ✅ 更新层级优先级：custom > product > base
• ✅ 完善降级机制支持产品层级
• ✅ 保持完全向后兼容性