@blocklet/ui-react 3.1.48 → 3.1.49

package/docs/hooks-api.ja.md

@@ -0,0 +1,214 @@
+# Hooks API
+
+このセクションでは、ライブラリ内で利用可能なカスタム React Hook の詳細なリファレンスを提供します。これらのフックは、ステートフルなロジックをカプセル化して再利用するように設計されており、Blocklet 環境内での一般的なタスクやインタラクションを簡素化します。
+
+## useComponentInstalled
+
+このフックは、指定された1つ以上のオプションコンポーネント（DID によって識別される）がインストールされているかどうかをチェックします。これは、他の Blocklet を依存関係として利用する機能を実装するために不可欠です。このフックは、インストールのステータスと、必要に応じてユーザーにインストールを促すために必要な URL を提供します。
+
+### パラメータ
+
+このフックは、以下のプロパティを持つ単一のオブジェクトを受け入れます：
+
+<x-field-group>
+  <x-field data-name="did" data-type="string | string[]" data-required="true">
+    <x-field-desc markdown>チェックするコンポーネントの分散型識別子（DID）または DID の配列。単一の文字列には `;;` で区切られた複数の DID を含めることができます。</x-field-desc>
+  </x-field>
+  <x-field data-name="onInstalled" data-type="function" data-required="false">
+    <x-field-desc markdown>指定されたすべてのコンポーネントがすでにインストールされている場合にトリガーされるオプションのコールバック関数。</x-field-desc>
+  </x-field>
+  <x-field data-name="onError" data-type="function" data-required="false">
+    <x-field-desc markdown>指定された1つ以上のコンポーネントがインストールされていない場合にトリガーされるオプションのコールバック関数。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### 戻り値
+
+インストールの状態と関連データを含むオブジェクトを返します：
+
+<x-field-group>
+  <x-field data-name="optComponents" data-type="array">
+    <x-field-desc markdown>インストールされていないコンポーネントオブジェクトの配列。各オブジェクトには `meta.did`、`storeUrl`、`installUrl` などのメタデータが含まれます。</x-field-desc>
+  </x-field>
+  <x-field data-name="installed" data-type="boolean">
+    <x-field-desc markdown>指定されたすべてのコンポーネントがインストールされ、`blocklet.yml` で定義されている場合は `true`、そうでない場合は `false` となるブール値。</x-field-desc>
+  </x-field>
+  <x-field data-name="installStatus" data-type="object">
+    <x-field-desc markdown>キーがコンポーネントの DID で、値が現在のインストールステータス（例: 'waiting', 'installing'）であるオブジェクト。この状態は `window.postMessage` イベントを介して更新されます。</x-field-desc>
+  </x-field>
+  <x-field data-name="setInstallStatus" data-type="function">
+    <x-field-desc markdown>`installStatus` オブジェクトを手動で更新するためのステートセッター関数。</x-field-desc>
+  </x-field>
+  <x-field data-name="definedInBlockletYML" data-type="boolean">
+    <x-field-desc markdown>コンポーネントが blocklet の設定（`blocklet.yml`）で定義されているかどうかを示すブール値。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### 使用例
+
+以下の例は、依存関係が欠落している場合に `useComponentInstalled` を使用して、機能または `ComponentInstaller` コンポーネントを条件付きでレンダリングする方法を示しています。
+
+```javascript "ComponentFeature.js" icon=logos:javascript
+import React from 'react';
+import { useComponentInstalled, ComponentInstaller } from '@blocklet/ui-react';
+
+const REQUIRED_DID = 'z8ia24z55nve2TSF5m1aZ5322d9f48a43D4a'; // DID の例
+
+function ComponentFeature() {
+  const { installed, optComponents } = useComponentInstalled({ did: REQUIRED_DID });
+
+  if (!installed) {
+    // コンポーネントが存在しない場合は、インストーラー UI をレンダリングします
+    return <ComponentInstaller components={optComponents} />;
+  }
+
+  // インストールされたコンポーネントに依存する機能をレンダリングします
+  return (
+    <div>
+      <h2>My Feature</h2>
+      <p>This feature requires the component with DID: {REQUIRED_DID}</p>
+      {/* ... 機能の実装 ... */}
+    </div>
+  );
+}
+
+export default ComponentFeature;
+```
+
+## useFollow
+
+このフックは、現在認証されているユーザーと、その DID によって指定された別のユーザーとの間のフォロー関係を管理します。フォローおよびアンフォローのための API 呼び出しを処理し、現在のフォロー状況を提供します。
+
+### パラメータ
+
+<x-field-group>
+  <x-field data-name="userDid" data-type="string" data-required="true">
+    <x-field-desc markdown>フォロー状況を確認する対象のユーザープロファイルの DID。</x-field-desc>
+  </x-field>
+  <x-field data-name="t" data-type="function" data-required="true">
+    <x-field-desc markdown>成功またはエラーメッセージを表示するために使用される翻訳関数（例: `react-i18next` 由来のもの）。</x-field-desc>
+  </x-field>
+  <x-field data-name="isMySelf" data-type="boolean" data-required="true">
+    <x-field-desc markdown>`userDid` が現在ログインしているユーザーのものである場合に `true` に設定されるべきブール値。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### 戻り値
+
+以下のプロパティを持つオブジェクトを返します：
+
+<x-field-group>
+  <x-field data-name="followed" data-type="boolean">
+    <x-field-desc markdown>現在のユーザーが `userDid` で指定されたユーザーをフォローしているかどうかを示します。フォローしている場合は `true`、そうでない場合は `false` です。</x-field-desc>
+  </x-field>
+  <x-field data-name="followUser" data-type="function">
+    <x-field-desc markdown>ユーザーをフォローするために呼び出す安定した関数。API リクエストを処理し、成功時に `followed` ステートを更新します。</x-field-desc>
+  </x-field>
+  <x-field data-name="unfollowUser" data-type="function">
+    <x-field-desc markdown>ユーザーのフォローを解除するために呼び出す安定した関数。API リクエストを処理し、成功時に `followed` ステートを更新します。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### 使用例
+
+この例では、関係ステータスに基づいて「フォロー」または「アンフォロー」アクションを表示する `FollowButton` コンポーネントを作成する方法を示します。
+
+```javascript "FollowButton.js" icon=logos:javascript
+import React from 'react';
+import Button from '@mui/material/Button';
+import { useTranslation } from 'react-i18next';
+import { useFollow } from '@blocklet/ui-react/hooks';
+import { useSession } from '@blocklet/did-connect-react';
+
+function FollowButton({ profileDid }) {
+  const { session } = useSession();
+  const { t } = useTranslation();
+  const isMySelf = session?.user?.did === profileDid;
+
+  const { followed, followUser, unfollowUser } = useFollow({
+    userDid: profileDid,
+    t,
+    isMySelf,
+  });
+
+  if (isMySelf) {
+    return null; // 自身のプロフィールにはボタンを表示しない
+  }
+
+  const handleClick = () => {
+    if (followed) {
+      unfollowUser();
+    } else {
+      followUser();
+    }
+  };
+
+  return (
+    <Button variant="contained" onClick={handleClick}>
+      {followed ? t('profile.unfollow') : t('profile.follow')}
+    </Button>
+  );
+}
+
+export default FollowButton;
+```
+
+## useMobile
+
+レスポンシブコンポーネントを作成するためのシンプルなユーティリティフックです。Material-UI の `useMediaQuery` を利用して、現在のビューポートの幅が指定されたブレークポイント未満であるかどうかを判断します。
+
+### パラメータ
+
+<x-field-group>
+  <x-field data-name="key" data-type="number | Breakpoint" data-default="'sm'" data-required="false">
+    <x-field-desc markdown>Material-UI のブレークポイントキー（例: `'xs'`、`'sm'`、`'md'`）または比較対象のピクセル値。画面幅がこの値より小さい場合にフックは `true` を返します。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### 戻り値
+
+`boolean` 値を返します。ビューポートが指定されたブレークポイントより小さい場合は `true`、そうでない場合は `false` です。
+
+### 使用例
+
+このフックは、Material-UI の `ThemeProvider` でラップされたコンポーネントツリー内で使用する必要があります。
+
+```javascript "ResponsiveComponent.js" icon=logos:javascript
+import React from 'react';
+import Typography from '@mui/material/Typography';
+import { ThemeProvider, createTheme } from '@mui/material/styles';
+import { useMobile } from '@blocklet/ui-react/hooks';
+
+// フックを使用するコンポーネント
+function ResponsiveComponent() {
+  const isMobile = useMobile({ key: 'md' }); // 'md' ブレークポイントに対してチェック
+
+  return (
+    <div>
+      {isMobile ? (
+        <Typography variant="h6">Mobile View</Typography>
+      ) : (
+        <Typography variant="h4">Desktop View</Typography>
+      )}
+      <p>Resize your browser window to see the content change.</p>
+    </div>
+  );
+}
+
+// コンポーネントは ThemeProvider でラップする必要があります
+const theme = createTheme();
+
+function App() {
+  return (
+    <ThemeProvider theme={theme}>
+      <ResponsiveComponent />
+    </ThemeProvider>
+  );
+}
+
+export default App;
+```
+
+---
+
+これらのフックを使用することで、最小限のボイラープレートコードで複雑な機能を効率的に実装できます。これらのフックを使用する可能性のあるコンポーネントの詳細については、[コンポーネント](./components.md) のドキュメントを参照してください。

package/docs/hooks-api.md

@@ -0,0 +1,214 @@
+# Hooks API
+
+This section provides a detailed reference for the custom React Hooks available within the library. These hooks are designed to encapsulate and reuse stateful logic, simplifying common tasks and interactions within a Blocklet environment.
+
+## useComponentInstalled
+
+This hook checks whether one or more specified optional components (identified by their DIDs) are installed. It is essential for implementing features that rely on other Blocklets as dependencies. The hook provides the installation status and necessary URLs to prompt the user for installation if required.
+
+### Parameters
+
+The hook accepts a single object with the following properties:
+
+<x-field-group>
+  <x-field data-name="did" data-type="string | string[]" data-required="true">
+    <x-field-desc markdown>The Decentralized Identifier (DID) or an array of DIDs for the component(s) to check. A single string can contain multiple DIDs separated by `;;`.</x-field-desc>
+  </x-field>
+  <x-field data-name="onInstalled" data-type="function" data-required="false">
+    <x-field-desc markdown>An optional callback function that is triggered when all specified components are already installed.</x-field-desc>
+  </x-field>
+  <x-field data-name="onError" data-type="function" data-required="false">
+    <x-field-desc markdown>An optional callback function that is triggered when one or more specified components are not installed.</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### Returns
+
+It returns an object containing the installation state and related data:
+
+<x-field-group>
+  <x-field data-name="optComponents" data-type="array">
+    <x-field-desc markdown>An array of component objects that are not installed. Each object includes metadata such as `meta.did`, `storeUrl`, and `installUrl`.</x-field-desc>
+  </x-field>
+  <x-field data-name="installed" data-type="boolean">
+    <x-field-desc markdown>A boolean value that is `true` if all specified components are installed and defined in the `blocklet.yml`, and `false` otherwise.</x-field-desc>
+  </x-field>
+  <x-field data-name="installStatus" data-type="object">
+    <x-field-desc markdown>An object where keys are component DIDs and values are their current installation status (e.g., 'waiting', 'installing'). This state is updated via `window.postMessage` events.</x-field-desc>
+  </x-field>
+  <x-field data-name="setInstallStatus" data-type="function">
+    <x-field-desc markdown>The state setter function to manually update the `installStatus` object.</x-field-desc>
+  </x-field>
+  <x-field data-name="definedInBlockletYML" data-type="boolean">
+    <x-field-desc markdown>A boolean indicating whether the component is defined in the blocklet's configuration (`blocklet.yml`).</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### Example Usage
+
+The following example demonstrates how to use `useComponentInstalled` to conditionally render a feature or a `ComponentInstaller` component if a dependency is missing.
+
+```javascript "ComponentFeature.js" icon=logos:javascript
+import React from 'react';
+import { useComponentInstalled, ComponentInstaller } from '@blocklet/ui-react';
+
+const REQUIRED_DID = 'z8ia24z55nve2TSF5m1aZ5322d9f48a43D4a'; // Example DID
+
+function ComponentFeature() {
+  const { installed, optComponents } = useComponentInstalled({ did: REQUIRED_DID });
+
+  if (!installed) {
+    // Render the installer UI if the component is not present
+    return <ComponentInstaller components={optComponents} />;
+  }
+
+  // Render the feature that depends on the installed component
+  return (
+    <div>
+      <h2>My Feature</h2>
+      <p>This feature requires the component with DID: {REQUIRED_DID}</p>
+      {/* ... feature implementation ... */}
+    </div>
+  );
+}
+
+export default ComponentFeature;
+```
+
+## useFollow
+
+This hook manages the following relationship between the currently authenticated user and another user specified by their DID. It handles the API calls for following and unfollowing, and provides the current follow status.
+
+### Parameters
+
+<x-field-group>
+  <x-field data-name="userDid" data-type="string" data-required="true">
+    <x-field-desc markdown>The DID of the user profile to check the follow status against.</x-field-desc>
+  </x-field>
+  <x-field data-name="t" data-type="function" data-required="true">
+    <x-field-desc markdown>A translation function used for displaying success or error messages (e.g., from `react-i18next`).</x-field-desc>
+  </x-field>
+  <x-field data-name="isMySelf" data-type="boolean" data-required="true">
+    <x-field-desc markdown>A boolean that should be set to `true` if the `userDid` belongs to the currently logged-in user.</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### Returns
+
+Returns an object with the following properties:
+
+<x-field-group>
+  <x-field data-name="followed" data-type="boolean">
+    <x-field-desc markdown>Indicates if the current user is following the user specified by `userDid`. `true` if following, `false` otherwise.</x-field-desc>
+  </x-field>
+  <x-field data-name="followUser" data-type="function">
+    <x-field-desc markdown>A stable function to call to follow the user. It handles the API request and updates the `followed` state on success.</x-field-desc>
+  </x-field>
+  <x-field data-name="unfollowUser" data-type="function">
+    <x-field-desc markdown>A stable function to call to unfollow the user. It handles the API request and updates the `followed` state on success.</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### Example Usage
+
+This example shows how to create a `FollowButton` component that displays a "Follow" or "Unfollow" action based on the relationship status.
+
+```javascript "FollowButton.js" icon=logos:javascript
+import React from 'react';
+import Button from '@mui/material/Button';
+import { useTranslation } from 'react-i18next';
+import { useFollow } from '@blocklet/ui-react/hooks';
+import { useSession } from '@blocklet/did-connect-react';
+
+function FollowButton({ profileDid }) {
+  const { session } = useSession();
+  const { t } = useTranslation();
+  const isMySelf = session?.user?.did === profileDid;
+
+  const { followed, followUser, unfollowUser } = useFollow({
+    userDid: profileDid,
+    t,
+    isMySelf,
+  });
+
+  if (isMySelf) {
+    return null; // Do not show button on your own profile
+  }
+
+  const handleClick = () => {
+    if (followed) {
+      unfollowUser();
+    } else {
+      followUser();
+    }
+  };
+
+  return (
+    <Button variant="contained" onClick={handleClick}>
+      {followed ? t('profile.unfollow') : t('profile.follow')}
+    </Button>
+  );
+}
+
+export default FollowButton;
+```
+
+## useMobile
+
+A simple utility hook for creating responsive components. It leverages Material-UI's `useMediaQuery` to determine if the current viewport width is below a specified breakpoint.
+
+### Parameters
+
+<x-field-group>
+  <x-field data-name="key" data-type="number | Breakpoint" data-default="'sm'" data-required="false">
+    <x-field-desc markdown>The Material-UI breakpoint key (e.g., `'xs'`, `'sm'`, `'md'`) or a pixel value to check against. The hook returns `true` if the screen width is smaller than this value.</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### Returns
+
+Returns a `boolean` value: `true` if the viewport is smaller than the specified breakpoint, `false` otherwise.
+
+### Example Usage
+
+This hook must be used within a component tree that is wrapped by a Material-UI `ThemeProvider`.
+
+```javascript "ResponsiveComponent.js" icon=logos:javascript
+import React from 'react';
+import Typography from '@mui/material/Typography';
+import { ThemeProvider, createTheme } from '@mui/material/styles';
+import { useMobile } from '@blocklet/ui-react/hooks';
+
+// A component that uses the hook
+function ResponsiveComponent() {
+  const isMobile = useMobile({ key: 'md' }); // Check against the 'md' breakpoint
+
+  return (
+    <div>
+      {isMobile ? (
+        <Typography variant="h6">Mobile View</Typography>
+      ) : (
+        <Typography variant="h4">Desktop View</Typography>
+      )}
+      <p>Resize your browser window to see the content change.</p>
+    </div>
+  );
+}
+
+// The component must be wrapped in a ThemeProvider
+const theme = createTheme();
+
+function App() {
+  return (
+    <ThemeProvider theme={theme}>
+      <ResponsiveComponent />
+    </ThemeProvider>
+  );
+}
+
+export default App;
+```
+
+---
+
+By using these hooks, you can efficiently implement complex features with minimal boilerplate code. For more information on the components that might use these hooks, please see the [Components](./components.md) documentation.

package/docs/hooks-api.zh-TW.md

@@ -0,0 +1,214 @@
+# Hooks API
+
+本節提供該函式庫中可用的自訂 React Hooks 的詳細參考。這些 Hooks 旨在封裝和重用有狀態的邏輯，簡化 Blocklet 環境中的常見任務和互動。
+
+## useComponentInstalled
+
+此 Hook 檢查一個或多個指定的選擇性元件（透過其 DID 識別）是否已安裝。對於實作依賴其他 Blocklet 作為相依項的功能至關重要。此 Hook 提供安裝狀態和必要的 URL，以便在需要時提示使用者進行安裝。
+
+### 參數
+
+此 Hook 接受一個包含以下屬性的物件：
+
+<x-field-group>
+  <x-field data-name="did" data-type="string | string[]" data-required="true">
+    <x-field-desc markdown>要檢查的元件的去中心化識別碼（DID）或 DID 陣列。單一字串可以包含多個以 `;;` 分隔的 DID。</x-field-desc>
+  </x-field>
+  <x-field data-name="onInstalled" data-type="function" data-required="false">
+    <x-field-desc markdown>一個選擇性的回呼函式，當所有指定的元件都已安裝時觸發。</x-field-desc>
+  </x-field>
+  <x-field data-name="onError" data-type="function" data-required="false">
+    <x-field-desc markdown>一個選擇性的回呼函式，當一個或多個指定的元件未安裝時觸發。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### 回傳值
+
+它回傳一個包含安裝狀態和相關資料的物件：
+
+<x-field-group>
+  <x-field data-name="optComponents" data-type="array">
+    <x-field-desc markdown>一個未安裝的元件物件陣列。每個物件包含元資料，如 `meta.did`、`storeUrl` 和 `installUrl`。</x-field-desc>
+  </x-field>
+  <x-field data-name="installed" data-type="boolean">
+    <x-field-desc markdown>一個布林值，如果所有指定的元件都已安裝且在 `blocklet.yml` 中定義，則為 `true`，否則為 `false`。</x-field-desc>
+  </x-field>
+  <x-field data-name="installStatus" data-type="object">
+    <x-field-desc markdown>一個物件，其中鍵是元件的 DID，值是其目前的安裝狀態（例如「waiting」、「installing」）。此狀態透過 `window.postMessage` 事件更新。</x-field-desc>
+  </x-field>
+  <x-field data-name="setInstallStatus" data-type="function">
+    <x-field-desc markdown>用於手動更新 `installStatus` 物件的狀態設定函式。</x-field-desc>
+  </x-field>
+  <x-field data-name="definedInBlockletYML" data-type="boolean">
+    <x-field-desc markdown>一個布林值，表示該元件是否在 blocklet 的設定檔（`blocklet.yml`）中定義。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### 使用範例
+
+以下範例示範如何使用 `useComponentInstalled` 來條件性地渲染一個功能，或在缺少相依項時渲染一個 `ComponentInstaller` 元件。
+
+```javascript "ComponentFeature.js" icon=logos:javascript
+import React from 'react';
+import { useComponentInstalled, ComponentInstaller } from '@blocklet/ui-react';
+
+const REQUIRED_DID = 'z8ia24z55nve2TSF5m1aZ5322d9f48a43D4a'; // 範例 DID
+
+function ComponentFeature() {
+  const { installed, optComponents } = useComponentInstalled({ did: REQUIRED_DID });
+
+  if (!installed) {
+    // 如果元件不存在，則渲染安裝程式 UI
+    return <ComponentInstaller components={optComponents} />;
+  }
+
+  // 渲染依賴於已安裝元件的功能
+  return (
+    <div>
+      <h2>My Feature</h2>
+      <p>This feature requires the component with DID: {REQUIRED_DID}</p>
+      {/* ... 功能實作 ... */}
+    </div>
+  );
+}
+
+export default ComponentFeature;
+```
+
+## useFollow
+
+此 Hook 管理目前已驗證的使用者與另一位由其 DID 指定的使用者之間的追蹤關係。它處理追蹤和取消追蹤的 API 呼叫，並提供目前的追蹤狀態。
+
+### 參數
+
+<x-field-group>
+  <x-field data-name="userDid" data-type="string" data-required="true">
+    <x-field-desc markdown>要檢查追蹤狀態的使用者設定檔的 DID。</x-field-desc>
+  </x-field>
+  <x-field data-name="t" data-type="function" data-required="true">
+    <x-field-desc markdown>用於顯示成功或錯誤訊息的翻譯函式（例如，來自 `react-i18next`）。</x-field-desc>
+  </x-field>
+  <x-field data-name="isMySelf" data-type="boolean" data-required="true">
+    <x-field-desc markdown>如果 `userDid` 屬於目前登入的使用者，則應設定為 `true` 的布林值。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### 回傳值
+
+回傳一個包含以下屬性的物件：
+
+<x-field-group>
+  <x-field data-name="followed" data-type="boolean">
+    <x-field-desc markdown>表示目前使用者是否正在追蹤由 `userDid` 指定的使用者。如果正在追蹤則為 `true`，否則為 `false`。</x-field-desc>
+  </x-field>
+  <x-field data-name="followUser" data-type="function">
+    <x-field-desc markdown>一個穩定的函式，用於呼叫以追蹤使用者。它處理 API 請求並在成功時更新 `followed` 狀態。</x-field-desc>
+  </x-field>
+  <x-field data-name="unfollowUser" data-type="function">
+    <x-field-desc markdown>一個穩定的函式，用於呼叫以取消追蹤使用者。它處理 API 請求並在成功時更新 `followed` 狀態。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### 使用範例
+
+此範例展示如何建立一個 `FollowButton` 元件，根據關係狀態顯示「追蹤」或「取消追蹤」操作。
+
+```javascript "FollowButton.js" icon=logos:javascript
+import React from 'react';
+import Button from '@mui/material/Button';
+import { useTranslation } from 'react-i18next';
+import { useFollow } from '@blocklet/ui-react/hooks';
+import { useSession } from '@blocklet/did-connect-react';
+
+function FollowButton({ profileDid }) {
+  const { session } = useSession();
+  const { t } = useTranslation();
+  const isMySelf = session?.user?.did === profileDid;
+
+  const { followed, followUser, unfollowUser } = useFollow({
+    userDid: profileDid,
+    t,
+    isMySelf,
+  });
+
+  if (isMySelf) {
+    return null; // 不在自己的個人資料頁面上顯示按鈕
+  }
+
+  const handleClick = () => {
+    if (followed) {
+      unfollowUser();
+    } else {
+      followUser();
+    }
+  };
+
+  return (
+    <Button variant="contained" onClick={handleClick}>
+      {followed ? t('profile.unfollow') : t('profile.follow')}
+    </Button>
+  );
+}
+
+export default FollowButton;
+```
+
+## useMobile
+
+一個用於建立響應式元件的簡單工具 Hook。它利用 Material-UI 的 `useMediaQuery` 來判斷目前的視窗寬度是否低於指定的斷點。
+
+### 參數
+
+<x-field-group>
+  <x-field data-name="key" data-type="number | Breakpoint" data-default="'sm'" data-required="false">
+    <x-field-desc markdown>Material-UI 的斷點鍵（例如 `'xs'`、`'sm'`、`'md'`）或一個像素值用於檢查。如果螢幕寬度小於此值，此 Hook 回傳 `true`。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### 回傳值
+
+回傳一個 `boolean` 值：如果視窗小於指定的斷點，則為 `true`，否則為 `false`。
+
+### 使用範例
+
+此 Hook 必須在被 Material-UI `ThemeProvider` 包裹的元件樹中使用。
+
+```javascript "ResponsiveComponent.js" icon=logos:javascript
+import React from 'react';
+import Typography from '@mui/material/Typography';
+import { ThemeProvider, createTheme } from '@mui/material/styles';
+import { useMobile } from '@blocklet/ui-react/hooks';
+
+// 一個使用此 Hook 的元件
+function ResponsiveComponent() {
+  const isMobile = useMobile({ key: 'md' }); // 根據 'md' 斷點進行檢查
+
+  return (
+    <div>
+      {isMobile ? (
+        <Typography variant="h6">Mobile View</Typography>
+      ) : (
+        <Typography variant="h4">Desktop View</Typography>
+      )}
+      <p>Resize your browser window to see the content change.</p>
+    </div>
+  );
+}
+
+// 該元件必須被 ThemeProvider 包裹
+const theme = createTheme();
+
+function App() {
+  return (
+    <ThemeProvider theme={theme}>
+      <ResponsiveComponent />
+    </ThemeProvider>
+  );
+}
+
+export default App;
+```
+
+---
+
+透過使用這些 Hooks，您可以用最少的樣板程式碼高效地實作複雜的功能。有關可能使用這些 Hooks 的元件的更多資訊，請參閱[元件](./components.md)文件。