@blocklet/payment-react 1.20.15 → 1.20.17

package/docs/hooks-use-mobile.ja.md

@@ -0,0 +1,84 @@
+# useMobile
+
+`useMobile` フックは、アプリケーションがモバイルサイズのデバイスで表示されているかどうかを検出するための便利なユーティリティです。Material-UIのブレークポイントシステムを活用することで、Reactロジック内で直接レスポンシブなレイアウトやコンポーネントを作成するのに役立ちます。
+
+## 仕組み
+
+内部では、`useMobile`はMaterial-UIの`useTheme`と`useMediaQuery`フックを使用します。現在の画面幅をテーマで定義されたブレークポイントと比較し、ビューポートが「モバイル」に該当するかどうかを判断します。
+
+## 基本的な使用法
+
+以下は、`useMobile`フックを使用してコンテンツを条件付きでレンダリングする簡単な例です。
+
+```tsx ResponsiveComponent.tsx icon=logos:react
+import { useMobile } from '@blocklet/payment-react';
+import { Typography, Box } from '@mui/material';
+
+function ResponsiveComponent() {
+  const { isMobile, mobileSize } = useMobile();
+
+  return (
+    <Box p={2}>
+      <Typography variant="h5">
+        Responsive Content
+      </Typography>
+      {
+        isMobile ? (
+          <Typography>
+            This is the mobile view. The screen is {mobileSize} or smaller.
+          </Typography>
+        ) : (
+          <Typography>
+            This is the desktop view. The screen is wider than {mobileSize}.
+          </Typography>
+        )
+      }
+    </Box>
+  );
+}
+
+export default ResponsiveComponent;
+```
+
+## パラメータ
+
+`useMobile`フックは、ブレークポイントをカスタマイズするためのオプションのパラメータを受け付けます。
+
+| 名前 | 型 | 説明 |
+| :--- | :--- | :--- |
+| `mobilePoint` | `'md' \| 'sm' \| 'lg' \| 'xl' \| 'xs'` | モバイルの閾値と見なすブレークポイントです。画面幅がこのポイント以下の場合、`isMobile`フラグはtrueになります。デフォルトは`'md'`です。 |
+
+### ブレークポイントのカスタマイズ
+
+異なる値を渡すことで、ブレークポイントを簡単に変更できます。
+
+```tsx CustomBreakpoint.tsx icon=logos:react
+import { useMobile } from '@blocklet/payment-react';
+import { Typography } from '@mui/material';
+
+function CustomBreakpointComponent() {
+  // 'sm' (small) 以下の画面をモバイルと見なす
+  const { isMobile } = useMobile('sm');
+
+  return (
+    <div>
+      {isMobile ? (
+        <Typography>Display for small screens</Typography>
+      ) : (
+        <Typography>Display for medium and larger screens</Typography>
+      )}
+    </div>
+  );
+}
+
+export default CustomBreakpointComponent;
+```
+
+## 戻り値
+
+このフックは、以下のプロパティを持つオブジェクトを返します。
+
+| キー | 型 | 説明 |
+| :--- | :--- | :--- |
+| `isMobile` | `boolean` | 現在のビューポートの幅が指定された`mobilePoint`ブレークポイント以下の場合は`true`、それ以外の場合は`false`です。 |
+| `mobileSize` | `string` | `mobilePoint`ブレークポイントのピクセル幅を表す文字列です (例: `"900px"`)。 |

package/docs/hooks-use-mobile.zh-TW.md

@@ -0,0 +1,84 @@
+# useMobile
+
+`useMobile` hook 是一個方便的實用工具，用於偵測應用程式是否在行動裝置尺寸的裝置上檢視。它利用 Material-UI 的中斷點系統，幫助您直接在 React 邏輯中建立響應式佈局和元件。
+
+## 運作方式
+
+`useMobile` 內部使用 Material-UI 的 `useTheme` 和 `useMediaQuery` hook。它會根據主題定義的中斷點檢查目前的螢幕寬度，以確定視窗是否符合「行動裝置」的條件。
+
+## 基本用法
+
+以下是如何使用 `useMobile` hook 來條件式渲染內容的簡單範例。
+
+```tsx ResponsiveComponent.tsx icon=logos:react
+import { useMobile } from '@blocklet/payment-react';
+import { Typography, Box } from '@mui/material';
+
+function ResponsiveComponent() {
+  const { isMobile, mobileSize } = useMobile();
+
+  return (
+    <Box p={2}>
+      <Typography variant="h5">
+        響應式內容
+      </Typography>
+      {
+        isMobile ? (
+          <Typography>
+            這是行動裝置檢視。螢幕尺寸為 {mobileSize} 或更小。
+          </Typography>
+        ) : (
+          <Typography>
+            這是桌面檢視。螢幕寬度大於 {mobileSize}。
+          </Typography>
+        )
+      }
+    </Box>
+  );
+}
+
+export default ResponsiveComponent;
+```
+
+## 參數
+
+`useMobile` hook 接受一個可選參數來自訂中斷點。
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `mobilePoint` | `'md' \| 'sm' \| 'lg' \| 'xl' \| 'xs'` | 要視為行動裝置閾值的中斷點。如果螢幕寬度在此點或以下，`isMobile` 旗標將為 true。預設為 `'md'`。 |
+
+### 自訂中斷點
+
+您可以透過傳遞不同的值來輕鬆更改中斷點。
+
+```tsx CustomBreakpoint.tsx icon=logos:react
+import { useMobile } from '@blocklet/payment-react';
+import { Typography } from '@mui/material';
+
+function CustomBreakpointComponent() {
+  // 將 'sm' (小) 及以下的螢幕視為行動裝置
+  const { isMobile } = useMobile('sm');
+
+  return (
+    <div>
+      {isMobile ? (
+        <Typography>在小螢幕上顯示</Typography>
+      ) : (
+        <Typography>在中型及更大螢幕上顯示</Typography>
+      )}
+    </div>
+  );
+}
+
+export default CustomBreakpointComponent;
+```
+
+## 回傳值
+
+此 hook 回傳一個包含以下屬性的物件：
+
+| Key | Type | Description |
+| :--- | :--- | :--- |
+| `isMobile` | `boolean` | 如果目前的視窗寬度小於或等於指定的 `mobilePoint` 中斷點，則為 `true`，否則為 `false`。 |
+| `mobileSize` | `string` | 一個字串，表示 `mobilePoint` 中斷點的像素寬度（例如：`"900px"`）。 |

package/docs/hooks-use-mobile.zh.md

@@ -0,0 +1,84 @@
+# useMobile
+
+`useMobile` hook 是一个方便的实用程序，用于检测应用程序是否在移动尺寸的设备上查看。它通过利用 Material-UI 的断点系统，帮助您直接在 React 逻辑中创建响应式布局和组件。
+
+## 工作原理
+
+在内部，`useMobile` 使用了 Material-UI 的 `useTheme` 和 `useMediaQuery` hook。它会根据主题中定义的断点检查当前屏幕宽度，以确定视口是否符合“移动设备”的标准。
+
+## 基本用法
+
+以下是一个如何使用 `useMobile` hook 来条件性渲染内容的简单示例。
+
+```tsx ResponsiveComponent.tsx icon=logos:react
+import { useMobile } from '@blocklet/payment-react';
+import { Typography, Box } from '@mui/material';
+
+function ResponsiveComponent() {
+  const { isMobile, mobileSize } = useMobile();
+
+  return (
+    <Box p={2}>
+      <Typography variant="h5">
+        响应式内容
+      </Typography>
+      {
+        isMobile ? (
+          <Typography>
+            这是移动视图。屏幕尺寸为 {mobileSize} 或更小。
+          </Typography>
+        ) : (
+          <Typography>
+            这是桌面视图。屏幕宽度大于 {mobileSize}。
+          </Typography>
+        )
+      }
+    </Box>
+  );
+}
+
+export default ResponsiveComponent;
+```
+
+## 参数
+
+`useMobile` hook 接受一个可选参数来自定义断点。
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| `mobilePoint` | `'md' \| 'sm' \| 'lg' \| 'xl' \| 'xs'` | 作为移动设备阈值的断点。如果屏幕宽度小于或等于此断点，`isMobile` 标志将为 true。默认为 `'md'`。 |
+
+### 自定义断点
+
+您可以通过传递不同的值来轻松更改断点。
+
+```tsx CustomBreakpoint.tsx icon=logos:react
+import { useMobile } from '@blocklet/payment-react';
+import { Typography } from '@mui/material';
+
+function CustomBreakpointComponent() {
+  // 将 'sm' (小) 尺寸及以下的屏幕视为移动设备
+  const { isMobile } = useMobile('sm');
+
+  return (
+    <div>
+      {isMobile ? (
+        <Typography>为小屏幕显示</Typography>
+      ) : (
+        <Typography>为中等及更大屏幕显示</Typography>
+      )}
+    </div>
+  );
+}
+
+export default CustomBreakpointComponent;
+```
+
+## 返回值
+
+该 hook 返回一个包含以下属性的对象：
+
+| Key | Type | Description |
+| :--- | :--- | :--- |
+| `isMobile` | `boolean` | 如果当前视口宽度小于或等于指定的 `mobilePoint` 断点，则为 `true`，否则为 `false`。 |
+| `mobileSize` | `string` | 一个表示 `mobilePoint` 断点像素宽度的字符串（例如 `“900px”`）。 |

package/docs/hooks-use-subscription.ja.md

@@ -0,0 +1,111 @@
+# useSubscription
+
+`useSubscription` フックは、WebSocket を使用して決済サービスからのリアルタイムイベントを購読する簡単な方法を提供します。接続、サブスクリプション、クリーンアップロジックを処理するため、開発者は `invoice.paid` のようなイベントに対するアプリケーションの反応に集中できます。
+
+これは、ユーザーがページを更新することなく、バックエンドイベントに応じてUIを即座に更新する必要がある、動的なユーザーエクスペリエンスを作成するために不可欠です。
+
+## 仕組み
+
+このフックは、WebSocket 接続管理の複雑さを抽象化します。コンポーネントが `useSubscription` を使用すると、リレーサービスへの永続的な接続が確立されます。次に、指定された特定の `channel` を購読します。フックは自動的にチャネルに名前空間を適用し、`relay:<app-id>:<your-channel>` という形式で最終的なチャネル名を構築します。
+
+バックエンドサービスがそのチャネルにイベントを公開すると、フックのサブスクリプションオブジェクトがイベントを発行し、コンポーネントはそれをリッスンできます。
+
+```d2
+direction: down
+
+react-component: {
+  label: "React コンポーネント"
+  shape: rectangle
+}
+
+use-subscription-hook: {
+  label: "useSubscription フック"
+  shape: rectangle
+}
+
+websocket-server: {
+  label: "WebSocket サーバー"
+  shape: rectangle
+}
+
+backend-service: {
+  label: "バックエンドサービス"
+  shape: rectangle
+}
+
+react-component -> use-subscription-hook: "1. チャネルIDで呼び出し"
+use-subscription-hook -> websocket-server: "2. 接続＆名前空間付きチャネルを購読"
+backend-service -> websocket-server: "3. イベントを公開（例：'invoice.paid'）"
+websocket-server -> use-subscription-hook: "4. イベントをクライアントにプッシュ"
+use-subscription-hook -> react-component: "5. イベントをリスナーに発行"
+react-component -> react-component: "6. UIを更新"
+```
+
+## パラメータ
+
+このフックは、単一の文字列引数を取ります。
+
+| パラメータ | タイプ | 説明 | 必須 |
+| :-------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------ | :------- |
+| `channel` | `string` | リッスンしたいイベントストリームの一意の識別子。**重要**: この文字列には `/`、`.`、`:` などの区切り文字を含めないでください。 | はい |
+
+## 戻り値
+
+このフックは、基盤となる `@arcblock/ws` クライアントライブラリから `subscription` オブジェクトを返します。接続が確立されるまでの間、このオブジェクトは最初に `null` である場合があります。
+
+接続が成功すると、返されたオブジェクトはイベントリスナーを管理するための以下のメソッドを提供します：
+
+- `subscription.on(eventName, handler)`: イベントリスナーをアタッチします。
+- `subscription.off(eventName, handler)`: イベントリスナーを削除します。
+
+## 使用例
+
+以下は、請求書のステータスをリアルタイムで追跡するコンポーネントの例です。バックエンドが請求書のチャネルで `invoice.paid` イベントをブロードキャストすると、コンポーネントのUIが自動的に更新されます。
+
+```tsx Real-time Invoice Status Tracker icon=logos:react
+import { useSubscription } from '@blocklet/payment-react';
+import React, { useState, useEffect } from 'react';
+
+/**
+ * 請求書のステータスを表示し、'invoice.paid' イベントを受信したときに
+ * リアルタイムで更新するコンポーネント。
+ */
+function InvoiceStatusTracker({ invoiceId }) {
+  const [status, setStatus] = useState('pending');
+  // この請求書専用のチャネルを購読する
+  const subscription = useSubscription(invoiceId);
+
+  useEffect(() => {
+    // subscription オブジェクトは WebSocket 接続が確立された後に利用可能になります。
+    if (subscription) {
+      const handlePaymentSuccess = (eventData) => {
+        console.log(`チャネル ${invoiceId} の 'invoice.paid' イベントを受信しました:`, eventData);
+        // イベントに基づいてコンポーネントの状態を更新する
+        setStatus('paid');
+      };
+
+      // 'invoice.paid' イベントのリスナーをアタッチする
+      subscription.on('invoice.paid', handlePaymentSuccess);
+
+      // コンポーネントがアンマウントされるとき、または subscription オブジェクトが変更されたときに
+      // メモリリークを防ぐためにイベントリスナーをクリーンアップすることが重要です。
+      return () => {
+        subscription.off('invoice.paid', handlePaymentSuccess);
+      };
+    }
+    // この effect は、subscription オブジェクト自体が変更された場合に再実行されるべきです。
+  }, [subscription, invoiceId]);
+
+  return (
+    <div>
+      <h2>Invoice Status</h2>
+      <p>ID: {invoiceId}</p>
+      <p>ステータス: <strong>{status.toUpperCase()}</strong></p>
+      {status === 'pending' && <p>支払い確認を待っています...</p>}
+      {status === 'paid' && <p>支払いが確認されました！請求書は決済済みです。</p>}
+    </div>
+  );
+}
+
+export default InvoiceStatusTracker;
+```

package/docs/hooks-use-subscription.zh-TW.md

@@ -0,0 +1,111 @@
+# useSubscription
+
+`useSubscription` hook 提供了一種使用 WebSockets 從支付服務訂閱即時事件的簡單方法。它處理連線、訂閱和清理邏輯，讓您可以專注於應用程式如何對 `invoice.paid` 之類的事件做出反應。
+
+這對於創建動態使用者體驗至關重要，其中 UI 需要即時回應後端事件，而無需使用者刷新頁面。
+
+## 運作方式
+
+此 hook 抽象化了管理 WebSocket 連線的複雜性。當元件使用 `useSubscription` 時，它會建立一個到中繼服務的持久連線。然後它會訂閱您提供的特定 `channel`。此 hook 會自動為您對頻道進行命名空間處理，建構一個格式為 `relay:<app-id>:<your-channel>` 的最終頻道名稱。
+
+當後端服務向該頻道發布事件時，此 hook 的訂閱物件會發出該事件，您的元件可以監聽該事件。
+
+```d2
+direction: down
+
+react-component: {
+  label: "React Component"
+  shape: rectangle
+}
+
+use-subscription-hook: {
+  label: "useSubscription Hook"
+  shape: rectangle
+}
+
+websocket-server: {
+  label: "WebSocket Server"
+  shape: rectangle
+}
+
+backend-service: {
+  label: "Backend Service"
+  shape: rectangle
+}
+
+react-component -> use-subscription-hook: "1. Call with channel ID"
+use-subscription-hook -> websocket-server: "2. Connect & Subscribe to namespaced channel"
+backend-service -> websocket-server: "3. Publish event (e.g., 'invoice.paid')"
+websocket-server -> use-subscription-hook: "4. Push event to client"
+use-subscription-hook -> react-component: "5. Emit event to listener"
+react-component -> react-component: "6. Update UI"
+```
+
+## 參數
+
+此 hook 接受一個字串參數。
+
+| 參數 | 類型 | 描述 | 必要 |
+| :-------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------ | :------- |
+| `channel` | `string` | 您想要監聽的事件流的唯一識別碼。**重要提示**：此字串不得包含 `/`、`.` 或 `:` 等分隔符。 | 是 |
+
+## 返回值
+
+此 hook 從底層的 `@arcblock/ws` 客戶端函式庫返回一個 `subscription` 物件。在建立連線期間，此物件最初可能為 `null`。
+
+一旦連線成功，返回的物件提供了管理事件監聽器的方法：
+
+- `subscription.on(eventName, handler)`：附加一個事件監聽器。
+- `subscription.off(eventName, handler)`：移除一個事件監聽器。
+
+
+## 範例用法
+
+這是一個即時追蹤發票狀態的元件範例。當後端在發票的頻道上廣播 `invoice.paid` 事件時，元件的 UI 會自動更新。
+
+```tsx Real-time Invoice Status Tracker icon=logos:react
+import { useSubscription } from '@blocklet/payment-react';
+import React, { useState, useEffect } from 'react';
+
+/**
+ * 一個顯示發票狀態的元件，並在收到 'invoice.paid' 事件時即時更新。
+ */
+function InvoiceStatusTracker({ invoiceId }) {
+  const [status, setStatus] = useState('pending');
+  // 訂閱此發票專用的頻道
+  const subscription = useSubscription(invoiceId);
+
+  useEffect(() => {
+    // WebSocket 連線建立後，subscription 物件才會可用。
+    if (subscription) {
+      const handlePaymentSuccess = (eventData) => {
+        console.log(`收到頻道 ${invoiceId} 的 'invoice.paid' 事件：`, eventData);
+        // 根據事件更新元件的狀態
+        setStatus('paid');
+      };
+
+      // 附加 'invoice.paid' 事件的監聽器
+      subscription.on('invoice.paid', handlePaymentSuccess);
+
+      // 在元件卸載時清理事件監聽器至關重要
+      // 或在 subscription 物件變更時，以防止記憶體洩漏。
+      return () => {
+        subscription.off('invoice.paid', handlePaymentSuccess);
+      };
+    }
+    // 如果 subscription 物件本身發生變化，此 effect 應該重新執行。
+  }, [subscription, invoiceId]);
+
+  return (
+    <div>
+      <h2>發票狀態</h2>
+      <p>ID：{invoiceId}</p>
+      <p>狀態：<strong>{status.toUpperCase()}</strong></p>
+      {status === 'pending' && <p>等待付款確認...</p>}
+      {status === 'paid' && <p>付款已確認！您的發票已結清。</p>}
+    </div>
+  );
+}
+
+export default InvoiceStatusTracker;
+```

package/docs/hooks-use-subscription.zh.md

@@ -0,0 +1,110 @@
+# useSubscription
+
+`useSubscription` Hook 提供了一种使用 WebSocket 从支付服务订阅实时事件的简单方法。它处理连接、订阅和清理逻辑，让您可以专注于应用程序如何响应像 `invoice.paid` 这样的事件。
+
+这对于创建动态用户体验至关重要，在这种体验中，UI 需要根据后端事件立即更新，而无需用户刷新页面。
+
+## 工作原理
+
+该 Hook 抽象了管理 WebSocket 连接的复杂性。当组件使用 `useSubscription` 时，它会与中继服务建立持久连接。然后，它会订阅您提供的特定 `channel`。该 Hook 会自动为您对通道进行命名空间化，构造一个格式为 `relay:<app-id>:<your-channel>` 的最终通道名称。
+
+当后端服务向该通道发布事件时，Hook 的订阅对象会发出该事件，您的组件可以监听该事件。
+
+```d2
+direction: down
+
+react-component: {
+  label: "React 组件"
+  shape: rectangle
+}
+
+use-subscription-hook: {
+  label: "useSubscription Hook"
+  shape: rectangle
+}
+
+websocket-server: {
+  label: "WebSocket 服务器"
+  shape: rectangle
+}
+
+backend-service: {
+  label: "后端服务"
+  shape: rectangle
+}
+
+react-component -> use-subscription-hook: "1. 使用 channel ID 调用"
+use-subscription-hook -> websocket-server: "2. 连接并订阅命名空间化的 channel"
+backend-service -> websocket-server: "3. 发布事件（例如 'invoice.paid'）"
+websocket-server -> use-subscription-hook: "4. 将事件推送至客户端"
+use-subscription-hook -> react-component: "5. 向监听器发出事件"
+react-component -> react-component: "6. 更新 UI"
+```
+
+## 参数
+
+该 Hook 接受一个字符串参数。
+
+| 参数 | 类型     | 描述                                                                                                                           | 是否必需 |
+| :-------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------ | :------- |
+| `channel`   | `string` | 您想要监听的事件流的唯一标识符。**重要提示**：此字符串不得包含 `/`、`.` 或 `:` 等分隔符。 | 是      |
+
+## 返回值
+
+该 Hook 从底层的 `@arcblock/ws` 客户端库返回一个 `subscription` 对象。在建立连接期间，此对象最初可能为 `null`。
+
+一旦连接成功，返回的对象将提供管理事件监听器的方法：
+
+-   `subscription.on(eventName, handler)`: 附加一个事件监听器。
+-   `subscription.off(eventName, handler)`: 移除一个事件监听器。
+
+
+## 使用示例
+
+以下是一个实时跟踪发票状态的组件示例。当后端在发票的通道上广播 `invoice.paid` 事件时，组件的 UI 会自动更新。
+
+```tsx Real-time Invoice Status Tracker icon=logos:react
+import { useSubscription } from '@blocklet/payment-react';
+import React, { useState, useEffect } from 'react';
+
+/**
+ * 一个显示发票状态并在收到 'invoice.paid' 事件时实时更新的组件。
+ */
+function InvoiceStatusTracker({ invoiceId }) {
+  const [status, setStatus] = useState('pending');
+  // 订阅专用于此发票的通道
+  const subscription = useSubscription(invoiceId);
+
+  useEffect(() => {
+    // WebSocket 连接建立后，subscription 对象才可用。
+    if (subscription) {
+      const handlePaymentSuccess = (eventData) => {
+        console.log(`收到通道 ${invoiceId} 的 'invoice.paid' 事件:`, eventData);
+        // 根据事件更新组件的状态
+        setStatus('paid');
+      };
+
+      // 附加 'invoice.paid' 事件的监听器
+      subscription.on('invoice.paid', handlePaymentSuccess);
+
+      // 在组件卸载或 subscription 对象更改时清理事件监听器至关重要，以防止内存泄漏。
+      return () => {
+        subscription.off('invoice.paid', handlePaymentSuccess);
+      };
+    }
+    // 如果 subscription 对象本身发生变化，此 effect 应重新运行。
+  }, [subscription, invoiceId]);
+
+  return (
+    <div>
+      <h2>Invoice Status</h2>
+      <p>ID: {invoiceId}</p>
+      <p>Status: <strong>{status.toUpperCase()}</strong></p>
+      {status === 'pending' && <p>Waiting for payment confirmation...</p>}
+      {status === 'paid' && <p>Payment confirmed! Your invoice is settled.</p>}
+    </div>
+  );
+}
+
+export default InvoiceStatusTracker;
+```

package/docs/hooks.ja.md

@@ -0,0 +1,14 @@
+# フック
+
+`@blocklet/payment-react` ライブラリは、リアルタイムイベントの処理やさまざまな画面サイズへの適応など、一般的なロジックをカプセル化して簡素化するための一連のカスタムReactフックを提供します。これらのフックを使用すると、最小限の定型コードで高度な機能をコンポーネントに簡単に統合できます。
+
+利用可能なフックを調べて、アプリケーションのインタラクティブ性と応答性を向上させましょう。
+
+<x-cards>
+  <x-card data-title="useSubscription" data-icon="lucide:webhook" data-href="/hooks/use-subscription">
+    'invoice.paid' のような決済サービスからのリアルタイムイベントを購読して、動的で応答性の高いユーザーエクスペリエンスを作成します。
+  </x-card>
+  <x-card data-title="useMobile" data-icon="lucide:smartphone" data-href="/hooks/use-mobile">
+    アプリケーションがモバイルデバイスで表示されているかどうかを検出するためのユーティリティフックで、応答性が高くモバイルフレンドリーなUIの構築に役立ちます。
+  </x-card>
+</x-cards>

package/docs/hooks.zh-TW.md

@@ -0,0 +1,14 @@
+# Hooks
+
+`@blocklet/payment-react` 函式庫提供了一組自訂的 React hooks，用以封裝和簡化常見的邏輯，例如處理即時事件或適應不同的螢幕尺寸。這些 hooks 讓您可以輕鬆地將進階功能整合到您的元件中，只需最少的樣板程式碼。
+
+探索可用的 hooks，以增強您應用程式的互動性和響應能力。
+
+<x-cards>
+  <x-card data-title="useSubscription" data-icon="lucide:webhook" data-href="/hooks/use-subscription">
+    訂閱來自支付服務的即時事件，例如 'invoice.paid'，以創造動態且響應迅速的使用者體驗。
+  </x-card>
+  <x-card data-title="useMobile" data-icon="lucide:smartphone" data-href="/hooks/use-mobile">
+    一個用於偵測應用程式是否在行動裝置上檢視的實用 hook，協助您建構響應式且對行動裝置友善的使用者介面。
+  </x-card>
+</x-cards>

package/docs/hooks.zh.md

@@ -0,0 +1,14 @@
+# Hooks
+
+`@blocklet/payment-react` 库提供了一组自定义 React hooks，用于封装和简化通用逻辑，例如处理实时事件或适应不同的屏幕尺寸。这些 hooks 允许您用最少的样板代码轻松地将高级功能集成到您的组件中。
+
+探索可用的 hooks 以增强应用程序的交互性和响应性。
+
+<x-cards>
+  <x-card data-title="useSubscription" data-icon="lucide:webhook" data-href="/hooks/use-subscription">
+    订阅来自支付服务的实时事件（例如 'invoice.paid'），以创建动态和响应式的用户体验。
+  </x-card>
+  <x-card data-title="useMobile" data-icon="lucide:smartphone" data-href="/hooks/use-mobile">
+    一个用于检测应用程序是否在移动设备上查看的实用程序 hook，可帮助您构建响应式和移动友好的 UI。
+  </x-card>
+</x-cards>