跳到主要内容

BlockletStudio

BlockletStudio 组件提供了一个精简的、可嵌入的用户界面，用于发布和管理 blocklet 资源。它通过渲染一个全页 iframe 来运行，该 iframe 从指定的 blocklet 服务加载一个专用的发布界面。这使得您的应用程序能够提供一致且强大的资源管理体验，而无需从头开始构建 UI。

主机应用程序与 BlockletStudio iframe 之间的通信通过 window.postMessage API 进行安全处理，从而可以为上传、发布和连接等事件启用回调。

使用示例

要集成 BlockletStudio，您需要管理其可见性状态（例如，使用 useState）。由于 iframe 可能需要一些时间来加载，建议向用户显示一个加载指示器。onOpened 回调可用于表示 iframe 内容已准备就绪，此时可以隐藏加载指示器。

以下示例演示了如何实现一个打开 BlockletStudio 对话框并管理加载状态的按钮。

Exporter.tsx

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';

// 提供 studio 服务的 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',
          ],
        }}
      />
    </>
  );
}

Props

BlockletStudio 组件接受以下 props 来控制其行为和外观。

  • open boolean (required) — 控制 BlockletStudio iframe 的可见性。设置为 true 显示，设置为 false 隐藏。
  • setOpen (open: boolean) => void (required) — 一个回调函数，BlockletStudio 使用它来请求关闭。通常，此函数会将与 open prop 关联的状态变量设置为 false。
  • componentDid string (required) — 提供资源发布服务的 blocklet 的去中心化标识符 (DID)。这决定了加载哪个 studio 界面。
  • 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: {}) — 一个包含查询参数的对象，这些参数将传递给 blocklet 的资源获取 API 端点。这允许对资源进行动态过滤。
  • mode string (default: "dialog") — 决定 studio 界面的显示模式。默认为 'dialog'。
  • title string — 一个可选的标题，显示在 studio 界面的顶部。
  • logo string — 一个可选的 logo URL，显示在 studio 界面中。
  • description string — 一个可选的字符串，提供简短描述，显示在 studio UI 中。
  • introduction string — 一个可选的字符串，用于更详细的介绍，显示在 studio UI 中。
  • note string — 一个可选的字符串，用于向用户显示注释或重要消息。
  • componentsTitle string — 一个可选的字符串，用于自定义组件部分的标题。
  • resourcesTitle string — 一个可选的字符串，用于自定义资源部分的标题。
  • components Record<string, unknown>[] (default: []) — 一个对象数组，代表在 studio 中默认应预先选中的组件。
  • resources Record<string, unknown> (default: {}) — 一个对象，代表在 studio 中默认应预先选中的资源。
  • dependentComponentsMode 'auto' | 'readonly' — 控制依赖组件的行为。在 'readonly' 模式下，用户无法取消选择作为所选资源依赖项而自动包含的组件。
  • style React.CSSProperties (default: {}) — 一个用于将自定义 CSS 样式应用于 iframe 元素的对象。
  • zIndex number (default: 9999) — iframe 元素的 z-index CSS 属性，控制其堆叠顺序。

依赖组件

为 BlockletStudio 提供资源 API 的 Blocklet 可以直接在资源数据中指定组件依赖项。当用户选择一个列出了 dependentComponents 的资源时，BlockletStudio 将在 UI 中自动选择这些组件。

此功能通过确保所有必要的依赖项都自动包含进来，从而简化了用户体验。

要实现此功能，您的 blocklet 的资源 API 应返回一个包含所需组件 DID 的 dependentComponents 数组。

API 响应示例

以下是来自资源 API 端点的 JSON 响应示例。"Application" 和 "Tool" 资源声明了它们的组件依赖项。

带有依赖项的 API 响应

json
{
  "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 文档。