@blocklet/ui-react 3.1.48 → 3.1.50

package/docs/components-user-management.zh-TW.md

@@ -0,0 +1,76 @@
+# 使用者管理
+
+使用者管理套件提供了一系列預先建置的 React 元件，專為處理基本的使用者相關功能而設計。這些元件簡化了在您的應用程式中實現使用者個人資料、會話管理和組織切換的過程，確保提供一致且可靠的使用者體驗。
+
+本節概述了此套件中可用的主要元件。有關詳細的實作指南和 API 參考，請參閱下方連結的特定元件文件。
+
+```d2
+direction: down
+
+User: {
+  shape: c4-person
+}
+
+Application: {
+  label: "Blocklet 應用程式"
+  shape: rectangle
+  grid-columns: 1
+  grid-gap: 100
+
+  UserCenter: {
+    label: "UserCenter\n(個人資料與設定)"
+  }
+
+  UserSessions: {
+    label: "UserSessions\n(登入活動)"
+  }
+
+  OrgsSwitch: {
+    label: "OrgsSwitch\n(團隊情境)"
+  }
+}
+
+User -> Application.UserCenter: "管理個人資料"
+User -> Application.UserSessions: "檢視會話"
+User -> Application.OrgsSwitch: "切換組織"
+```
+
+## 核心元件
+
+此套件由幾個關鍵元件組成，每個元件都處理使用者管理的特定方面。
+
+<x-cards>
+  <x-card data-title="UserCenter" data-icon="lucide:user-cog" data-href="/components/user-management/user-center">
+    一個用於顯示和管理使用者個人資料的全面元件。它包含處理使用者設定、通行證管理以及如追蹤其他使用者等社交互動的功能。
+  </x-card>
+  <x-card data-title="UserSessions" data-icon="lucide:smartphone-nfc" data-href="/components/user-management/user-sessions">
+    一個注重安全性的元件，允許使用者查看和管理他們在不同裝置上的有效和過去的登入會話，從而增強帳戶安全性。
+  </x-card>
+</x-cards>
+
+### 組織切換
+
+`OrgsSwitch` 元件為屬於多個組織的使用者提供了一個下拉式選單介面。它允許無縫的情境切換，這對於具有團隊或多租戶功能的應用程式至關重要。
+
+**主要功能：**
+
+*   **目前組織顯示：**清楚地顯示使用者目前的組織情境。
+*   **組織列表：**列出使用者可以切換的所有可用組織，並具備無限滾動功能以提升效能。
+*   **搜尋功能：**包含一個搜尋欄，可快速篩選和尋找特定組織。
+*   **建立與導覽：**提供建立新組織的選項，以及一個連結到管理所有組織的專屬頁面。
+
+### 用於使用者互動的 Hooks
+
+為方便開發社交功能，此函式庫還包含自訂的 hooks 和 contexts，用以抽象化複雜的邏輯。
+
+*   **`useFollow` hook**：此 hook 管理追蹤和取消追蹤其他使用者的完整邏輯。它處理 API 請求和狀態變更，並返回目前的追蹤狀態（`followed`）以及 `followUser` 和 `unfollowUser` 函式。
+*   **`UserFollowersProvider` context**：對於需要在多個元件中存取追蹤狀態的應用程式，此提供者會包覆您的元件樹的一部分，並透過 `useUserFollowersContext` hook 提供追蹤狀態和操作。
+
+## 總結
+
+這套元件為任何使用此函式庫建置的應用程式提供了強健使用者管理的必要建構區塊。透過使用這些元件，您可以加速開發，並確保您的應用程式遵循使用者帳戶管理和安全性的最佳實踐。
+
+有關詳細的實作指南，請繼續參閱特定元件的文件。
+
+*   **下一步：** [UserCenter](./components-user-management-user-center.md)
+*   **另請參閱：** [UserSessions](./components-user-management-user-sessions.md)

package/docs/components-user-management.zh.md

@@ -0,0 +1,76 @@
+# 用户管理
+
+用户管理套件提供了一系列预构建的 React 组件，旨在处理与用户相关的基本功能。这些组件简化了在您的应用中实现用户个人资料、会话管理和组织切换的过程，确保了用户体验的一致性和可靠性。
+
+本节概述了该套件中可用的主要组件。有关详细的实现指南和 API 参考，请参阅下方链接的特定组件文档。
+
+```d2
+direction: down
+
+User: {
+  shape: c4-person
+}
+
+Application: {
+  label: "Blocklet 应用"
+  shape: rectangle
+  grid-columns: 1
+  grid-gap: 100
+
+  UserCenter: {
+    label: "UserCenter\n（个人资料与设置）"
+  }
+
+  UserSessions: {
+    label: "UserSessions\n（登录活动）"
+  }
+
+  OrgsSwitch: {
+    label: "OrgsSwitch\n（团队上下文）"
+  }
+}
+
+User -> Application.UserCenter: "管理个人资料"
+User -> Application.UserSessions: "查看会话"
+User -> Application.OrgsSwitch: "切换组织"
+```
+
+## 核心组件
+
+该套件由几个关键组件组成，每个组件都针对用户管理的特定方面。
+
+<x-cards>
+  <x-card data-title="UserCenter" data-icon="lucide:user-cog" data-href="/components/user-management/user-center">
+    一个用于显示和管理用户个人资料的综合性组件。它包含处理用户设置、通行证管理以及关注其他用户等社交互动的功能。
+  </x-card>
+  <x-card data-title="UserSessions" data-icon="lucide:smartphone-nfc" data-href="/components/user-management/user-sessions">
+    一个注重安全的组件，允许用户查看和管理他们在不同设备上的活动和历史登录会话，从而增强账户安全性。
+  </x-card>
+</x-cards>
+
+### 组织切换
+
+`OrgsSwitch` 组件为属于多个组织的用户提供了一个下拉菜单界面。它支持无缝的上下文切换，这对于具有基于团队或多租户功能的应用至关重要。
+
+**主要功能：**
+
+*   **当前组织显示：** 清晰地显示用户当前的组织上下文。
+*   **组织列表：** 列出用户可以切换到的所有可用组织，并支持无限滚动以提高性能。
+*   **搜索功能：** 包含一个搜索栏，用于快速筛选和查找特定组织。
+*   **创建与导航：** 提供创建新组织的选项，以及一个用于管理所有组织的专用页面链接。
+
+### 用于用户交互的钩子 (Hooks)
+
+为便于开发社交功能，该库还包含了自定义钩子 (hooks) 和上下文 (contexts)，用以抽象复杂的逻辑。
+
+*   **`useFollow` 钩子 (hook)**：此钩子管理关注和取消关注其他用户的完整逻辑。它处理 API 请求和状态变更，返回当前的关注状态（`followed`）以及 `followUser` 和 `unfollowUser` 函数。
+*   **`UserFollowersProvider` 上下文 (context)**：对于需要在多个组件之间访问关注状态的应用，此提供程序 (provider) 会包装您的组件树的一部分，并通过 `useUserFollowersContext` 钩子 (hook) 使关注状态和操作可用。
+
+## 总结
+
+这套组件为任何使用该库构建的应用提供了实现强大用户管理的必要构建块。通过使用这些组件，您可以加速开发，并确保您的应用遵循用户账户管理和安全方面的最佳实践。
+
+有关详细的实现指南，请继续阅读特定组件的文档。
+
+*   **下一步：** [UserCenter](./components-user-management-user-center.md)
+*   **另请参阅：** [UserSessions](./components-user-management-user-sessions.md)

package/docs/components-utilities-icon.ja.md

@@ -0,0 +1,106 @@
+# 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>
+  );
+}
+```
+
+これは、円形、角丸、四角形のアバターを作成する方法を示しています。

package/docs/components-utilities-icon.md

@@ -0,0 +1,106 @@
+# Icon
+
+The `Icon` component is a flexible utility built upon Material-UI's `Avatar` component. It is designed to render icons from multiple sources, including [Iconify](https://iconify.design/) icon strings, image URLs, and character-based "letter avatars". This versatility makes it a standardized component for handling most icon and avatar display needs within an application.
+
+## Props
+
+The `Icon` component accepts the following props:
+
+<x-field-group>
+  <x-field data-name="icon" data-type="string" data-required="true">
+    <x-field-desc markdown>The primary identifier for the icon. The component intelligently determines how to render it based on the string's format. It can be an Iconify string (e.g., `mdi:home`), a direct image URL, or a simple string to generate a letter avatar (e.g., "U").</x-field-desc>
+  </x-field>
+  <x-field data-name="size" data-type="number" data-required="false">
+    <x-field-desc markdown>Sets a uniform `width` and `height` for the icon container in pixels.</x-field-desc>
+  </x-field>
+  <x-field data-name="sx" data-type="BoxProps['sx']" data-required="false">
+    <x-field-desc markdown>The `sx` prop for custom styling, consistent with Material-UI's system.</x-field-desc>
+  </x-field>
+  <x-field data-name="..." data-type="AvatarProps" data-required="false">
+    <x-field-desc markdown>The component also accepts any other props supported by the Material-UI [Avatar](https://mui.com/material-ui/react-avatar/) component, such as `variant`, `alt`, and `onClick`.</x-field-desc>
+  </x-field>
+</x-field-group>
+
+## Usage Examples
+
+Here are practical examples demonstrating the different ways to use the `Icon` component.
+
+### Iconify Icon
+
+To display an icon from the Iconify ecosystem, provide its unique string identifier to the `icon` prop. The component will dynamically load and render the corresponding 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} />;
+}
+```
+
+This example renders the "react" icon from the Material Design Icons collection.
+
+### Image URL
+
+You can render an image directly by passing its URL to the `icon` prop. The component will detect the URL format and use it as the `src` for an `<img>` tag within the Avatar.
+
+```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} />;
+}
+```
+
+### Letter Avatar
+
+If the `icon` prop receives a string that is neither a valid Iconify icon nor a URL, it will render a letter avatar using the first character of the string. This is useful for user profile placeholders.
+
+```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' }} />;
+}
+```
+
+In this case, the component will display the letter "B". Note the use of the `variant` and `sx` props, which are passed directly to the underlying Material-UI Avatar.
+
+### Custom Size
+
+The `size` prop provides a convenient way to control the icon's dimensions.
+
+```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>
+  );
+}
+```
+
+This example shows the same icon rendered at three different sizes.
+
+### Using Avatar Props
+
+Since the `Icon` component is a wrapper around Material-UI's `Avatar`, you can use any `Avatar` prop to customize its appearance. For instance, you can change the shape using the `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>
+  );
+}
+```
+
+This demonstrates how to create circular, rounded, and square avatars.

package/docs/components-utilities-icon.zh-TW.md

@@ -0,0 +1,106 @@
+# 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>
+  );
+}
+```
+
+這展示了如何創建圓形、圓角和方形的頭像。

package/docs/components-utilities-icon.zh.md

@@ -0,0 +1,106 @@
+# 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>
+  );
+}
+```
+
+这演示了如何创建圆形、圆角和方形的头像。