@blocklet/ui-react 3.1.48 → 3.1.50

package/docs/components-layout-header.zh-TW.md

@@ -0,0 +1,233 @@
+# Header
+
+`Header` 元件為 Blocklet 應用程式提供了一個響應式且可自訂的頁首。它透過直接從 blocklet 的設定檔（`blocklet.yml`）讀取元資料，自動填入導覽連結、應用程式標誌和使用者會話控制項。此元件旨在以最少的設定建立一個一致且功能豐富的頁首。
+
+## 總覽
+
+`Header` 元件作為主要的導覽和品牌元素。它基於 `@arcblock/ux` 元件（包括 `ResponsiveHeader` 和 `NavMenu`）建構，並與 DID Connect 會話上下文無縫整合，以進行使用者身份驗證。
+
+主要功能包括：
+- **自動設定**：從 `blocklet.yml` 填入應用程式標誌、標題和導覽連結。
+- **響應式設計**：自動適應不同螢幕尺寸，提供適合行動裝置的導覽選單。
+- **會話管理**：與 DID Connect 整合，顯示使用者資訊、個人資料選單以及登入/登出按鈕。
+- **可自訂的附加元件**：允許注入自訂元件或修改預設元素，如主題切換器和語系選擇器。
+- **組織切換**：如果 blocklet 啟用組織支援，則自動包含組織切換器。
+- **網域警告**：當管理員和使用者透過臨時網域存取應用程式時發出通知，以鼓勵設定自訂網域以提高安全性。
+
+### 運作方式
+
+下圖說明了 `Header` 的資料流和元件組成。它從 `blocklet.yml` 檔案中讀取設定，進行處理，並渲染相應的 UI 元素，包括標誌、導覽連結和使用者會話控制項。
+
+```d2
+direction: down
+
+blocklet-yml: {
+  label: "blocklet.yml"
+  shape: rectangle
+}
+
+Header-Component: {
+  label: "Header 元件"
+  shape: rectangle
+
+  Blocklet-Metadata-Parser: {
+    label: "元資料解析器"
+  }
+
+  UI-Renderer: {
+    label: "UI 渲染器"
+    shape: rectangle
+
+    Logo
+    Navigation-Menu: {
+      label: "導覽選單"
+    }
+    Header-Addons: {
+      label: "頁首附加元件"
+      shape: rectangle
+      grid-columns: 2
+      Session-Manager: {
+        label: "會話管理器"
+      }
+      Locale-Selector: {
+        label: "語系選擇器"
+      }
+      Theme-Toggle: {
+        label: "主題切換器"
+      }
+      Custom-Addons: {
+        label: "自訂附加元件"
+      }
+    }
+  }
+
+  Blocklet-Metadata-Parser -> UI-Renderer: "提供資料"
+}
+
+blocklet-yml -> Header-Component.Blocklet-Metadata-Parser: "讀取設定"
+
+Header-Component.UI-Renderer.Logo
+Header-Component.UI-Renderer.Navigation-Menu
+Header-Component.UI-Renderer.Header-Addons
+
+```
+
+## 基本用法
+
+要使用 `Header`，請將其匯入並放置在您應用程式的佈局中。它需要 blocklet 的元資料，這通常可透過 `window.blocklet` 全域取得。
+
+```javascript "App.js" icon=logos:javascript
+import Header from '@blocklet/ui-react/lib/Header';
+
+function App() {
+  // meta 物件通常來自 window.blocklet
+  const blockletMeta = window.blocklet || {};
+
+  return (
+    <div>
+      <Header meta={blockletMeta} />
+      <main>
+        {/* 您的應用程式內容 */}
+      </main>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## 屬性
+
+`Header` 元件接受多個屬性以進行自訂。
+
+<x-field-group>
+  <x-field data-name="meta" data-type="BlockletMetaProps" data-required="false">
+    <x-field-desc markdown>blocklet 的元資料物件，通常來自 `window.blocklet`。它包含元件用於渲染的資訊，如 `name`、`logo` 和 `navigation`。</x-field-desc>
+  </x-field>
+  <x-field data-name="addons" data-type="Function | React.ReactNode" data-required="false">
+    <x-field-desc markdown>要新增到頁首右側的自訂元素。如果提供一個函式，它會接收內建的附加元件作為參數，讓您可以修改、重新排序或補充它們。如果提供一個節點，它將取代所有內建的附加元件。</x-field-desc>
+  </x-field>
+  <x-field data-name="sessionManagerProps" data-type="SessionManagerProps" data-required="false" data-default='{ "showRole": true }'>
+    <x-field-desc markdown>直接傳遞給底層 `SessionUser` 元件的屬性，用於控制使用者會話資訊的顯示，例如顯示使用者的角色。</x-field-desc>
+  </x-field>
+  <x-field data-name="homeLink" data-type="string | Function" data-required="false" data-default="publicPath">
+    <x-field-desc markdown>首頁連結的 URL，通常透過點擊標誌或品牌名稱觸發。預設為 blocklet 的公開路徑（`/`）。也可以是一個回傳 JSX 元素的函式。</x-field-desc>
+  </x-field>
+  <x-field data-name="theme" data-type="object" data-required="false">
+    <x-field-desc markdown>一個 Material-UI 主題物件，用於與預設主題合併，以實現對顏色、字體排印和其他樣式的深度自訂。</x-field-desc>
+  </x-field>
+  <x-field data-name="hideNavMenu" data-type="boolean" data-required="false" data-default="false">
+    <x-field-desc markdown>如果為 `true`，即使存在導覽資料，從 `blocklet.yml` 產生的導覽選單也將被隱藏。</x-field-desc>
+  </x-field>
+  <x-field data-name="bordered" data-type="boolean" data-required="false" data-default="false">
+    <x-field-desc markdown>如果為 `true`，頁首將應用底部邊框以進行視覺分隔。</x-field-desc>
+  </x-field>
+  <x-field data-name="logo" data-type="React.ReactNode" data-required="false">
+    <x-field-desc markdown>一個自訂的標誌元素，用於覆蓋來自 blocklet 元資料的標誌。</x-field-desc>
+  </x-field>
+  <x-field data-name="brand" data-type="React.ReactNode" data-required="false">
+    <x-field-desc markdown>一個自訂的品牌元素（例如文字或圖片），用於顯示在標誌旁邊。</x-field-desc>
+  </x-field>
+  <x-field data-name="showDomainWarningDialog" data-type="boolean" data-required="false" data-default="true">
+    <x-field-desc markdown>如果為 `false`，則不會顯示關於臨時網域的警告對話方塊。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+## 功能
+
+### 從元資料自動產生導覽
+
+`Header` 會根據您 `blocklet.yml` 檔案中的 `navigation` 陣列自動產生其導覽選單。元件會解析此設定以建立主導覽連結和巢狀下拉選單。
+
+以下是 `blocklet.yml` 中 `navigation` 設定的一個範例：
+
+```yaml "blocklet.yml" icon=mdi:code-braces
+navigation:
+  - title: Features
+    link: /features
+    icon: 'mdi:star'
+  - title: Docs
+    link: /docs
+    icon: 'mdi:book-open'
+  - title: More
+    items:
+      - title: About Us
+        link: /about
+        description: Learn more about our mission.
+      - title: Community
+        link: https://community.example.com
+        description: Join our community forum.
+```
+
+`parseNavigation` 工具程式會處理此結構，處理 `title` 和 `description` 的在地化，並根據目前的 URL 路徑確定作用中連結。
+
+### 會話管理與附加元件
+
+頁首右側包含「附加元件」，這是一組用於會話管理和應用程式設定的控制項。預設情況下，這些包括：
+
+- **組織切換器**：如果 blocklet 啟用組織支援，則會出現。
+- **通知中心**：如果 blocklet 包含通知頁面，則會出現。
+- **語系選擇器**：如果設定了多種語言，則會出現。
+- **主題模式切換器**：在亮色和暗色模式之間切換。
+- **會話控制項**：顯示已登入使用者的頭像以及一個包含個人資料、設定和登出連結的選單。對於訪客，則顯示「連接錢包」按鈕。
+
+#### 自訂附加元件
+
+您可以使用 `addons` 屬性來自訂這些附加元件。
+
+**範例：附加一個自訂按鈕**
+
+向 `addons` 屬性提供一個函式。此函式會接收一個包含預設附加元件元素的陣列，讓您可以新增自己的元素。
+
+```javascript "HeaderWithCustomAddon.js" icon=logos:javascript
+import Header from '@blocklet/ui-react/lib/Header';
+import Button from '@mui/material/Button';
+
+function HeaderWithCustomAddon() {
+  return (
+    <Header
+      meta={window.blocklet}
+      addons={(builtInAddons) => (
+        <>
+          {builtInAddons}
+          <Button variant="contained" color="primary" sx={{ ml: 1 }}>
+            Upgrade
+          </Button>
+        </>
+      )}
+    />
+  );
+}
+```
+
+**範例：取代所有附加元件**
+
+提供一個 React 節點或節點陣列以完全取代預設的附加元件。
+
+```javascript "HeaderWithReplacedAddons.js" icon=logos:javascript
+import Header from '@blocklet/ui-react/lib/Header';
+import Button from '@mui/material/Button';
+
+function HeaderWithReplacedAddons() {
+  return (
+    <Header
+      meta={window.blocklet}
+      addons={[
+        <Button key="feedback" variant="outlined" sx={{ ml: 1 }}>
+          Feedback
+        </Button>,
+      ]}
+    />
+  );
+}
+```
+
+### 在嵌入模式中隱藏
+
+`Header` 被 `withHideWhenEmbed` 高階元件所包覆。當應用程式在嵌入式情境中渲染時（例如，在 `sessionStorage` 包含 `EMBED_MODE_KEY: 1` 的 iframe 中），它將自動隱藏。這在將您的 blocklet 整合到另一個應用程式中時，有助於提供更簡潔的 UI。
+
+## 總結
+
+`Header` 元件是一個強大的工具，用於在 Blocklet 應用程式中建立一致的品牌和導覽。透過利用 blocklet 元資料，它簡化了開發過程，同時透過屬性提供了廣泛的自訂選項。
+
+有關相關的佈局元件，請參閱 [Footer](./components-layout-footer.md) 的文件。

package/docs/components-layout-header.zh.md

@@ -0,0 +1,233 @@
+# Header
+
+`Header` 组件为 Blocklet 应用提供了一个响应式且可定制的页眉。它通过直接从 blocklet 的配置（`blocklet.yml`）中读取元数据，自动填充导航链接、应用 logo 和用户会话控件。该组件旨在以最少的配置创建一个功能丰富且一致的页眉。
+
+## 概述
+
+`Header` 组件是主要的导航和品牌元素。它构建于 `@arcblock/ux` 组件之上，包括 `ResponsiveHeader` 和 `NavMenu`，并与用于用户身份验证的 DID Connect 会话上下文无缝集成。
+
+主要功能包括：
+- **自动配置**：从 `blocklet.yml` 中填充应用 logo、标题和导航链接。
+- **响应式设计**：自动适应不同的屏幕尺寸，提供移动设备友好的导航菜单。
+- **会话管理**：与 DID Connect 集成，以显示用户信息、个人资料菜单以及登录/登出按钮。
+- **可定制的插件**：允许注入自定义组件或修改默认元素，如主题切换器和语言选择器。
+- **组织切换**：如果 blocklet 启用了组织支持，则自动包含一个组织切换器。
+- **域名警告**：当管理员和用户通过临时域名访问应用时，通知他们配置自定义域名以提高安全性。
+
+### 工作原理
+
+下图说明了 `Header` 的数据流和组件构成。它从 `blocklet.yml` 文件中读取配置，进行处理，并渲染相应的 UI 元素，包括 logo、导航链接和用户会话控件。
+
+```d2
+direction: down
+
+blocklet-yml: {
+  label: "blocklet.yml"
+  shape: rectangle
+}
+
+Header-Component: {
+  label: "Header 组件"
+  shape: rectangle
+
+  Blocklet-Metadata-Parser: {
+    label: "元数据解析器"
+  }
+
+  UI-Renderer: {
+    label: "UI 渲染器"
+    shape: rectangle
+
+    Logo
+    Navigation-Menu: {
+      label: "导航菜单"
+    }
+    Header-Addons: {
+      label: "Header 插件"
+      shape: rectangle
+      grid-columns: 2
+      Session-Manager: {
+        label: "会话管理器"
+      }
+      Locale-Selector: {
+        label: "语言选择器"
+      }
+      Theme-Toggle: {
+        label: "主题切换器"
+      }
+      Custom-Addons: {
+        label: "自定义插件"
+      }
+    }
+  }
+
+  Blocklet-Metadata-Parser -> UI-Renderer: "提供数据"
+}
+
+blocklet-yml -> Header-Component.Blocklet-Metadata-Parser: "读取配置"
+
+Header-Component.UI-Renderer.Logo
+Header-Component.UI-Renderer.Navigation-Menu
+Header-Component.UI-Renderer.Header-Addons
+
+```
+
+## 基本用法
+
+要使用 `Header`，请将其导入并放置在应用的布局中。它需要 blocklet 的元数据，该元数据通常通过 `window.blocklet` 全局可用。
+
+```javascript "App.js" icon=logos:javascript
+import Header from '@blocklet/ui-react/lib/Header';
+
+function App() {
+  // meta 对象通常来源于 window.blocklet
+  const blockletMeta = window.blocklet || {};
+
+  return (
+    <div>
+      <Header meta={blockletMeta} />
+      <main>
+        {/* 你的应用内容 */}
+      </main>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## Props
+
+`Header` 组件接受多个 props 以进行自定义。
+
+<x-field-group>
+  <x-field data-name="meta" data-type="BlockletMetaProps" data-required="false">
+    <x-field-desc markdown="blocklet 的元数据对象，通常来自 `window.blocklet`。它包含组件用于渲染的信息，如 `name`、`logo` 和 `navigation`。"></x-field-desc>
+  </x-field>
+  <x-field data-name="addons" data-type="Function | React.ReactNode" data-required="false">
+    <x-field-desc markdown="要添加到页眉右侧的自定义元素。如果提供一个函数，它会接收内置插件作为参数，允许您修改、重新排序或补充它们。如果提供一个节点，它将替换所有内置插件。"></x-field-desc>
+  </x-field>
+  <x-field data-name="sessionManagerProps" data-type="SessionManagerProps" data-required="false" data-default='{ "showRole": true }'>
+    <x-field-desc markdown="直接传递给底层 `SessionUser` 组件的 props，用于控制用户会话信息的显示，例如显示用户角色。"></x-field-desc>
+  </x-field>
+  <x-field data-name="homeLink" data-type="string | Function" data-required="false" data-default="publicPath">
+    <x-field-desc markdown="主页链接的 URL，通常通过点击 logo 或品牌名称触发。它默认为 blocklet 的公共路径（`/`）。也可以是一个返回 JSX 元素的函数。"></x-field-desc>
+  </x-field>
+  <x-field data-name="theme" data-type="object" data-required="false">
+    <x-field-desc markdown="一个 Material-UI 主题对象，用于与默认主题合并，从而实现对颜色、排版和其他样式的深度自定义。"></x-field-desc>
+  </x-field>
+  <x-field data-name="hideNavMenu" data-type="boolean" data-required="false" data-default="false">
+    <x-field-desc markdown="如果为 `true`，即使存在导航数据，从 `blocklet.yml` 生成的导航菜单也将被隐藏。"></x-field-desc>
+  </x-field>
+  <x-field data-name="bordered" data-type="boolean" data-required="false" data-default="false">
+    <x-field-desc markdown="如果为 `true`，将在页眉底部应用一条边框以进行视觉分隔。"></x-field-desc>
+  </x-field>
+  <x-field data-name="logo" data-type="React.ReactNode" data-required="false">
+    <x-field-desc markdown="一个自定义 logo 元素，用于覆盖来自 blocklet 元数据的 logo。"></x-field-desc>
+  </x-field>
+  <x-field data-name="brand" data-type="React.ReactNode" data-required="false">
+    <x-field-desc markdown="一个自定义品牌元素（例如，文本或图像），显示在 logo 旁边。"></x-field-desc>
+  </x-field>
+  <x-field data-name="showDomainWarningDialog" data-type="boolean" data-required="false" data-default="true">
+    <x-field-desc markdown="如果为 `false`，则不会显示关于临时域名的警告对话框。"></x-field-desc>
+  </x-field>
+</x-field-group>
+
+## 功能
+
+### 从元数据自动生成导航
+
+`Header` 会根据 `blocklet.yml` 文件中的 `navigation` 数组自动生成其导航菜单。该组件解析此配置以创建主导航链接和嵌套的下拉菜单。
+
+以下是 `blocklet.yml` 中 `navigation` 配置的示例：
+
+```yaml "blocklet.yml" icon=mdi:code-braces
+navigation:
+  - title: Features
+    link: /features
+    icon: 'mdi:star'
+  - title: Docs
+    link: /docs
+    icon: 'mdi:book-open'
+  - title: More
+    items:
+      - title: About Us
+        link: /about
+        description: Learn more about our mission.
+      - title: Community
+        link: https://community.example.com
+        description: Join our community forum.
+```
+
+`parseNavigation` 工具程序会处理此结构，处理 `title` 和 `description` 的本地化，并根据当前 URL 路径确定活动链接。
+
+### 会话管理和插件
+
+页眉的右侧包含“插件”，这是一组用于会话管理和应用设置的控件。默认情况下，这些插件包括：
+
+- **组织切换器**：如果 blocklet 启用了组织支持，则会出现。
+- **通知中心**：如果 blocklet 包含通知页面，则会出现。
+- **语言选择器**：如果配置了多种语言，则会出现。
+- **主题模式切换器**：在亮色和暗色模式之间切换。
+- **会话控件**：显示已登录用户的头像和一个包含个人资料、设置和登出链接的菜单。对于访客，它会显示一个“连接钱包”按钮。
+
+#### 自定义插件
+
+您可以使用 `addons` prop 来自定义这些插件。
+
+**示例：追加一个自定义按钮**
+
+向 `addons` prop 提供一个函数。此函数接收一个包含默认插件元素的数组，允许您添加自己的元素。
+
+```javascript "HeaderWithCustomAddon.js" icon=logos:javascript
+import Header from '@blocklet/ui-react/lib/Header';
+import Button from '@mui/material/Button';
+
+function HeaderWithCustomAddon() {
+  return (
+    <Header
+      meta={window.blocklet}
+      addons={(builtInAddons) => (
+        <>
+          {builtInAddons}
+          <Button variant="contained" color="primary" sx={{ ml: 1 }}>
+            Upgrade
+          </Button>
+        </>
+      )}
+    />
+  );
+}
+```
+
+**示例：替换所有插件**
+
+提供一个 React 节点或节点数组来完全替换默认插件。
+
+```javascript "HeaderWithReplacedAddons.js" icon=logos:javascript
+import Header from '@blocklet/ui-react/lib/Header';
+import Button from '@mui/material/Button';
+
+function HeaderWithReplacedAddons() {
+  return (
+    <Header
+      meta={window.blocklet}
+      addons={[
+        <Button key="feedback" variant="outlined" sx={{ ml: 1 }}>
+          Feedback
+        </Button>,
+      ]}
+    />
+  );
+}
+```
+
+### 在嵌入模式下隐藏
+
+`Header` 被 `withHideWhenEmbed` 高阶组件包裹。当应用在嵌入式上下文（例如，在 `sessionStorage` 包含 `EMBED_MODE_KEY: 1` 的 iframe 中）渲染时，它将自动隐藏。当您的 blocklet 集成到另一个应用中时，这对于提供更简洁的 UI 非常有用。
+
+## 总结
+
+`Header` 组件是在 Blocklet 应用中建立一致品牌和导航的强大工具。通过利用 blocklet 元数据，它简化了开发过程，同时通过 props 提供了广泛的自定义选项。
+
+有关相关的布局组件，请参阅 [Footer](./components-layout-footer.md) 的文档。

package/docs/components-layout.ja.md

@@ -0,0 +1,50 @@
+# レイアウト
+
+レイアウトコンポーネントは、blocklet アプリケーションのユーザーインターフェースを構築するための基礎となるビルディングブロックです。これらは、メインヘッダー、フッター、コンテンツエリアを含む、一貫性のある予測可能なフレームワークを提供します。これらのコンポーネントを活用することで、blocklet のメタデータに基づいて自動的に適応するため、アプリケーション全体でプロフェッショナルで統一感のあるユーザーエクスペリエンスを確保できます。
+
+これらのコンポーネントは、以下に示すように、アプリケーションの主要な視覚構造を形成します。
+
+```d2
+direction: down
+
+"アプリケーション UI": {
+  shape: rectangle
+
+  Header: {
+    label: "ヘッダー"
+    shape: rectangle
+  }
+
+  Dashboard: {
+    label: "ダッシュボード / メインコンテンツ"
+    shape: rectangle
+  }
+
+  Footer: {
+    label: "フッター"
+    shape: rectangle
+  }
+}
+```
+
+このセクションでは、利用可能な主要なレイアウトコンポーネントの概要を説明します。詳細な実装ガイドと API リファレンスについては、各コンポーネントの特定のドキュメントを参照してください。
+
+<x-cards data-columns="3">
+  <x-card data-title="Header" data-icon="lucide:navigation" data-href="/components/layout/header">
+    レスポンシブでカスタマイズ可能なヘッダーを提供し、blocklet のメタデータからナビゲーションリンクとユーザーセッションコントロールを自動的に入力します。
+  </x-card>
+  <x-card data-title="Footer" data-icon="lucide:book-down" data-href="/components/layout/footer">
+    ブランディング、著作権情報、ソーシャルメディアリンク、追加のナビゲーションを含む、アプリケーションの一貫したフッターをレンダリングします。
+  </x-card>
+  <x-card data-title="Dashboard" data-icon="lucide:layout-dashboard" data-href="/components/layout/dashboard">
+    サイドバー、ヘッダー、コンテンツエリアを備えたビルド済みのダッシュボードレイアウトで、管理者インターフェースやユーザー中心のビュー向けに設計されています。
+  </x-card>
+</x-cards>
+
+## 概要
+
+レイアウトコンポーネントは、blocklet のメタデータ（`blocklet.yml`）から直接設定を取得し、シームレスに連携するように設計されており、定型コードを最小限に抑え、開発を加速させます。
+
+続けるには、各コンポーネントの詳細なドキュメントを参照して、それぞれのプロパティ、使用パターン、カスタマイズオプションを理解してください。
+
+- **次へ**: [Header コンポーネント](./components-layout-header.md)について学びます。

package/docs/components-layout.md

@@ -0,0 +1,50 @@
+# Layout
+
+Layout components are the foundational building blocks for structuring your blocklet application's user interface. They provide a consistent and predictable framework, including the main header, footer, and content areas. By leveraging these components, you can ensure a professional and cohesive user experience across your entire application, as they automatically adapt based on your blocklet's metadata.
+
+These components form the primary visual structure of an application, as illustrated below:
+
+```d2
+direction: down
+
+"Application UI": {
+  shape: rectangle
+
+  Header: {
+    label: "Header"
+    shape: rectangle
+  }
+
+  Dashboard: {
+    label: "Dashboard / Main Content"
+    shape: rectangle
+  }
+
+  Footer: {
+    label: "Footer"
+    shape: rectangle
+  }
+}
+```
+
+This section provides an overview of the primary layout components available. For detailed implementation guides and API references, please refer to the specific documentation for each component.
+
+<x-cards data-columns="3">
+  <x-card data-title="Header" data-icon="lucide:navigation" data-href="/components/layout/header">
+    Provides a responsive and customizable header, automatically populated with navigation links and user session controls from the blocklet's metadata.
+  </x-card>
+  <x-card data-title="Footer" data-icon="lucide:book-down" data-href="/components/layout/footer">
+    Renders a consistent footer for your application, including branding, copyright information, social media links, and additional navigation.
+  </x-card>
+  <x-card data-title="Dashboard" data-icon="lucide:layout-dashboard" data-href="/components/layout/dashboard">
+    A pre-built dashboard layout with a sidebar, header, and content area, designed for admin interfaces and user-centric views.
+  </x-card>
+</x-cards>
+
+## Summary
+
+The layout components are designed to work together seamlessly, pulling configuration directly from your blocklet's metadata (`blocklet.yml`) to minimize boilerplate code and accelerate development.
+
+To continue, please explore the detailed documentation for each component to understand their specific props, usage patterns, and customization options.
+
+- **Next**: Learn about the [Header component](./components-layout-header.md).

package/docs/components-layout.zh-TW.md

@@ -0,0 +1,50 @@
+# 佈局
+
+佈局元件是建構 blocklet 應用程式使用者介面的基礎建構模塊。它們提供了一致且可預測的框架，包括主要的 Header、Footer 和內容區域。透過利用這些元件，您可以確保在整個應用程式中提供專業且一致的使用者體驗，因為它們會根據您的 blocklet 元資料自動調整。
+
+這些元件構成應用程式的主要視覺結構，如下圖所示：
+
+```d2
+direction: down
+
+"應用程式 UI": {
+  shape: rectangle
+
+  Header: {
+    label: "Header"
+    shape: rectangle
+  }
+
+  Dashboard: {
+    label: "Dashboard / 主要內容"
+    shape: rectangle
+  }
+
+  Footer: {
+    label: "Footer"
+    shape: rectangle
+  }
+}
+```
+
+本節概述了可用的主要佈局元件。有關詳細的實作指南和 API 參考，請參閱每個元件的具體文件。
+
+<x-cards data-columns="3">
+  <x-card data-title="Header" data-icon="lucide:navigation" data-href="/components/layout/header">
+    提供一個響應式且可自訂的 Header，會自動從 blocklet 的元資料中填入導覽連結和使用者會話控制項。
+  </x-card>
+  <x-card data-title="Footer" data-icon="lucide:book-down" data-href="/components/layout/footer">
+    為您的應用程式呈現一個一致的 Footer，包含品牌、版權資訊、社交媒體連結及其他導覽。
+  </x-card>
+  <x-card data-title="Dashboard" data-icon="lucide:layout-dashboard" data-href="/components/layout/dashboard">
+    一個預先建置的 Dashboard 佈局，包含側邊欄、Header 和內容區域，專為管理員介面和以使用者為中心的視圖而設計。
+  </x-card>
+</x-cards>
+
+## 摘要
+
+佈局元件旨在無縫協同工作，直接從您的 blocklet 元資料（`blocklet.yml`）中提取設定，以最大限度地減少樣板程式碼並加速開發。
+
+若要繼續，請瀏覽每個元件的詳細文件，以了解其特定的 props、使用模式和自訂選項。
+
+- **下一步**：了解 [Header 元件](./components-layout-header.md)。

package/docs/components-layout.zh.md

@@ -0,0 +1,50 @@
+# 布局
+
+布局组件是构建 Blocklet 应用用户界面的基础构建块。它们提供了一个一致且可预测的框架，包括主 Header、Footer 和内容区域。通过利用这些组件，您可以确保在整个应用中提供专业且一致的用户体验，因为它们会根据 Blocklet 的元数据自动进行调整。
+
+这些组件构成了应用的主要视觉结构，如下图所示：
+
+```d2
+direction: down
+
+"应用 UI": {
+  shape: rectangle
+
+  Header: {
+    label: "Header"
+    shape: rectangle
+  }
+
+  Dashboard: {
+    label: "Dashboard / 主内容"
+    shape: rectangle
+  }
+
+  Footer: {
+    label: "Footer"
+    shape: rectangle
+  }
+}
+```
+
+本节概述了可用的主要布局组件。有关详细的实现指南和 API 参考，请参阅每个组件的具体文档。
+
+<x-cards data-columns="3">
+  <x-card data-title="Header" data-icon="lucide:navigation" data-href="/components/layout/header">
+    提供一个响应式且可自定义的 Header，它会根据 Blocklet 的元数据自动填充导航链接和用户会话控件。
+  </x-card>
+  <x-card data-title="Footer" data-icon="lucide:book-down" data-href="/components/layout/footer">
+    为您的应用渲染一个一致的 Footer，包括品牌、版权信息、社交媒体链接和附加导航。
+  </x-card>
+  <x-card data-title="Dashboard" data-icon="lucide:layout-dashboard" data-href="/components/layout/dashboard">
+    一个预构建的 Dashboard 布局，带有侧边栏、Header 和内容区域，专为管理界面和以用户为中心的视图而设计。
+  </x-card>
+</x-cards>
+
+## 总结
+
+布局组件旨在无缝协同工作，直接从 Blocklet 的元数据（`blocklet.yml`）中提取配置，以最大限度地减少样板代码并加速开发。
+
+要继续，请浏览每个组件的详细文档，以了解其具体的属性、使用模式和自定义选项。
+
+- **下一步**：了解 [Header component](./components-layout-header.md)。