ナビゲーションユーティリティ

これらの関数は、Blockletベースのアプリケーションで動的なユーザーインターフェースを構築するためのエンジンです。これらは、blockletのメタデータ（blocklet.yml）とその現在の状態からnavigationプロパティを解析および処理し、メインのblockletとそのすべての子コンポーネントからのナビゲーション項目を、統一されたレンダリング可能な構造に集約します。

これらのユーティリティが解決する中心的な課題は、複雑さの管理です。複合アプリケーションでは、各コンポーネントが独自のナビゲーション項目を宣言できます。これらのユーティリティは、これらの宣言をインテリジェントにマージし、各コンポーネントのマウントポイントに基づいてパスプレフィックスを解決し、国際化（i18n）を処理し、重複またはアクセス不能な項目を除外し、すべてを論理的なセクション（header、footer、userCenterなど）に整理します。

コア処理フロー

以下の図は、さまざまなソースからの生のナビゲーションメタデータが、UI用の最終的な構造化されたリストに変換される高レベルのプロセスを示しています。

Navigation Utilities

メイン関数

parseNavigation(blocklet, options)

これはナビゲーションデータを処理するための主要な関数です。blocklet.ymlファイルからのビルトインナビゲーションの解析から、データベースに保存されているユーザー定義のカスタマイズとのマージまで、ワークフロー全体を統括します。

パラメータ

blocklet object (required) — meta、children、およびsettings.navigationsを含む、完全なblockletの状態オブジェクト。
options object — 解析プロセス用のオプション設定。
- beforeProcess (data: any) => any — ビルトインナビゲーションリストが圧縮されパッチが適用される前に、それを前処理するためのオプションの関数。

戻り値

処理されたナビゲーションデータを含むオブジェクト：

navigationList NavigationItem[] — 最終的にマージされ、クリーンアップされたレンダリング可能なナビゲーション項目のリスト。これが主要な出力です。
components ComponentItem[] — ナビゲーションを宣言するすべての子コンポーネントの配列。名前、リンク、タイトルが含まれます。
builtinList NavigationItem[] — 設定からのカスタムナビゲーションとマージされる前の、blocklet.ymlファイルから純粋に派生した処理済みのナビゲーション項目のリスト。

使用例

基本的な使用法

import { parseNavigation } from '@blocklet/meta/lib/navigation';

// 単純化されたblockletの状態オブジェクト
const blockletState = {
  did: 'z1...',
  meta: {
    name: 'my-app',
    title: 'My App',
    navigation: [
      { id: 'home', title: 'Home', link: '/' },
      { id: 'dashboard', title: 'Dashboard', component: 'dashboard-blocklet' },
    ],
  },
  children: [
    {
      did: 'z2...',
      mountPoint: '/dashboard',
      meta: {
        name: 'dashboard-blocklet',
        title: 'Dashboard',
        navigation: [
          { id: 'overview', title: 'Overview', link: '/overview' },
        ],
      },
    },
  ],
  settings: {
    // データベースからのカスタムナビゲーション項目
    navigations: [
      {
        id: 'external-link',
        title: 'External Site',
        link: 'https://example.com',
        section: 'header',
        from: 'db',
        visible: true,
      },
    ],
  },
};

const { navigationList, components } = parseNavigation(blockletState);

console.log(navigationList);
/*
以下のような構造化された配列を出力します:
[
  { id: '/home', title: 'Home', link: '/', ... },
  {
    id: '/dashboard/overview',
    title: 'Overview',
    link: '/dashboard/overview',
    component: 'dashboard-blocklet',
    ...
  },
  { id: 'external-link', title: 'External Site', ... }
]
*/
console.log(components);
/*
コンポーネント情報を出力します:
[
  {
    did: 'z2...',
    name: 'dashboard-blocklet',
    link: '/dashboard',
    title: 'Dashboard',
    ...
  }
]
*/

ヘルパー関数

parseNavigationはオールインワンのソリューションですが、ライブラリはいくつかの基礎となるヘルパー関数もエクスポートしています。これらは、ナビゲーションデータに対してカスタム操作を実行する必要がある高度なユースケースで役立ちます。

deepWalk

ツリー状のオブジェクトを再帰的に走査し、各ノードにコールバックを適用する汎用ユーティリティ。

flattenNavigation

ネストされたナビゲーションツリーをフラットな配列に変換します。オプションで指定された深さまで変換できます。

nestNavigationList

項目が`parent` IDプロパティを持つフラットな配列から、ネストされたナビゲーションツリーを再構築します。

splitNavigationBySection

複数のセクションに属するナビゲーション項目を、各セクションごとの個別の項目に分解します。

filterNavigation

`visible: false`とマークされた項目や、コンポーネントが見つからない項目を削除して、ナビゲーションリストをフィルタリングします。

joinLink

親のリンクと子のリンクをインテリジェントに結合し、プレフィックスと絶対URLを正しく処理します。

flattenNavigation(list, options)

この関数は、ナビゲーション項目のツリーを受け取り、それを単一レベルの配列にフラット化します。深いネストをサポートしないメニューでの表示や、処理を容易にするためにナビゲーションデータを準備する際に特に役立ちます。

パラメータ

list NavigationItem[] (required) — ツリー構造のナビゲーションリスト。
options object — フラット化のための設定オプション。
- depth number (default: 1) — ツリーをフラット化する深さ。深さ1は完全なフラット化を意味します。
- transform (current, parent) => any — 各項目がフラット化される際に変換するための関数。

例

ナビゲーションツリーのフラット化

const nestedNav = [
  {
    id: 'parent1',
    title: 'Parent 1',
    items: [
      { id: 'child1a', title: 'Child 1a' },
      { id: 'child1b', title: 'Child 1b' },
    ],
  },
];

const flatNav = flattenNavigation(nestedNav, { depth: 2 }); // 2レベルまでフラット化

console.log(flatNav);
/*
[
  { id: 'parent1', title: 'Parent 1' },
  { id: 'child1a', title: 'Child 1a' },
  { id: 'child1b', title: 'Child 1b' }
]
*/

nestNavigationList(list)

flattenNavigationの逆の操作です。この関数は、子がparent IDを介して親を参照するナビゲーション項目のフラットな配列を受け取り、元のツリー構造を再構築します。

パラメータ

list NavigationItem[] (required) — idとparentプロパティを持つナビゲーション項目のフラットな配列。

例

フラットなリストからツリーを構築

const flatNav = [
  { id: 'parent1', title: 'Parent 1', section: 'header' },
  { id: 'child1a', title: 'Child 1a', parent: 'parent1', section: 'header' },
  { id: 'root2', title: 'Root 2', section: 'header' },
];

const nestedNav = nestNavigationList(flatNav);

console.log(nestedNav);
/*
[
  {
    id: 'parent1',
    title: 'Parent 1',
    section: 'header',
    items: [ { id: 'child1a', title: 'Child 1a', ... } ],
  },
  { id: 'root2', title: 'Root 2', section: 'header' },
]
*/

これらのユーティリティは、複雑なコンポーネントベースのアプリケーションでナビゲーションを管理するための包括的なツールキットを提供します。これらのナビゲーション項目内で使用されるURLとパスのフォーマット方法を理解するには、URL & パスユーティリティのドキュメントに進んでください。