@blocklet/ui-react 3.1.47 → 3.1.49

package/docs/components-component-management-blocklet-studio.ja.md

@@ -0,0 +1,194 @@
+# BlockletStudio
+
+`BlockletStudio`コンポーネントは、ブロックレットリソースの公開と管理のための、効率的で埋め込み可能なユーザーインターフェースを提供します。これは、指定されたブロックレットサービスから専用の公開インターフェースを読み込むフルページの`iframe`をレンダリングすることで動作します。これにより、アプリケーションはUIをゼロから構築することなく、一貫性のある強力なリソース管理体験を提供できます。
+
+ホストアプリケーションと`BlockletStudio` iframe間の通信は、`window.postMessage` APIを使用して安全に処理され、アップロード、リリース、接続などのイベントに対するコールバックを可能にします。
+
+## 使用例
+
+`BlockletStudio`を統合するには、その可視性状態を（例：`useState`で）管理する必要があります。iframeの読み込みには時間がかかる場合があるため、ユーザーにローディングインジケーターを表示することが推奨されます。`onOpened`コールバックを使用してiframeコンテンツの準備ができたことを通知し、その時点でローディングインジケーターを非表示にすることができます。
+
+次の例は、`BlockletStudio`ダイアログを開き、ローディング状態を管理するボタンを実装する方法を示しています。
+
+```tsx icon=logos:react title="Exporter.tsx"
+import { Icon } from '@iconify-icon/react';
+import ArrowUp from '@iconify-icons/tabler/arrow-big-up-line';
+import { Box, IconButton, CircularProgress as Spinner, svgIconClasses } from '@mui/material';
+import { useState } from 'react';
+import { BlockletStudio } from '@arcblock/ux-react';
+
+// スタジオサービスを提供するブロックレットのDID。
+const AI_STUDIO_COMPONENT_DID = 'z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9';
+
+export default function Exporter() {
+  const [showCreateResource, setShowCreateResource] = useState(false);
+  const [opening, setOpening] = useState(false);
+
+  const handleShowDialog = () => {
+    setOpening(true);
+    setShowCreateResource(true);
+  };
+
+  return (
+    <>
+      <IconButton
+        sx={{
+          position: 'relative',
+          minWidth: 40,
+          minHeight: 40,
+          borderRadius: '100%',
+          [`.${svgIconClasses.root}`]: {
+            color: 'text.secondary',
+          },
+        }}
+        onClick={handleShowDialog}>
+        {opening ? <Spinner size={16} /> : <Box component={Icon} icon={ArrowUp} style={{ fontSize: 24 }} />}
+      </IconButton>
+      <BlockletStudio
+        open={showCreateResource}
+        setOpen={setShowCreateResource}
+        onOpened={() => setOpening(false)}
+        componentDid={AI_STUDIO_COMPONENT_DID}
+        mode="dialog"
+        title="Demo Project"
+        description="This is a demo project for the 'aigne' blocklet."
+        note='Please review all resources and components before publishing.'
+        introduction="Welcome to the resource publisher."
+        tenantScope="test-tenant-scope-id-2"
+        resourcesParams={{ name: 'test-project', extra: true }}
+        dependentComponentsMode="readonly"
+        componentsTitle="Required Components"
+        resourcesTitle="Add Project Files"
+        onConnected={() => alert('Connected')}
+        onUploaded={() => alert('Uploaded')}
+        onReleased={() => alert('Released')}
+        components={[
+          { did: 'z8ia3xzq2tMq8CRHfaXj1BTYJyYnEcHbqP8cJ', included: true, required: true },
+          { did: 'z2qZyjnsRffFtn2PDnDwDHTRbAu53RpKqDtFZ', included: true, required: false },
+        ]}
+        resources={{
+          'z8iZpog7mcgcgBZzTiXJCWESvmnRrQmnd3XBB': [
+            'template-448698592710885376',
+            'template-448696391418511360',
+          ],
+        }}
+      />
+    </>
+  );
+}
+```
+
+## Props
+
+`BlockletStudio`コンポーネントは、その動作と外観を制御するために以下のpropsを受け入れます。
+
+<x-field-group>
+  <x-field data-name="open" data-type="boolean" data-required="true">
+    <x-field-desc markdown>`BlockletStudio` iframeの可視性を制御します。`true`に設定すると表示され、`false`に設定すると非表示になります。</x-field-desc>
+  </x-field>
+  <x-field data-name="setOpen" data-type="(open: boolean) => void" data-required="true">
+    <x-field-desc markdown>`BlockletStudio`が閉じることを要求するために使用するコールバック関数。通常、この関数は`open` propに関連付けられた状態変数を`false`に設定します。</x-field-desc>
+  </x-field>
+  <x-field data-name="componentDid" data-type="string" data-required="true">
+    <x-field-desc markdown>リソース公開サービスを提供するブロックレットの分散型識別子（DID）。これにより、どのスタジオインターフェースが読み込まれるかが決まります。</x-field-desc>
+  </x-field>
+  <x-field data-name="onOpened" data-type="() => void" data-required="false">
+    <x-field-desc markdown>`BlockletStudio` iframeの読み込みが完了し、ユーザーが操作できる状態になったときに実行されるオプションのコールバック関数。</x-field-desc>
+  </x-field>
+  <x-field data-name="onUploaded" data-type="(data: unknown) => void" data-required="false">
+    <x-field-desc markdown>ユーザーが新しいリソースのアップロードに成功した後にトリガーされるオプションのコールバック関数。`data`パラメータには、アップロードされたアイテムに関するメタデータが含まれます。</x-field-desc>
+  </x-field>
+  <x-field data-name="onReleased" data-type="(data: unknown) => void" data-required="false">
+    <x-field-desc markdown>ユーザーがコンポーネントの新しいリリースを公開した後にトリガーされるオプションのコールバック関数。`data`パラメータには、新しいリリースに関する情報が含まれます。</x-field-desc>
+  </x-field>
+  <x-field data-name="onConnected" data-type="(data: unknown) => void" data-required="false">
+    <x-field-desc markdown>ユーザーがリソースまたはコンポーネントを接続した後にトリガーされるオプションのコールバック関数。</x-field-desc>
+  </x-field>
+  <x-field data-name="tenantScope" data-type="string" data-required="false">
+    <x-field-desc markdown>リソースを特定のテナントにスコープするためのオプションの文字列。これは、マルチテナント環境でのデータ分離を保証するために使用できます。</x-field-desc>
+  </x-field>
+  <x-field data-name="resourcesParams" data-type="Record<string, any>" data-required="false" data-default="{}">
+    <x-field-desc markdown>ブロックレットのリソース取得APIエンドポイントに渡されるクエリパラメータを含むオブジェクト。これにより、リソースの動的なフィルタリングが可能になります。</x-field-desc>
+  </x-field>
+  <x-field data-name="mode" data-type="string" data-required="false" data-default='"dialog"'>
+    <x-field-desc markdown>スタジオインターフェースの表示モードを決定します。デフォルトは`'dialog'`です。</x-field-desc>
+  </x-field>
+  <x-field data-name="title" data-type="string" data-required="false">
+    <x-field-desc markdown>スタジオインターフェースの上部に表示されるオプションのタイトル。</x-field-desc>
+  </x-field>
+  <x-field data-name="logo" data-type="string" data-required="false">
+    <x-field-desc markdown>スタジオインターフェースに表示されるロゴのオプションのURL。</x-field-desc>
+  </x-field>
+  <x-field data-name="description" data-type="string" data-required="false">
+    <x-field-desc markdown>スタジオUIに表示される簡単な説明を提供するオプションの文字列。</x-field-desc>
+  </x-field>
+  <x-field data-name="introduction" data-type="string" data-required="false">
+    <x-field-desc markdown>スタジオUIに表示される、より詳細な紹介のためのオプションの文字列。</x-field-desc>
+  </x-field>
+  <x-field data-name="note" data-type="string" data-required="false">
+    <x-field-desc markdown>ユーザーに注意や重要なメッセージを表示するためのオプションの文字列。</x-field-desc>
+  </x-field>
+  <x-field data-name="componentsTitle" data-type="string" data-required="false">
+    <x-field-desc markdown>コンポーネントセクションのタイトルをカスタマイズするためのオプションの文字列。</x-field-desc>
+  </x-field>
+  <x-field data-name="resourcesTitle" data-type="string" data-required="false">
+    <x-field-desc markdown>リソースセクションのタイトルをカスタマイズするためのオプションの文字列。</x-field-desc>
+  </x-field>
+  <x-field data-name="components" data-type="Record<string, unknown>[]" data-required="false" data-default="[]">
+    <x-field-desc markdown>スタジオでデフォルトで事前選択されるべきコンポーネントを表すオブジェクトの配列。</x-field-desc>
+  </x-field>
+  <x-field data-name="resources" data-type="Record<string, unknown>" data-required="false" data-default="{}">
+    <x-field-desc markdown>スタジオでデフォルトで事前選択されるべきリソースを表すオブジェクト。</x-field-desc>
+  </x-field>
+  <x-field data-name="dependentComponentsMode" data-type="'auto' | 'readonly'" data-required="false">
+    <x-field-desc markdown>依存コンポーネントの動作を制御します。`'readonly'`モードでは、ユーザーは選択されたリソースの依存関係として自動的に含まれるコンポーネントの選択を解除できません。</x-field-desc>
+  </x-field>
+  <x-field data-name="style" data-type="React.CSSProperties" data-required="false" data-default="{}">
+    <x-field-desc markdown>`iframe`要素にカスタムCSSスタイルを適用するためのオブジェクト。</x-field-desc>
+  </x-field>
+  <x-field data-name="zIndex" data-type="number" data-required="false" data-default="9999">
+    <x-field-desc markdown>`iframe`要素のz-index CSSプロパティ。スタック順序を制御します。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+## 依存コンポーネント
+
+`BlockletStudio`にリソースAPIを提供するブロックレットは、リソースデータ内で直接コンポーネントの依存関係を指定できます。ユーザーが`dependentComponents`をリストしているリソースを選択すると、`BlockletStudio`はUIでそれらのコンポーネントを自動的に選択します。
+
+この機能は、必要なすべての依存関係が自動的に含まれるようにすることで、ユーザーエクスペリエンスを簡素化します。
+
+これを実装するには、ブロックレットのリソースAPIは、必要なコンポーネントのDIDを含む`dependentComponents`配列を返す必要があります。
+
+### APIレスポンス例
+
+以下は、リソースAPIエンドポイントからのJSONレスポンスの例です。「Application」および「Tool」リソースは、それぞれのコンポーネント依存関係を宣言しています。
+
+```json 依存関係を含むAPIレスポンス
+{
+  "resources": [
+    {
+      "id": "application-448698592710885376",
+      "name": "My App (as Application)",
+      "dependentComponents": [
+        "error-did",
+        "z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9",
+        "z2qZyjnsRffFtn2PDnDwDHTRbAu53RpKqDtFZ",
+        "z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk"
+      ]
+    },
+    {
+      "id": "tool-448698592710885376",
+      "name": "My App (as Tool)",
+      "dependentComponents": ["error-did", "z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk"]
+    },
+    {
+      "id": "template-448698592710885376",
+      "name": "My App (as Template)"
+    }
+  ]
+}
+```
+
+## 概要
+
+`BlockletStudio`コンポーネントは、リソースとコンポーネントの管理をアプリケーションに直接統合するための、強力で便利な方法を提供します。`iframe`と明確なpropsセットを活用することで、開発を簡素化しつつ、一貫したユーザーエクスペリエンスを提供します。依存関係管理に関する関連機能については、[ComponentInstaller](./components-component-management-component-installer.md)のドキュメントも参照してください。

package/docs/components-component-management-blocklet-studio.md

@@ -0,0 +1,194 @@
+# BlockletStudio
+
+The `BlockletStudio` component provides a streamlined, embeddable user interface for publishing and managing blocklet resources. It operates by rendering a full-page `iframe` that loads a dedicated publishing interface from a specified blocklet service. This allows your application to offer a consistent and powerful resource management experience without needing to build the UI from scratch.
+
+Communication between the host application and the `BlockletStudio` iframe is handled securely using the `window.postMessage` API, enabling callbacks for events like uploads, releases, and connections.
+
+## Usage Example
+
+To integrate `BlockletStudio`, you need to manage its visibility state (e.g., with `useState`). Since the iframe may take a moment to load, it is recommended to display a loading indicator to the user. The `onOpened` callback can be used to signal that the iframe content is ready, at which point the loading indicator can be hidden.
+
+The following example demonstrates how to implement a button that opens the `BlockletStudio` dialog and manages a loading state.
+
+```tsx icon=logos:react title="Exporter.tsx"
+import { Icon } from '@iconify-icon/react';
+import ArrowUp from '@iconify-icons/tabler/arrow-big-up-line';
+import { Box, IconButton, CircularProgress as Spinner, svgIconClasses } from '@mui/material';
+import { useState } from 'react';
+import { BlockletStudio } from '@arcblock/ux-react';
+
+// The DID of the blocklet that provides the studio service.
+const AI_STUDIO_COMPONENT_DID = 'z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9';
+
+export default function Exporter() {
+  const [showCreateResource, setShowCreateResource] = useState(false);
+  const [opening, setOpening] = useState(false);
+
+  const handleShowDialog = () => {
+    setOpening(true);
+    setShowCreateResource(true);
+  };
+
+  return (
+    <>
+      <IconButton
+        sx={{
+          position: 'relative',
+          minWidth: 40,
+          minHeight: 40,
+          borderRadius: '100%',
+          [`.${svgIconClasses.root}`]: {
+            color: 'text.secondary',
+          },
+        }}
+        onClick={handleShowDialog}>
+        {opening ? <Spinner size={16} /> : <Box component={Icon} icon={ArrowUp} style={{ fontSize: 24 }} />}
+      </IconButton>
+      <BlockletStudio
+        open={showCreateResource}
+        setOpen={setShowCreateResource}
+        onOpened={() => setOpening(false)}
+        componentDid={AI_STUDIO_COMPONENT_DID}
+        mode="dialog"
+        title="Demo Project"
+        description="This is a demo project for the 'aigne' blocklet."
+        note='Please review all resources and components before publishing.'
+        introduction="Welcome to the resource publisher."
+        tenantScope="test-tenant-scope-id-2"
+        resourcesParams={{ name: 'test-project', extra: true }}
+        dependentComponentsMode="readonly"
+        componentsTitle="Required Components"
+        resourcesTitle="Add Project Files"
+        onConnected={() => alert('Connected')}
+        onUploaded={() => alert('Uploaded')}
+        onReleased={() => alert('Released')}
+        components={[
+          { did: 'z8ia3xzq2tMq8CRHfaXj1BTYJyYnEcHbqP8cJ', included: true, required: true },
+          { did: 'z2qZyjnsRffFtn2PDnDwDHTRbAu53RpKqDtFZ', included: true, required: false },
+        ]}
+        resources={{
+          'z8iZpog7mcgcgBZzTiXJCWESvmnRrQmnd3XBB': [
+            'template-448698592710885376',
+            'template-448696391418511360',
+          ],
+        }}
+      />
+    </>
+  );
+}
+```
+
+## Props
+
+The `BlockletStudio` component accepts the following props to control its behavior and appearance.
+
+<x-field-group>
+  <x-field data-name="open" data-type="boolean" data-required="true">
+    <x-field-desc markdown>Controls the visibility of the `BlockletStudio` iframe. Set to `true` to display it, and `false` to hide it.</x-field-desc>
+  </x-field>
+  <x-field data-name="setOpen" data-type="(open: boolean) => void" data-required="true">
+    <x-field-desc markdown>A callback function used by `BlockletStudio` to request being closed. Typically, this function will set the state variable associated with the `open` prop to `false`.</x-field-desc>
+  </x-field>
+  <x-field data-name="componentDid" data-type="string" data-required="true">
+    <x-field-desc markdown>The Decentralized Identifier (DID) of the blocklet that provides the resource publishing service. This determines which studio interface is loaded.</x-field-desc>
+  </x-field>
+  <x-field data-name="onOpened" data-type="() => void" data-required="false">
+    <x-field-desc markdown>An optional callback function that is executed when the `BlockletStudio` iframe has finished loading and is ready for user interaction.</x-field-desc>
+  </x-field>
+  <x-field data-name="onUploaded" data-type="(data: unknown) => void" data-required="false">
+    <x-field-desc markdown>An optional callback function that is triggered after a user successfully uploads a new resource. The `data` parameter contains metadata about the uploaded item.</x-field-desc>
+  </x-field>
+  <x-field data-name="onReleased" data-type="(data: unknown) => void" data-required="false">
+    <x-field-desc markdown>An optional callback function that is triggered after a user publishes a new release of a component. The `data` parameter contains information about the new release.</x-field-desc>
+  </x-field>
+  <x-field data-name="onConnected" data-type="(data: unknown) => void" data-required="false">
+    <x-field-desc markdown>An optional callback function that is triggered after a user connects a resource or component.</x-field-desc>
+  </x-field>
+  <x-field data-name="tenantScope" data-type="string" data-required="false">
+    <x-field-desc markdown>An optional string to scope the resources to a specific tenant. This can be used to ensure data isolation in a multi-tenant environment.</x-field-desc>
+  </x-field>
+  <x-field data-name="resourcesParams" data-type="Record<string, any>" data-required="false" data-default="{}">
+    <x-field-desc markdown>An object containing query parameters to be passed to the blocklet's resource-fetching API endpoint. This allows for dynamic filtering of resources.</x-field-desc>
+  </x-field>
+  <x-field data-name="mode" data-type="string" data-required="false" data-default='"dialog"'>
+    <x-field-desc markdown>Determines the display mode of the studio interface. The default is `'dialog'`.</x-field-desc>
+  </x-field>
+  <x-field data-name="title" data-type="string" data-required="false">
+    <x-field-desc markdown>An optional title to be displayed at the top of the studio interface.</x-field-desc>
+  </x-field>
+  <x-field data-name="logo" data-type="string" data-required="false">
+    <x-field-desc markdown>An optional URL for a logo to be displayed in the studio interface.</x-field-desc>
+  </x-field>
+  <x-field data-name="description" data-type="string" data-required="false">
+    <x-field-desc markdown>An optional string providing a short description, displayed in the studio UI.</x-field-desc>
+  </x-field>
+  <x-field data-name="introduction" data-type="string" data-required="false">
+    <x-field-desc markdown>An optional string for a more detailed introduction, displayed in the studio UI.</x-field-desc>
+  </x-field>
+  <x-field data-name="note" data-type="string" data-required="false">
+    <x-field-desc markdown>An optional string to display a note or important message to the user.</x-field-desc>
+  </x-field>
+  <x-field data-name="componentsTitle" data-type="string" data-required="false">
+    <x-field-desc markdown>An optional string to customize the title of the components section.</x-field-desc>
+  </x-field>
+  <x-field data-name="resourcesTitle" data-type="string" data-required="false">
+    <x-field-desc markdown>An optional string to customize the title of the resources section.</x-field-desc>
+  </x-field>
+  <x-field data-name="components" data-type="Record<string, unknown>[]" data-required="false" data-default="[]">
+    <x-field-desc markdown>An array of objects representing components that should be pre-selected by default in the studio.</x-field-desc>
+  </x-field>
+  <x-field data-name="resources" data-type="Record<string, unknown>" data-required="false" data-default="{}">
+    <x-field-desc markdown>An object representing resources that should be pre-selected by default in the studio.</x-field-desc>
+  </x-field>
+  <x-field data-name="dependentComponentsMode" data-type="'auto' | 'readonly'" data-required="false">
+    <x-field-desc markdown>Controls the behavior of dependent components. In `'readonly'` mode, users cannot deselect components that are automatically included as dependencies of a selected resource.</x-field-desc>
+  </x-field>
+  <x-field data-name="style" data-type="React.CSSProperties" data-required="false" data-default="{}">
+    <x-field-desc markdown>An object for applying custom CSS styles to the `iframe` element.</x-field-desc>
+  </x-field>
+  <x-field data-name="zIndex" data-type="number" data-required="false" data-default="9999">
+    <x-field-desc markdown>The z-index CSS property for the `iframe` element, controlling its stacking order.</x-field-desc>
+  </x-field>
+</x-field-group>
+
+## Dependent Components
+
+Blocklets that provide a resource API for the `BlockletStudio` can specify component dependencies directly within the resource data. When a user selects a resource that lists `dependentComponents`, the `BlockletStudio` will automatically select those components in the UI.
+
+This feature simplifies the user experience by ensuring that all necessary dependencies are included automatically.
+
+To implement this, your blocklet's resource API should return a `dependentComponents` array containing the DIDs of the required components.
+
+### API Response Example
+
+Here is an example of a JSON response from a resource API endpoint. The "Application" and "Tool" resources declare their component dependencies.
+
+```json API Response with Dependencies
+{
+  "resources": [
+    {
+      "id": "application-448698592710885376",
+      "name": "My App (as Application)",
+      "dependentComponents": [
+        "error-did",
+        "z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9",
+        "z2qZyjnsRffFtn2PDnDwDHTRbAu53RpKqDtFZ",
+        "z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk"
+      ]
+    },
+    {
+      "id": "tool-448698592710885376",
+      "name": "My App (as Tool)",
+      "dependentComponents": ["error-did", "z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk"]
+    },
+    {
+      "id": "template-448698592710885376",
+      "name": "My App (as Template)"
+    }
+  ]
+}
+```
+
+## Summary
+
+The `BlockletStudio` component offers a powerful and convenient way to integrate resource and component management directly into your application. By leveraging an `iframe` and a clear set of props, it provides a consistent user experience while simplifying development. For related functionalities regarding dependency management, you may also want to review the [ComponentInstaller](./components-component-management-component-installer.md) documentation.

package/docs/components-component-management-blocklet-studio.zh-TW.md

@@ -0,0 +1,194 @@
+# BlockletStudio
+
+`BlockletStudio` 元件提供了一個精簡、可嵌入的使用者介面，用於發佈和管理 blocklet 資源。它透過渲染一個全頁 `iframe` 來運作，該 `iframe` 從指定的 blocklet 服務載入一個專用的發佈介面。這讓您的應用程式能夠提供一致且強大的資源管理體驗，而無需從頭開始建構 UI。
+
+宿主應用程式與 `BlockletStudio` iframe 之間的通訊使用 `window.postMessage` API 進行安全處理，為上傳、發佈和連線等事件啟用回呼。
+
+## 使用範例
+
+要整合 `BlockletStudio`，您需要管理其可見性狀態（例如，使用 `useState`）。由於 iframe 可能需要一些時間來載入，建議向使用者顯示一個載入指示器。`onOpened` 回呼可用於表示 iframe 內容已準備就緒，此時可以隱藏載入指示器。
+
+以下範例示範如何實作一個按鈕，該按鈕可開啟 `BlockletStudio` 對話方塊並管理載入狀態。
+
+```tsx icon=logos:react title="Exporter.tsx"
+import { Icon } from '@iconify-icon/react';
+import ArrowUp from '@iconify-icons/tabler/arrow-big-up-line';
+import { Box, IconButton, CircularProgress as Spinner, svgIconClasses } from '@mui/material';
+import { useState } from 'react';
+import { BlockletStudio } from '@arcblock/ux-react';
+
+// 提供工作室服務的 blocklet 的 DID。
+const AI_STUDIO_COMPONENT_DID = 'z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9';
+
+export default function Exporter() {
+  const [showCreateResource, setShowCreateResource] = useState(false);
+  const [opening, setOpening] = useState(false);
+
+  const handleShowDialog = () => {
+    setOpening(true);
+    setShowCreateResource(true);
+  };
+
+  return (
+    <>
+      <IconButton
+        sx={{
+          position: 'relative',
+          minWidth: 40,
+          minHeight: 40,
+          borderRadius: '100%',
+          [`.${svgIconClasses.root}`]: {
+            color: 'text.secondary',
+          },
+        }}
+        onClick={handleShowDialog}>
+        {opening ? <Spinner size={16} /> : <Box component={Icon} icon={ArrowUp} style={{ fontSize: 24 }} />}
+      </IconButton>
+      <BlockletStudio
+        open={showCreateResource}
+        setOpen={setShowCreateResource}
+        onOpened={() => setOpening(false)}
+        componentDid={AI_STUDIO_COMPONENT_DID}
+        mode="dialog"
+        title="Demo Project"
+        description="This is a demo project for the 'aigne' blocklet."
+        note='Please review all resources and components before publishing.'
+        introduction="Welcome to the resource publisher."
+        tenantScope="test-tenant-scope-id-2"
+        resourcesParams={{ name: 'test-project', extra: true }}
+        dependentComponentsMode="readonly"
+        componentsTitle="Required Components"
+        resourcesTitle="Add Project Files"
+        onConnected={() => alert('Connected')}
+        onUploaded={() => alert('Uploaded')}
+        onReleased={() => alert('Released')}
+        components={[
+          { did: 'z8ia3xzq2tMq8CRHfaXj1BTYJyYnEcHbqP8cJ', included: true, required: true },
+          { did: 'z2qZyjnsRffFtn2PDnDwDHTRbAu53RpKqDtFZ', included: true, required: false },
+        ]}
+        resources={{
+          'z8iZpog7mcgcgBZzTiXJCWESvmnRrQmnd3XBB': [
+            'template-448698592710885376',
+            'template-448696391418511360',
+          ],
+        }}
+      />
+    </>
+  );
+}
+```
+
+## 屬性
+
+`BlockletStudio` 元件接受以下屬性來控制其行為和外觀。
+
+<x-field-group>
+  <x-field data-name="open" data-type="boolean" data-required="true">
+    <x-field-desc markdown>控制 `BlockletStudio` iframe 的可見性。設定為 `true` 可顯示，`false` 可隱藏。</x-field-desc>
+  </x-field>
+  <x-field data-name="setOpen" data-type="(open: boolean) => void" data-required="true">
+    <x-field-desc markdown>一個回呼函式，`BlockletStudio` 用於請求關閉。通常，此函式會將與 `open` 屬性相關的狀態變數設定為 `false`。</x-field-desc>
+  </x-field>
+  <x-field data-name="componentDid" data-type="string" data-required="true">
+    <x-field-desc markdown>提供資源發佈服務的 blocklet 的去中心化識別碼 (DID)。這決定了載入哪個工作室介面。</x-field-desc>
+  </x-field>
+  <x-field data-name="onOpened" data-type="() => void" data-required="false">
+    <x-field-desc markdown>一個可選的回呼函式，當 `BlockletStudio` iframe 完成載入並準備好進行使用者互動時執行。</x-field-desc>
+  </x-field>
+  <x-field data-name="onUploaded" data-type="(data: unknown) => void" data-required="false">
+    <x-field-desc markdown>一個可選的回呼函式，在使用者成功上傳新資源後觸發。`data` 參數包含有關上傳項目的元資料。</x-field-desc>
+  </x-field>
+  <x-field data-name="onReleased" data-type="(data: unknown) => void" data-required="false">
+    <x-field-desc markdown>一個可選的回呼函式，在使用者發佈元件的新版本後觸發。`data` 參數包含有關新版本的資訊。</x-field-desc>
+  </x-field>
+  <x-field data-name="onConnected" data-type="(data: unknown) => void" data-required="false">
+    <x-field-desc markdown>一個可選的回呼函式，在使用者連線資源或元件後觸發。</x-field-desc>
+  </x-field>
+  <x-field data-name="tenantScope" data-type="string" data-required="false">
+    <x-field-desc markdown>一個可選的字串，用於將資源範圍限定於特定租戶。這可用於確保多租戶環境中的資料隔離。</x-field-desc>
+  </x-field>
+  <x-field data-name="resourcesParams" data-type="Record<string, any>" data-required="false" data-default="{}">
+    <x-field-desc markdown>一個包含查詢參數的物件，這些參數將傳遞給 blocklet 的資源擷取 API 端點。這允許對資源進行動態篩選。</x-field-desc>
+  </x-field>
+  <x-field data-name="mode" data-type="string" data-required="false" data-default='"dialog"'>
+    <x-field-desc markdown>決定工作室介面的顯示模式。預設為 `'dialog'`。</x-field-desc>
+  </x-field>
+  <x-field data-name="title" data-type="string" data-required="false">
+    <x-field-desc markdown>一個可選的標題，顯示在工作室介面的頂部。</x-field-desc>
+  </x-field>
+  <x-field data-name="logo" data-type="string" data-required="false">
+    <x-field-desc markdown>一個可選的 logo URL，顯示在工作室介面中。</x-field-desc>
+  </x-field>
+  <x-field data-name="description" data-type="string" data-required="false">
+    <x-field-desc markdown>一個可選的字串，提供簡短描述，顯示在工作室 UI 中。</x-field-desc>
+  </x-field>
+  <x-field data-name="introduction" data-type="string" data-required="false">
+    <x-field-desc markdown>一個可選的字串，用於更詳細的介紹，顯示在工作室 UI 中。</x-field-desc>
+  </x-field>
+  <x-field data-name="note" data-type="string" data-required="false">
+    <x-field-desc markdown>一個可選的字串，用於向使用者顯示註釋或重要訊息。</x-field-desc>
+  </x-field>
+  <x-field data-name="componentsTitle" data-type="string" data-required="false">
+    <x-field-desc markdown>一個可選的字串，用於自訂元件部分的標題。</x-field-desc>
+  </x-field>
+  <x-field data-name="resourcesTitle" data-type="string" data-required="false">
+    <x-field-desc markdown>一個可選的字串，用於自訂資源部分的標題。</x-field-desc>
+  </x-field>
+  <x-field data-name="components" data-type="Record<string, unknown>[]" data-required="false" data-default="[]">
+    <x-field-desc markdown>一個物件陣列，代表在工作室中應預設預選的元件。</x-field-desc>
+  </x-field>
+  <x-field data-name="resources" data-type="Record<string, unknown>" data-required="false" data-default="{}">
+    <x-field-desc markdown>一個物件，代表在工作室中應預設預選的資源。</x-field-desc>
+  </x-field>
+  <x-field data-name="dependentComponentsMode" data-type="'auto' | 'readonly'" data-required="false">
+    <x-field-desc markdown>控制相依元件的行為。在 `'readonly'` 模式下，使用者無法取消選取作為所選資源的相依性而自動包含的元件。</x-field-desc>
+  </x-field>
+  <x-field data-name="style" data-type="React.CSSProperties" data-required="false" data-default="{}">
+    <x-field-desc markdown>一個用於將自訂 CSS 樣式應用於 `iframe` 元素的物件。</x-field-desc>
+  </x-field>
+  <x-field data-name="zIndex" data-type="number" data-required="false" data-default="9999">
+    <x-field-desc markdown>`iframe` 元素的 z-index CSS 屬性，控制其堆疊順序。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+## 相依元件
+
+為 `BlockletStudio` 提供資源 API 的 Blocklet 可以在資源資料中直接指定元件相依性。當使用者選取一個列出 `dependentComponents` 的資源時，`BlockletStudio` 將在 UI 中自動選取這些元件。
+
+此功能透過確保所有必要的相依性都自動包含在內，簡化了使用者體驗。
+
+要實作此功能，您的 blocklet 的資源 API 應返回一個包含所需元件 DID 的 `dependentComponents` 陣列。
+
+### API 回應範例
+
+以下是來自資源 API 端點的 JSON 回應範例。「應用程式」和「工具」資源宣告了它們的元件相依性。
+
+```json 帶有相依性的 API 回應
+{
+  "resources": [
+    {
+      "id": "application-448698592710885376",
+      "name": "My App (as Application)",
+      "dependentComponents": [
+        "error-did",
+        "z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9",
+        "z2qZyjnsRffFtn2PDnDwDHTRbAu53RpKqDtFZ",
+        "z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk"
+      ]
+    },
+    {
+      "id": "tool-448698592710885376",
+      "name": "My App (as Tool)",
+      "dependentComponents": ["error-did", "z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk"]
+    },
+    {
+      "id": "template-448698592710885376",
+      "name": "My App (as Template)"
+    }
+  ]
+}
+```
+
+## 總結
+
+`BlockletStudio` 元件提供了一種強大而便利的方式，可將資源和元件管理直接整合到您的應用程式中。透過利用 `iframe` 和一組清晰的屬性，它在簡化開發的同時提供了一致的使用者體驗。有關相依性管理的相關功能，您可能還想查閱 [ComponentInstaller](./components-component-management-component-installer.md) 文件。