@blocklet/ui-react

# 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)のドキュメントも参照してください。