|
@@ -2,16 +2,17 @@
|
|
|
|
|
|
## 概述
|
|
|
|
|
|
-Icon 组件现在支持产品层级功能,允许不同产品使用专属的图标集,同时保持完整的降级机制。
|
|
|
+Icon 组件支持多种图标来源,包括本地图标、产品层级图标和外部URL图标。组件提供完整的降级机制和灵活的图标管理方式。
|
|
|
|
|
|
## 层级优先级
|
|
|
|
|
|
图标解析按以下优先级顺序查找:
|
|
|
|
|
|
-1. **Custom层** (最高优先级) - 全局用户自定义图标
|
|
|
-2. **Product-Custom层** - 产品内用户自定义图标
|
|
|
-3. **Product-Base层** - 产品基础图标
|
|
|
-4. **Base层** (最低优先级) - 全局基础图标,作为兜底
|
|
|
+1. **URL图标** (最高优先级) - 直接指定的外部URL图标
|
|
|
+2. **Custom层** - 全局用户自定义图标
|
|
|
+3. **Product-Custom层** - 产品内用户自定义图标
|
|
|
+4. **Product-Base层** - 产品基础图标
|
|
|
+5. **Base层** (最低优先级) - 全局基础图标,作为兜底
|
|
|
|
|
|
## 目录结构
|
|
|
|
|
@@ -70,6 +71,134 @@ import Icon from './components/Icon';
|
|
|
<Icon module="module-common" name="icon-save" size="2x" />;
|
|
|
```
|
|
|
|
|
|
+### URL图标支持
|
|
|
+
|
|
|
+Icon 组件现在支持直接使用外部URL作为图标源,这是最简单直接的方式,优先级高于所有其他图标解析参数。
|
|
|
+
|
|
|
+#### 基本URL用法
|
|
|
+
|
|
|
+```tsx
|
|
|
+// 使用外部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
|
|
|
+
|
|
|
+```tsx
|
|
|
+// 使用相对路径URL
|
|
|
+<Icon
|
|
|
+ url="/icons/local-icon.svg"
|
|
|
+ module="common"
|
|
|
+ name="local-icon"
|
|
|
+ alt="Local Icon"
|
|
|
+/>
|
|
|
+```
|
|
|
+
|
|
|
+#### 动态URL图标
|
|
|
+
|
|
|
+```tsx
|
|
|
+// 动态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>` 标签属性:
|
|
|
+
|
|
|
+```tsx
|
|
|
+<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图标包含内置的错误处理机制:
|
|
|
+
|
|
|
+```tsx
|
|
|
+<Icon
|
|
|
+ url="https://example.com/icons/possibly-broken-icon.png"
|
|
|
+ module="common"
|
|
|
+ name="possibly-broken-icon"
|
|
|
+ onError={(e) => {
|
|
|
+ // 自定义错误处理逻辑
|
|
|
+ console.warn('图标加载失败,使用备用图标');
|
|
|
+ // 可以在这里设置状态来切换到备用图标
|
|
|
+ }}
|
|
|
+/>
|
|
|
+```
|
|
|
+
|
|
|
+#### 类型安全
|
|
|
+
|
|
|
+组件包含URL类型验证:
|
|
|
+
|
|
|
+```tsx
|
|
|
+// ✅ 正确的用法
|
|
|
+<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层图标(最低优先级)
|
|
|
+
|
|
|
+```tsx
|
|
|
+// 即使module和name对应的本地图标存在,也会使用URL
|
|
|
+<Icon
|
|
|
+ url="https://example.com/icons/priority-icon.svg"
|
|
|
+ module="common"
|
|
|
+ name="existing-local-icon" // 这个本地图标会被忽略
|
|
|
+/>
|
|
|
+```
|
|
|
+
|
|
|
### 产品特定图标
|
|
|
|
|
|
```tsx
|
|
@@ -199,6 +328,15 @@ import TestProductLayer from './components/Icon/test-product-layer';
|
|
|
|
|
|
## 更新日志
|
|
|
|
|
|
+### v2.1.0 - URL图标支持
|
|
|
+
|
|
|
+- ✅ 新增 `url` 参数支持,可直接使用外部URL作为图标源
|
|
|
+- ✅ URL图标拥有最高优先级,绕过所有本地图标解析
|
|
|
+- ✅ 支持绝对URL、相对URL和动态URL
|
|
|
+- ✅ 添加URL类型验证和错误处理机制
|
|
|
+- ✅ 支持所有标准 `<img>` 标签属性
|
|
|
+- ✅ 完全向后兼容,现有代码无需修改
|
|
|
+
|
|
|
### v2.0.0 - 产品层级支持
|
|
|
|
|
|
- ✅ 新增 `productId` 参数支持
|