BlockletStudioコンポーネントは、ブロックレットリソースの公開と管理のための、効率的で埋め込み可能なユーザーインターフェースを提供します。これは、指定されたブロックレットサービスから専用の公開インターフェースを読み込むフルページのiframeをレンダリングすることで動作します。これにより、アプリケーションはUIをゼロから構築することなく、一貫性のある強力なリソース管理体験を提供できます。
ホストアプリケーションとBlockletStudio iframe間の通信は、window.postMessage APIを使用して安全に処理され、アップロード、リリース、接続などのイベントに対するコールバックを可能にします。
使用例
BlockletStudioを統合するには、その可視性状態を（例：useStateで）管理する必要があります。iframeの読み込みには時間がかかる場合があるため、ユーザーにローディングインジケーターを表示することが推奨されます。onOpenedコールバックを使用してiframeコンテンツの準備ができたことを通知し、その時点でローディングインジケーターを非表示にすることができます。
次の例は、BlockletStudioダイアログを開き、ローディング状態を管理するボタンを実装する方法を示しています。
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を受け入れます。
- open
boolean(required) — BlockletStudio iframeの可視性を制御します。trueに設定すると表示され、falseに設定すると非表示になります。 - setOpen
(open: boolean) => void(required) — BlockletStudioが閉じることを要求するために使用するコールバック関数。通常、この関数はopen propに関連付けられた状態変数をfalseに設定します。 - componentDid
string(required) — リソース公開サービスを提供するブロックレットの分散型識別子（DID）。これにより、どのスタジオインターフェースが読み込まれるかが決まります。 - onOpened
() => void— BlockletStudio iframeの読み込みが完了し、ユーザーが操作できる状態になったときに実行されるオプションのコールバック関数。 - onUploaded
(data: unknown) => void— ユーザーが新しいリソースのアップロードに成功した後にトリガーされるオプションのコールバック関数。dataパラメータには、アップロードされたアイテムに関するメタデータが含まれます。 - onReleased
(data: unknown) => void— ユーザーがコンポーネントの新しいリリースを公開した後にトリガーされるオプションのコールバック関数。dataパラメータには、新しいリリースに関する情報が含まれます。 - onConnected
(data: unknown) => void— ユーザーがリソースまたはコンポーネントを接続した後にトリガーされるオプションのコールバック関数。 - tenantScope
string— リソースを特定のテナントにスコープするためのオプションの文字列。これは、マルチテナント環境でのデータ分離を保証するために使用できます。 - resourcesParams
Record<string, any>(default:{}) — ブロックレットのリソース取得APIエンドポイントに渡されるクエリパラメータを含むオブジェクト。これにより、リソースの動的なフィルタリングが可能になります。 - mode
string(default:"dialog") — スタジオインターフェースの表示モードを決定します。デフォルトは'dialog'です。 - title
string— スタジオインターフェースの上部に表示されるオプションのタイトル。 - logo
string— スタジオインターフェースに表示されるロゴのオプションのURL。 - description
string— スタジオUIに表示される簡単な説明を提供するオプションの文字列。 - introduction
string— スタジオUIに表示される、より詳細な紹介のためのオプションの文字列。 - note
string— ユーザーに注意や重要なメッセージを表示するためのオプションの文字列。 - componentsTitle
string— コンポーネントセクションのタイトルをカスタマイズするためのオプションの文字列。 - resourcesTitle
string— リソースセクションのタイトルをカスタマイズするためのオプションの文字列。 - components
Record<string, unknown>[](default:[]) — スタジオでデフォルトで事前選択されるべきコンポーネントを表すオブジェクトの配列。 - resources
Record<string, unknown>(default:{}) — スタジオでデフォルトで事前選択されるべきリソースを表すオブジェクト。 - dependentComponentsMode
'auto' | 'readonly'— 依存コンポーネントの動作を制御します。'readonly'モードでは、ユーザーは選択されたリソースの依存関係として自動的に含まれるコンポーネントの選択を解除できません。 - style
React.CSSProperties(default:{}) — iframe要素にカスタムCSSスタイルを適用するためのオブジェクト。 - zIndex
number(default:9999) — iframe要素のz-index CSSプロパティ。スタック順序を制御します。
依存コンポーネント
BlockletStudioにリソースAPIを提供するブロックレットは、リソースデータ内で直接コンポーネントの依存関係を指定できます。ユーザーがdependentComponentsをリストしているリソースを選択すると、BlockletStudioはUIでそれらのコンポーネントを自動的に選択します。
この機能は、必要なすべての依存関係が自動的に含まれるようにすることで、ユーザーエクスペリエンスを簡素化します。
これを実装するには、ブロックレットのリソースAPIは、必要なコンポーネントのDIDを含むdependentComponents配列を返す必要があります。
APIレスポンス例
以下は、リソースAPIエンドポイントからのJSONレスポンスの例です。「Application」および「Tool」リソースは、それぞれのコンポーネント依存関係を宣言しています。
依存関係を含む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のドキュメントも参照してください。