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

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

# Icon

`Icon` 元件是一個基於 Material-UI 的 `Avatar` 元件所建構的靈活工具。它旨在渲染來自多種來源的圖示，包括 [Iconify](https://iconify.design/) 圖示字串、圖片 URL 以及基於字元的「字母頭像」。這種多功能性使其成為一個標準化元件，可滿足應用程式中大多數圖示和頭像的顯示需求。

## 屬性

`Icon` 元件接受以下屬性：

<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` 屬性，與 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/) 元件支援的任何其他屬性，例如 `variant`、`alt` 和 `onClick`。</x-field-desc>
  </x-field>
</x-field-group>

## 使用範例

以下是展示 `Icon` 元件不同使用方式的實際範例。

### Iconify 圖示

要顯示來自 Iconify 生態系統的圖示，請將其唯一的字串識別碼提供給 `icon` 屬性。元件將動態載入並渲染對應的 SVG。

```jsx Displaying an Iconify icon 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` 屬性來直接渲染圖片。元件將偵測 URL 格式，並將其用作 Avatar 內 `<img>` 標籤的 `src`。

```jsx Rendering an icon from a 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` 屬性收到的字串既不是有效的 Iconify 圖示也不是 URL，它將使用字串的第一個字元渲染一個字母頭像。這對於使用者個人資料的預留位置很有用。

```jsx Creating a letter avatar 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` 屬性的使用，它們會直接傳遞給底層的 Material-UI Avatar。

### 自訂尺寸

`size` 屬性提供了一種方便的方式來控制圖示的尺寸。

```jsx Adjusting the icon size 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 屬性

由於 `Icon` 元件是 Material-UI 的 `Avatar` 的封裝，您可以使用任何 `Avatar` 屬性來自訂其外觀。例如，您可以使用 `variant` 屬性來改變形狀。

```jsx Customizing with 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>
  );
}
```

這展示了如何創建圓形、圓角和方形的頭像。