npm package: @reskin/icon
Description: 基于 Mage Icons 的 Angular SVG 图标组件库，提供 1300+ 高质量图标资源。
Latest version: 0.1.0

# @reskin/icon

基于 Mage Icons 的 Angular SVG 图标组件库，提供 1300+ 高质量图标资源。

## 特性

- 🎨 1300+ 精美图标，涵盖多种使用场景
- 🔄 支持 4 种图标风格（stroke、bulk、social-bw、social-color）
- 🎯 完全类型安全的 TypeScript 支持
- 🚀 按需加载，性能优化
- 🎨 灵活的尺寸和颜色自定义
- ♿ 内置无障碍支持（ARIA 属性）
- 🔒 使用 DomSanitizer 确保安全性

## 安装

```bash
npm install @reskin/icon
```

## 快速开始

### 1. 导入模块

在你的 Angular 模块中导入 `RkIconModule`：

```typescript
import { NgModule } from '@angular/core';
import { RkIconModule } from '@reskin/icon';

@NgModule({
    imports: [
        RkIconModule,
        // ...其他模块
    ],
})
export class AppModule {}
```

### 2. 使用图标

在模板中使用 `rk-icon` 组件：

```html
<rk-icon name="heart"></rk-icon>
```

## API 文档

### 组件属性

| 属性名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `name` | `string` | - | 图标名称（必填） |
| `type` | `'stroke' \| 'bulk' \| 'social-bw' \| 'social-color'` | `'stroke'` | 图标类型 |
| `size` | `number` | `24` | 图标大小（像素） |
| `color` | `string` | `'#000'` | 图标颜色（支持任何 CSS 颜色值） |

### 图标类型说明

- **stroke**: 线条风格图标，适合界面图标
- **bulk**: 填充风格图标，视觉更醒目
- **social-bw**: 黑白社交媒体图标
- **social-color**: 彩色社交媒体图标（保留品牌色）

## 使用示例

### 基础用法

```html
<!-- 默认图标 -->
<rk-icon name="heart"></rk-icon>

<!-- 指定类型 -->
<rk-icon name="heart" type="bulk"></rk-icon>
```

### 自定义尺寸

```html
<!-- 小图标 -->
<rk-icon name="star" [size]="16"></rk-icon>

<!-- 中等图标 -->
<rk-icon name="star" [size]="24"></rk-icon>

<!-- 大图标 -->
<rk-icon name="star" [size]="48"></rk-icon>
```

### 自定义颜色

```html
<!-- 使用颜色值 -->
<rk-icon name="heart" color="#ff0000"></rk-icon>
<rk-icon name="heart" color="rgb(255, 0, 0)"></rk-icon>

<!-- 使用 CSS 颜色名 -->
<rk-icon name="heart" color="red"></rk-icon>
```

### 通过 CSS 控制颜色

```html
<rk-icon name="heart" class="text-red-500"></rk-icon>
```

```css
.text-red-500 {
    color: #ef4444;
}

/* 图标会继承 color 属性 */
rk-icon {
    color: #3b82f6;
}
```

### 响应式尺寸

```html
<!-- 使用 Tailwind CSS -->
<rk-icon name="menu" class="w-6 h-6 md:w-8 md:h-8"></rk-icon>

<!-- 使用动态绑定 -->
<rk-icon name="menu" [size]="isMobile ? 20 : 28"></rk-icon>
```

### 在按钮中使用

```html
<button class="flex items-center gap-2">
    <rk-icon name="download" [size]="20"></rk-icon>
    <span>下载</span>
</button>
```

### 社交媒体图标

```html
<!-- 黑白风格 -->
<rk-icon name="facebook" type="social-bw" [size]="32"></rk-icon>
<rk-icon name="twitter" type="social-bw" [size]="32"></rk-icon>

<!-- 彩色风格（保留品牌色） -->
<rk-icon name="facebook" type="social-color" [size]="32"></rk-icon>
<rk-icon name="twitter" type="social-color" [size]="32"></rk-icon>
```

## 工具函数

库还提供了一些实用的工具函数：

```typescript
import { getIcon, searchIcons, getIconsByType, iconStats } from '@reskin/icon';

// 获取单个图标
const heartIcon = getIcon('heart', 'bulk');

// 搜索图标
const arrowIcons = searchIcons('arrow');
const strokeArrows = searchIcons('arrow', 'stroke');

// 按类型获取图标列表
const bulkIcons = getIconsByType('bulk');

// 查看图标统计信息
console.log(iconStats);
// { total: 1356, bulk: 678, stroke: 678, 'social-bw': 0, 'social-color': 0 }
```

## 性能优化

### 变更检测策略

组件使用 `OnPush` 变更检测策略，确保最佳性能：

```typescript
@Component({
    selector: 'rk-icon',
    changeDetection: ChangeDetectionStrategy.OnPush,
})
export class RkIconComponent implements OnInit, OnChanges {
    ngOnInit(): void {
        // 初始渲染
        this.renderIcon();
    }
    
    ngOnChanges(changes: SimpleChanges): void {
        // 属性变化时重新渲染
        if (changes['name'] || changes['type'] || changes['size'] || changes['color']) {
            this.renderIcon();
        }
    }
}
```

### 按需加载

图标数据在首次使用时加载，不会影响应用启动性能。

## 无障碍支持

组件自动添加 ARIA 属性以支持屏幕阅读器：

```html
<rk-icon name="heart"></rk-icon>
<!-- 渲染为 -->
<span role="img" aria-label="heart">
    <!-- SVG 内容 -->
</span>
```

## 安全性

组件使用 Angular 的 `DomSanitizer` 服务处理 SVG 内容。由于图标数据来自可信的内部源（`mage.icons.ts`），使用 `bypassSecurityTrustHtml()` 方法直接绕过安全检查，避免不必要的内容清理。

**安全说明**：
- 图标数据存储在编译时的静态文件中，不接受外部输入
- 所有图标内容在发布前已经过验证
- 如果需要渲染来自外部或用户输入的 SVG，应使用 `sanitize()` 方法

## 常见问题

### 图标不显示？

1. 确保已正确导入 `RkIconModule`
2. 检查图标名称是否正确（区分大小写）
3. 查看浏览器控制台是否有警告信息

### 如何查找可用的图标？

```typescript
import { icons } from '@reskin/icon';

// 打印所有图标名称
console.log(icons.map(icon => icon.name));
```

### 颜色不生效？

- 确保图标类型支持颜色自定义（`social-color` 类型保留品牌色）
- 检查 CSS 优先级是否被覆盖

### 如何在 TypeScript 中使用？

```typescript
import { IconType } from '@reskin/icon';

export class MyComponent {
    iconName = 'heart';
    iconType: IconType = 'bulk';
    iconSize = 24;
}
```

## 浏览器兼容性

- Chrome (最新版)
- Firefox (最新版)
- Safari (最新版)
- Edge (最新版)

## 许可证

查看 package.json 了解许可证信息。

## 更新日志

### 0.0.3
- 优化组件性能，使用 OnPush 变更检测
- 添加 DomSanitizer 安全处理
- 改进 TypeScript 类型定义
- 添加无障碍支持
- 使用 Tailwind CSS 优化样式