@blocklet/ui-react/docs/components-utilities-icon.ja.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>Material-UI のシステムと一貫性のあるカスタムスタイリングのための `sx` prop。</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 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` prop に渡すことで、画像を直接レンダリングできます。コンポーネントは 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` prop が有効な 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` prop の使用に注意してください。これらは基盤となる Material-UI Avatar に直接渡されます。

### カスタムサイズ

`size` prop を使用すると、アイコンの寸法を簡単に制御できます。

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

この例では、同じアイコンを3つの異なるサイズでレンダリングしています。

### Avatar Props の使用

`Icon` コンポーネントは Material-UI の `Avatar` のラッパーであるため、任意の `Avatar` prop を使用してその外観をカスタマイズできます。たとえば、`variant` prop を使用して形状を変更できます。

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

これは、円形、角丸、四角形のアバターを作成する方法を示しています。