このドキュメントでは、Blocklet UI React ライブラリの基本原則について説明します。中心的な設計思想はメタデータ駆動アプローチであり、Header、Footer、Dashboard などの UI コンポーネントは、blocklet のメタデータに基づいて自動的に設定・レンダリングされます。この戦略により、一貫性が確保され、定型的なコードが削減され、ユーザーの役割や言語設定に適応する動的な UI が可能になります。
中心的な考え方は、単一の設定ファイル（通常は blocklet.yml）が、アプリケーションの全体的な構造と外観に関する信頼できる唯一の情報源として機能するということです。ライブラリはこのメタデータを読み取り、処理し、それを使用して適切な UI 要素を構築します。
メタデータ駆動の原則
ライブラリの動作は、単純なデータフローとして視覚化できます。blocklet のメタデータがライブラリへの入力として提供され、ライブラリはそれをパイプラインを通じて処理し、完全にレンダリングされた UI コンポーネントを生成します。これにより、開発者がアプリケーションごとに共通のレイアウト要素を手動で構築・設定する必要がなくなります。
この自動化されたプロセスは、明確に定義されたメタデータ構造に依存しており、それについては次のセクションで詳しく説明します。
Blocklet メタデータの構造
ライブラリは、UI のレンダリングに必要なすべての情報を含む BlockletMetaProps と呼ばれる特定のオブジェクト構造を想定しています。以下に、この構造の詳細な内訳を示します。
- appName
string— アプリケーション名。通常は Header に表示されます。 - appLogo
React.ReactNode— アプリケーションのロゴ用の React ノード。これも Header に表示されます。 - enableConnect
boolean— DID Connect ボタンを表示するかどうかを決定します。 - enableLocale
boolean— 言語選択コンポーネントを表示するかどうかを決定します。 - theme
object— アプリケーションレイアウトのカラースキームを定義します。- background
string— Header や Footer などのレイアウトコンポーネントの背景色を設定します。
- background
- navigation
array— アプリケーション全体のリンクとメニューを定義するナビゲーション項目オブジェクトの配列です。- title
string | object(required) — ナビゲーション項目の表示テキスト。i18n のためにオブジェクトにすることも可能です。 - link
string | object— ナビゲーション項目の URL。i18n のためにオブジェクトにすることも可能です。 - icon
string— タイトルの横に表示するアイコン用の Iconify 互換文字列です。 - section
string | array— 項目が表示される場所を指定します。例：'header'、'footer'、'dashboard'。 - role
string | array— この項目を閲覧できるユーザーロールを定義します。例：'admin'、'guest'。 - items
array— ドロップダウンメニューやサブメニューを作成するための、ネストされたナビゲーション項目の配列です。
- title
ナビゲーション設定の例
navigation 配列は、メタデータの最も重要な部分です。すべてのリンク、メニュー、およびその配置を構造化された方法で定義する手段を提供します。
blocklet.yml でのナビゲーション設定
# blocklet.yml
navigation:
- title: 機能
link: /features
- title:
en: About Us
ja: 私たちについて
link:
en: /about
ja: /about-us
section: footer
- title: 管理ダッシュボード
link: /admin
section: dashboard
role: admin
- title: ソーシャル
section: social
items:
- title: Twitter
link: https://twitter.com/arcblock
icon: mdi:twitter
- title: GitHub
link: https://github.com/arcblock
icon: mdi:githubこの例は、いくつかの主要な機能を示しています：
- シンプルなヘッダーリンク（「機能」）。
- 多言語対応のフッターリンク（「私たちについて」）。
- ダッシュボード用の管理者専用リンク。
- フッター向けのソーシャルメディアリンクのグループ。
データ処理パイプライン
レンダリングの前に、ライブラリは生のメタデータを一連のステップで処理し、UI コンポーネント用に準備します。
1. パースとセクション分割
最初のステップは、navigation 配列をパースし、項目を section プロパティに基づいてグループ化することです。単一のナビゲーション項目は、section の値に配列を使用することで、複数のセクションに割り当てることができます。
parseNavigation ユーティリティは、各項目を事前に定義されたセクションに分類します：
header: メインアプリケーションのヘッダー用。footer: フッターの主要なリンク用。social: 通常はフッターに配置されるソーシャルメディアアイコン用。bottom: フッターの最下部にある法的または二次的なリンク用。dashboard: ダッシュボードレイアウトのサイドバーナビゲーション用。sessionManager: ユーザーセッションコンポーネント内のメニュー用。userCenter: ユーザープロファイルエリア内のタブまたはリンク用。
項目に section プロパティがない場合、デフォルトで header になります。
2. 国際化 (i18n)
ライブラリは、複数の言語を組み込みでサポートしています。ナビゲーション項目の title または link プロパティが言語キー（例：en、ja）を持つオブジェクトである場合、getLocalizedNavigation 関数はユーザーの現在のロケールに基づいて正しい文字列を自動的に選択します。
i18n オブジェクトの例
// 多言語サポートを持つナビゲーション項目
{
title: {
en: 'Home',
ja: 'ホームページ'
},
link: {
en: '/home',
ja: '/ja/home'
}
}3. ロールベースのフィルタリング
動的なユーザーエクスペリエンスを作成するために、ナビゲーション項目を特定のユーザーロールに制限することができます。filterNavByRole 関数は、各項目の role プロパティを現在のセッションの user.role と比較してナビゲーションリストをフィルタリングします。
- 項目に
roleプロパティがない場合、それは全員に表示されます。 - 項目に
roleプロパティ（例：['admin', 'editor']）がある場合、そのロールが配列に含まれるユーザーにのみ表示されます。 guestロールは、未認証のユーザーに適用される特別な値です。
このメカニズムにより、メタデータで包括的なナビゲーション構造を定義し、ログインしているユーザーの権限に基づいて UI を自動的に適応させることができます。
まとめ
Blocklet UI React ライブラリのコアコンセプトは、一元化されたメタデータオブジェクトを活用して、共通の UI コンポーネントの設定とレンダリングを駆動することです。このメタデータ駆動アプローチは、いくつかの利点を提供します：
- 信頼できる唯一の情報源：アプリケーションの構造、ブランディング、ナビゲーションが 1 か所で定義されます。
- 一貫性：アプリケーションのさまざまな部分で一貫したルックアンドフィールを保証します。
- ボイラープレートの削減：ヘッダーやフッターのような共通のレイアウト要素を手動でコーディングする必要がなくなります。
- 動的 UI：国際化とロールベースのアクセス制御をネイティブでサポートし、UI がユーザーとその権限に応じて動的に適応できるようにします。
これらの原則を明確に理解することで、ライブラリのコンポーネントを効果的に活用できます。特定のコンポーネントとその使用方法に関する詳細については、コンポーネントセクションを参照してください。