@blocklet/ui-react 3.1.48 → 3.1.50

package/docs/components-component-management-component-installer.zh.md

@@ -0,0 +1,256 @@
+# ComponentInstaller
+
+`ComponentInstaller` 是一个实用工具组件，为依赖其他 blocklet 的功能充当网关。它会验证指定的组件依赖项是否已安装。如果未安装，它会为管理员（默认为 `owner` 或 `admin` 角色）提供一个用户友好的界面，以便直接进行安装。如果用户缺少必要的权限，它会显示一条消息，建议他们联系管理员。
+
+该组件对于创建能够优雅处理可选依赖项缺失的稳健应用程序至关重要，通过引导管理员完成安装过程来改善用户体验。
+
+## 工作原理
+
+该组件的逻辑遵循一个清晰的顺序流程，以确保在渲染其子组件之前满足依赖关系。
+
+```d2
+direction: down
+
+start: {
+  label: "开始"
+  shape: oval
+}
+
+check_dependencies: {
+  label: "检查在 'did' prop 中定义的依赖项"
+  shape: rectangle
+}
+
+is_installed: {
+  label: "所有依赖项都已安装吗？"
+  shape: diamond
+}
+
+render_children: {
+  label: "渲染子组件"
+  shape: rectangle
+  style.fill: "#d4edda"
+}
+
+check_permission: {
+  label: "根据 'roles' prop 检查用户角色"
+  shape: rectangle
+}
+
+has_permission: {
+  label: "用户有权限吗？"
+  shape: diamond
+}
+
+display_installer: {
+  label: "显示安装器界面"
+  shape: rectangle
+  style.fill: "#cce5ff"
+}
+
+is_mute: {
+  label: "'noPermissionMute' prop 是否为 true？"
+  shape: diamond
+}
+
+display_suggestion: {
+  label: "显示“联系管理员”建议"
+  shape: rectangle
+  style.fill: "#f8d7da"
+}
+
+render_fallback: {
+  label: "渲染回退组件或 null"
+  shape: rectangle
+}
+
+end: {
+  label: "结束"
+  shape: oval
+}
+
+start -> check_dependencies
+check_dependencies -> is_installed
+is_installed -> render_children: "是"
+is_installed -> check_permission: "否"
+render_children -> end
+
+check_permission -> has_permission
+has_permission -> display_installer: "是"
+has_permission -> is_mute: "否"
+display_installer -> end
+
+is_mute -> render_fallback: "是"
+is_mute -> display_suggestion: "否"
+render_fallback -> end
+display_suggestion -> end
+```
+
+1.  **依赖检查**：它读取 `did` prop，并与 blocklet 的元数据（`window.blocklet.optionalComponents`）进行核对，以确定所需的组件是否已安装。
+2.  **权限检查**：如果缺少任何组件，它会使用 `SessionPermission` 组件来验证当前用户的角色是否与 `roles` prop 中指定的角色匹配。
+3.  **条件渲染**：
+    *   如果所有依赖项都已安装，它将渲染其 `children`。
+    *   如果依赖项缺失且用户拥有权限，它将显示一个弹出式安装面板。
+    *   如果依赖项缺失且用户缺乏权限，它将显示联系管理员的建议，或者如果启用了 `noPermissionMute`，则渲染一个 `fallback` 组件。
+
+## 基本用法
+
+使用 `ComponentInstaller` 包裹任何依赖于可选 blocklet 的组件或功能。提供所需组件的 DID。
+
+```jsx "MyFeature.jsx" icon=logos:react
+import ComponentInstaller from '@arcblock/blocklet-ui-react/lib/ComponentInstaller';
+import MyDependentComponent from './MyDependentComponent';
+
+export default function MyFeature() {
+  // 替换为所需组件的实际 DID
+  const requiredComponentDid = 'z8ia2427634f1e909a304e2b963715a18';
+
+  return (
+    <ComponentInstaller did={requiredComponentDid}>
+      {/* 只有在满足依赖关系时，此组件才会被渲染 */}
+      <MyDependentComponent />
+    </ComponentInstaller>
+  );
+}
+```
+
+## Props
+
+`ComponentInstaller` 接受以下 props 来自定义其行为。
+
+<x-field-group>
+  <x-field data-name="did" data-type="string | string[]" data-required="true">
+    <x-field-desc markdown>要检查的组件依赖项的 DID（或 DID 数组）。这是您需要的 blocklet 的主要标识符。</x-field-desc>
+  </x-field>
+  <x-field data-name="children" data-type="any" data-required="true">
+    <x-field-desc markdown>确认所有依赖项都已安装后要渲染的内容。可以是标准的 React 节点或渲染函数。</x-field-desc>
+  </x-field>
+  <x-field data-name="roles" data-type="string[]" data-default='["owner", "admin"]'>
+    <x-field-desc markdown>允许查看安装界面并安装缺失组件的用户角色数组。</x-field-desc>
+  </x-field>
+  <x-field data-name="fallback" data-type="React.ReactNode" data-required="false">
+    <x-field-desc markdown>一个回退组件，用于在检查依赖项时或当 `noPermissionMute` 对没有安装权限的用户激活时显示。</x-field-desc>
+  </x-field>
+  <x-field data-name="noPermissionMute" data-type="boolean" data-default="false">
+    <x-field-desc markdown>如果为 `true`，没有权限的用户将看到 `fallback` 组件（或什么也不显示），而不是“联系管理员”的消息。</x-field-desc>
+  </x-field>
+  <x-field data-name="disabled" data-type="boolean" data-default="false">
+    <x-field-desc markdown>如果为 `true`，该组件将绕过所有检查并立即渲染其 `children`。</x-field-desc>
+  </x-field>
+  <x-field data-name="onInstalled" data-type="function" data-required="false">
+    <x-field-desc markdown>依赖项检查完成后触发的回调函数。它接收已安装组件的列表。</x-field-desc>
+  </x-field>
+  <x-field data-name="onError" data-type="function" data-required="false">
+    <x-field-desc markdown>如果在依赖项检查期间发生错误，则触发的回调函数。它接收导致错误的组件列表。</x-field-desc>
+  </x-field>
+  <x-field data-name="onClose" data-type="function" data-required="false">
+    <x-field-desc markdown>当安装弹出窗口关闭时调用的回调函数。</x-field-desc>
+  </x-field>
+  <x-field data-name="closeByOutSize" data-type="boolean" data-default="false">
+    <x-field-desc markdown>如果为 `true`，当用户点击安装弹出窗口外部时，该窗口将关闭。</x-field-desc>
+  </x-field>
+  <x-field data-name="warnIcon" data-type="React.ReactNode" data-required="false">
+    <x-field-desc markdown>一个自定义的 React 节点，用于替换安装弹出窗口中的默认警告图标。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+## 高级用法
+
+### 检查多个组件
+
+您可以向 `did` prop 传递一个 DID 数组，以一次性检查多个依赖项。只有在所有指定的组件都已安装的情况下，子组件才会渲染。
+
+```jsx "MyDashboard.jsx" icon=logos:react
+import ComponentInstaller from '@arcblock/blocklet-ui-react/lib/ComponentInstaller';
+import AnalyticsWidget from './AnalyticsWidget';
+import CmsWidget from './CmsWidget';
+
+export default function MyDashboard() {
+  const requiredDids = [
+    'z8ia2427634f1e909a304e2b963715a18', // Analytics Service
+    'z8ia3c1f2e4b8e6a1b2c3d4e5f6a7b8c9', // CMS Service
+  ];
+
+  return (
+    <ComponentInstaller did={requiredDids}>
+      <AnalyticsWidget />
+      <CmsWidget />
+    </ComponentInstaller>
+  );
+}
+```
+
+### 为加载状态使用回退组件
+
+提供一个 `fallback` 组件，以在依赖项检查进行中时改善用户体验。这对于与 `noPermissionMute` 一起使用，为未经授权的用户显示占位符也很有用。
+
+```jsx "FeatureWithLoading.jsx" icon=logos:react
+import ComponentInstaller from '@arcblock/blocklet-ui-react/lib/ComponentInstaller';
+import CircularProgress from '@mui/material/CircularProgress';
+import Box from '@mui/material/Box';
+import MyDependentComponent from './MyDependentComponent';
+
+export default function FeatureWithLoading() {
+  const LoadingSpinner = (
+    <Box sx={{ display: 'flex', justifyContent: 'center', p: 4 }}>
+      <CircularProgress />
+    </Box>
+  );
+
+  return (
+    <ComponentInstaller
+      did="z8ia2427634f1e909a304e2b963715a18"
+      fallback={LoadingSpinner}
+      noPermissionMute={true}
+    >
+      <MyDependentComponent />
+    </ComponentInstaller>
+  );
+}
+```
+
+### 使用渲染 Props 自定义 UI
+
+为了完全控制 UI，您可以将一个函数作为 `children` 传递。该函数接收一个包含 `hasPermission`、`optComponents` 和 `installStatus` 的对象，允许您构建一个完全自定义的安装界面。
+
+```jsx "CustomInstallerButton.jsx" icon=logos:react
+import ComponentInstaller from '@arcblock/blocklet-ui-react/lib/ComponentInstaller';
+import Button from '@mui/material/Button';
+
+export default function CustomInstallerButton() {
+  const requiredDid = 'z8ia2427634f1e909a304e2b963715a18';
+
+  return (
+    <ComponentInstaller did={requiredDid}>
+      {({ hasPermission, optComponents, installStatus }) => {
+        const isMissing = optComponents.length > 0;
+        const status = installStatus[requiredDid] || 'not_installed';
+
+        if (!isMissing) {
+          return <p>功能已准备就绪！</p>;
+        }
+
+        if (!hasPermission) {
+          return <p>请请求管理员安装所需组件。</p>;
+        }
+
+        return (
+          <Button
+            variant="contained"
+            disabled={status !== 'not_installed'}
+            onClick={() => window.open(optComponents[0].installUrl, '_blank')}
+          >
+            {status === 'not_installed' ? `安装 ${optComponents[0].meta.title}` : `正在安装... (${status})`}
+          </Button>
+        );
+      }}
+    </ComponentInstaller>
+  );
+}
+```
+
+## 总结
+
+`ComponentInstaller` 是一个功能强大的组件，用于管理 blocklet 应用程序中的可选依赖项。它提供了一种结构化且用户友好的方式，以确保所需组件可用，并在必要时引导管理员完成安装过程。通过使用此组件，您可以构建更具弹性和功能丰富的应用程序，以适应用户的环境。
+
+有关管理组件的更多详细信息，您可能还对 [BlockletStudio](./components-component-management-blocklet-studio.md) 组件感兴趣，它为资源和组件管理提供了更全面的界面。

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

@@ -0,0 +1,59 @@
+# コンポーネント管理
+
+コンポーネント管理は、実行中のアプリケーション内でブロックレットコンポーネントを動的にインストール、公開、管理するための一連のツールを提供します。この機能により、アプリケーションはモジュール式で拡張可能になり、管理者や開発者はコアアプリケーションの完全な再デプロイを必要とせずに機能を追加または更新できます。
+
+これらのツールは、機能をその場で構成・更新できる柔軟なシステムを構築するために不可欠です。例えば、アプリケーションが必要な依存関係をすべて実行時に持つことを保証したり、開発者が新しいリソースを公開するための統合インターフェースを提供したりすることができます。
+
+このライフサイクルを管理するための主要なコンポーネントは `ComponentInstaller` と `BlockletStudio` です。
+
+```d2
+direction: down
+
+Application: {
+  label: "メインアプリケーション"
+  shape: rectangle
+  style.fill: "#f0f7ff"
+}
+
+Blocklet-Components: {
+  label: "Blocklet コンポーネント"
+  shape: rectangle
+  style.fill: "#f6ffed"
+  style.stroke-dash: 2
+}
+
+ComponentInstaller: {
+  label: "ComponentInstaller"
+  shape: rectangle
+  style.fill: "#fff7e6"
+}
+
+BlockletStudio: {
+  label: "BlockletStudio"
+  shape: rectangle
+  style.fill: "#fff1f0"
+}
+
+Application -> Blocklet-Components: "依存/使用"
+ComponentInstaller -> Blocklet-Components: "インストール & 検証"
+BlockletStudio -> Blocklet-Components: "公開 & 管理"
+```
+
+## コアツール
+
+このセクションでは、利用可能なコンポーネント管理ツールの簡単な概要を説明します。詳細なドキュメントと使用例については、各サブページを参照してください。
+
+<x-cards data-columns="2">
+  <x-card data-title="ComponentInstaller" data-icon="lucide:package-check" data-href="/components/component-management/component-installer">
+    必要なすべての依存コンポーネントがインストールされているかを確認し、管理者が不足しているコンポーネントをインストールするための、ロールで保護されたシンプルなインターフェースを提供するユーティリティコンポーネントです。
+  </x-card>
+  <x-card data-title="BlockletStudio" data-icon="lucide:box" data-href="/components/component-management/blocklet-studio">
+    アプリケーション内で直接、コンポーネントおよび関連リソースの公開、バージョン管理、管理を行うための包括的なスタジオを提供する、埋め込み可能な iframe ベースのインターフェースです。
+  </x-card>
+</x-cards>
+
+## 概要
+
+`ComponentInstaller` と `BlockletStudio` を活用することで、開発者は保守と拡張が容易な堅牢なアプリケーションを構築できます。`ComponentInstaller` は依存関係を管理することでアプリケーションの健全性を保証し、`BlockletStudio` はコンテンツと機能の管理のための強力なインターフェースを提供します。
+
+基本的な原則に関する詳細については、[コアコンセプト](./core-concepts.md) のドキュメントを参照してください。

package/docs/components-component-management.md

@@ -0,0 +1,59 @@
+# Component Management
+
+Component management provides a suite of tools for dynamically installing, publishing, and managing blocklet components within a running application. This capability allows applications to be modular and extensible, enabling administrators and developers to add or update features without requiring a full redeployment of the core application.
+
+These tools are essential for creating flexible systems where functionality can be composed and updated on the fly. For example, you can ensure that an application has all its necessary dependencies at runtime or provide an integrated interface for developers to publish new resources.
+
+The primary components for managing this lifecycle are `ComponentInstaller` and `BlockletStudio`.
+
+```d2
+direction: down
+
+Application: {
+  label: "Main Application"
+  shape: rectangle
+  style.fill: "#f0f7ff"
+}
+
+Blocklet-Components: {
+  label: "Blocklet Components"
+  shape: rectangle
+  style.fill: "#f6ffed"
+  style.stroke-dash: 2
+}
+
+ComponentInstaller: {
+  label: "ComponentInstaller"
+  shape: rectangle
+  style.fill: "#fff7e6"
+}
+
+BlockletStudio: {
+  label: "BlockletStudio"
+  shape: rectangle
+  style.fill: "#fff1f0"
+}
+
+Application -> Blocklet-Components: "Depends on / Uses"
+ComponentInstaller -> Blocklet-Components: "Installs & Verifies"
+BlockletStudio -> Blocklet-Components: "Publishes & Manages"
+```
+
+## Core Tools
+
+This section provides a brief overview of the available component management tools. For detailed documentation and usage examples, please refer to the specific sub-pages.
+
+<x-cards data-columns="2">
+  <x-card data-title="ComponentInstaller" data-icon="lucide:package-check" data-href="/components/component-management/component-installer">
+    A utility component that verifies if all required dependent components are installed and provides a simple, role-protected interface for administrators to install any missing ones.
+  </x-card>
+  <x-card data-title="BlockletStudio" data-icon="lucide:box" data-href="/components/component-management/blocklet-studio">
+    An embeddable iframe-based interface that provides a comprehensive studio for publishing, versioning, and managing components and their associated resources directly within your application.
+  </x-card>
+</x-cards>
+
+## Summary
+
+By leveraging `ComponentInstaller` and `BlockletStudio`, developers can build robust applications that are easy to maintain and extend. `ComponentInstaller` ensures application health by managing dependencies, while `BlockletStudio` provides a powerful interface for content and feature management.
+
+For more information on the underlying principles, see the [Core Concepts](./core-concepts.md) documentation.

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

@@ -0,0 +1,59 @@
+# 組件管理
+
+組件管理提供了一套工具，用於在執行中的應用程式內動態安裝、發布和管理 blocklet 組件。此功能使應用程式得以模組化和擴充，讓管理員和開發人員能夠新增或更新功能，而無需對核心應用程式進行完整的重新部署。
+
+這些工具對於創建功能可以即時組合和更新的靈活系統至關重要。例如，您可以確保應用程式在執行階段擁有所有必要的依賴項，或為開發人員提供一個整合式介面來發布新資源。
+
+管理此生命週期的主要組件是 `ComponentInstaller` 和 `BlockletStudio`。
+
+```d2
+direction: down
+
+Application: {
+  label: "主應用程式"
+  shape: rectangle
+  style.fill: "#f0f7ff"
+}
+
+Blocklet-Components: {
+  label: "Blocklet 組件"
+  shape: rectangle
+  style.fill: "#f6ffed"
+  style.stroke-dash: 2
+}
+
+ComponentInstaller: {
+  label: "ComponentInstaller"
+  shape: rectangle
+  style.fill: "#fff7e6"
+}
+
+BlockletStudio: {
+  label: "BlockletStudio"
+  shape: rectangle
+  style.fill: "#fff1f0"
+}
+
+Application -> Blocklet-Components: "依賴 / 使用"
+ComponentInstaller -> Blocklet-Components: "安裝與驗證"
+BlockletStudio -> Blocklet-Components: "發布與管理"
+```
+
+## 核心工具
+
+本節簡要概述了可用的組件管理工具。有關詳細文件和使用範例，請參閱特定的子頁面。
+
+<x-cards data-columns="2">
+  <x-card data-title="ComponentInstaller" data-icon="lucide:package-check" data-href="/components/component-management/component-installer">
+    一個實用組件，用於驗證是否已安裝所有必要的相依組件，並為管理員提供一個簡單、受角色保護的介面來安裝任何缺少的組件。
+  </x-card>
+  <x-card data-title="BlockletStudio" data-icon="lucide:box" data-href="/components/component-management/blocklet-studio">
+    一個可嵌入的、基於 iframe 的介面，提供一個全面的工作室，用於直接在您的應用程式內發布、版本控制和管理組件及其相關資源。
+  </x-card>
+</x-cards>
+
+## 總結
+
+透過利用 `ComponentInstaller` 和 `BlockletStudio`，開發人員可以建立易於維護和擴展的穩健應用程式。`ComponentInstaller` 透過管理依賴項來確保應用程式的健康狀態，而 `BlockletStudio` 則為內容和功能管理提供強大的介面。
+
+欲了解更多關於其基本原理的資訊，請參閱 [核心概念](./core-concepts.md) 文件。

package/docs/components-component-management.zh.md

@@ -0,0 +1,59 @@
+# 组件管理
+
+组件管理提供了一套工具，用于在正在运行的应用程序中动态安装、发布和管理 blocklet 组件。此功能使应用程序能够模块化和可扩展，允许管理员和开发人员添加或更新功能，而无需对核心应用程序进行完全重新部署。
+
+这些工具对于创建可以动态组合和更新功能的灵活系统至关重要。例如，您可以确保应用程序在运行时拥有所有必需的依赖项，或为开发人员提供一个集成的界面来发布新资源。
+
+管理此生命周期的主要组件是 `ComponentInstaller` 和 `BlockletStudio`。
+
+```d2
+direction: down
+
+Application: {
+  label: "主应用程序"
+  shape: rectangle
+  style.fill: "#f0f7ff"
+}
+
+Blocklet-Components: {
+  label: "Blocklet 组件"
+  shape: rectangle
+  style.fill: "#f6ffed"
+  style.stroke-dash: 2
+}
+
+ComponentInstaller: {
+  label: "ComponentInstaller"
+  shape: rectangle
+  style.fill: "#fff7e6"
+}
+
+BlockletStudio: {
+  label: "BlockletStudio"
+  shape: rectangle
+  style.fill: "#fff1f0"
+}
+
+Application -> Blocklet-Components: "依赖/使用"
+ComponentInstaller -> Blocklet-Components: "安装与验证"
+BlockletStudio -> Blocklet-Components: "发布与管理"
+```
+
+## 核心工具
+
+本节简要概述了可用的组件管理工具。有关详细文档和使用示例，请参阅具体子页面。
+
+<x-cards data-columns="2">
+  <x-card data-title="ComponentInstaller" data-icon="lucide:package-check" data-href="/components/component-management/component-installer">
+    一个实用程序组件，用于验证是否所有必需的依赖组件都已安装，并为管理员提供一个简单的、受角色保护的界面来安装任何缺失的组件。
+  </x-card>
+  <x-card data-title="BlockletStudio" data-icon="lucide:box" data-href="/components/component-management/blocklet-studio">
+    一个可嵌入的、基于 iframe 的界面，提供了一个全面的工作室，用于在您的应用程序内直接发布、版本化和管理组件及其相关资源。
+  </x-card>
+</x-cards>
+
+## 摘要
+
+通过利用 `ComponentInstaller` 和 `BlockletStudio`，开发人员可以构建易于维护和扩展的健壮应用程序。`ComponentInstaller` 通过管理依赖关系来确保应用程序的健康，而 `BlockletStudio` 则为内容和功能管理提供了强大的界面。
+
+有关基本原理的更多信息，请参阅 [核心概念](./core-concepts.md) 文档。