@blocklet/ui-react/docs/components-utilities-icon.zh.md

Some useful front-end web components that can be used in Blocklets.

# Icon

`Icon` 组件是一个基于 Material-UI 的 `Avatar` 组件构建的灵活实用工具。它旨在从多种来源渲染图标，包括 [Iconify](https://iconify.design/) 图标字符串、图像 URL 和基于字符的“字母头像”。这种多功能性使其成为一个标准化组件，可用于处理应用程序中的大多数图标和头像显示需求。

## Props

`Icon` 组件接受以下 props：

<x-field-group>
  <x-field data-name="icon" data-type="string" data-required="true">
    <x-field-desc markdown>图标的主要标识符。组件会根据字符串的格式智能地确定如何渲染它。它可以是 Iconify 字符串（例如 `mdi:home`）、直接的图像 URL 或用于生成字母头像的简单字符串（例如 “U”）。</x-field-desc>
  </x-field>
  <x-field data-name="size" data-type="number" data-required="false">
    <x-field-desc markdown>以像素为单位，为图标容器设置统一的 `width` 和 `height`。</x-field-desc>
  </x-field>
  <x-field data-name="sx" data-type="BoxProps['sx']" data-required="false">
    <x-field-desc markdown>用于自定义样式的 `sx` prop，与 Material-UI 的系统一致。</x-field-desc>
  </x-field>
  <x-field data-name="..." data-type="AvatarProps" data-required="false">
    <x-field-desc markdown>该组件也接受 Material-UI [Avatar](https://mui.com/material-ui/react-avatar/) 组件支持的任何其他 props，例如 `variant`、`alt` 和 `onClick`。</x-field-desc>
  </x-field>
</x-field-group>

## 用法示例

以下是演示 `Icon` 组件不同使用方式的实际示例。

### Iconify 图标

要显示来自 Iconify 生态系统的图标，请将其唯一的字符串标识符提供给 `icon` prop。该组件将动态加载并渲染相应的 SVG。

```jsx 显示 Iconify 图标 icon=mdi:react
import Icon from '@blocklet/ui-react/lib/Icon';

export default function IconifyExample() {
  return <Icon icon="mdi:react" size={48} />;
}
```

此示例渲染了 Material Design Icons 集合中的 “react” 图标。

### 图像 URL

您可以通过将其 URL 传递给 `icon` prop 来直接渲染图像。该组件将检测 URL 格式，并将其用作 Avatar 内 `<img>` 标签的 `src`。

```jsx 从 URL 渲染图标 icon=mdi:image
import Icon from '@blocklet/ui-react/lib/Icon';

export default function ImageUrlExample() {
  return <Icon icon="https://www.arcblock.io/image-bin/uploads/eb1cf5d60cd85c42362920c49e3768cb.svg" size={48} />;
}
```

### 字母头像

如果 `icon` prop 接收到的字符串既不是有效的 Iconify 图标也不是 URL，它将使用该字符串的第一个字符渲染一个字母头像。这对于用户个人资料的占位符很有用。

```jsx 创建字母头像 icon=mdi:format-letter-case
import Icon from '@blocklet/ui-react/lib/Icon';

export default function LetterAvatarExample() {
  return <Icon icon="Blocklet" size={48} variant="rounded" sx={{ bgcolor: 'primary.main', color: 'primary.contrastText' }} />;
}
```

在这种情况下，组件将显示字母 “B”。请注意 `variant` 和 `sx` props 的使用，它们被直接传递给底层的 Material-UI Avatar。

### 自定义尺寸

`size` prop 提供了一种便捷的方式来控制图标的尺寸。

```jsx 调整图标尺寸 icon=mdi:ruler
import Icon from '@blocklet/ui-react/lib/Icon';

export default function SizingExample() {
  return (
    <div>
      <Icon icon="mdi:home" size={24} />
      <Icon icon="mdi:home" size={32} />
      <Icon icon="mdi:home" size={48} />
    </div>
  );
}
```

此示例展示了以三种不同尺寸渲染的同一个图标。

### 使用 Avatar Props

由于 `Icon` 组件是 Material-UI 的 `Avatar` 的包装器，您可以使用任何 `Avatar` prop 来自定义其外观。例如，您可以使用 `variant` prop 来改变形状。

```jsx 使用 Avatar props 进行自定义 icon=mdi:shape
import Icon from '@blocklet/ui-react/lib/Icon';

export default function AvatarPropsExample() {
  return (
    <div>
      <Icon icon="B" variant="circular" size={48} sx={{ bgcolor: 'secondary.main' }} />
      <Icon icon="L" variant="rounded" size={48} sx={{ bgcolor: 'success.main' }} />
      <Icon icon="T" variant="square" size={48} sx={{ bgcolor: 'info.main' }} />
    </div>
  );
}
```

这演示了如何创建圆形、圆角和方形的头像。