React Dock Manager (ドック マネージャー) の概要

Infragistics React Dock Manager は、ペインでアプリケーションのレイアウトを管理する方法を提供します。エンド ユーザーはペインをピン固定、サイズ変更、移動、最大化、非表示にすることでカスタマイズできます。

React ドック マネージャーの例

この例は、アプリケーションで使用できる IgrDockManager のほとんどの機能とドッキング オプションを示しています。

ドック マネージャー パッケージをインストールするには、以下のコマンドを実行します。

npm install --save igniteui-react-dockmanager

使用方法

ドック マネージャーをインポートした後、ページに追加できます。

<IgrDockManager id="dockManager">
</IgrDockManager>

ドック マネージャーにはペインのレイアウトを説明する Layout プロパティがあります。レイアウトを定義するには、RootPane プロパティを設定し、子ペインを追加します。以下は、単一のコンテンツ ペインでレイアウトを定義する方法です。

import {  IgrDockManager, IgrDockManagerPaneType, IgrSplitPaneOrientation } from 'igniteui-react-dockmanager';

// ...

this.dockManager = document.getElementById("dockManager") as IgrDockManager;
this.dockManager.layout = {
    rootPane: {
        type: IgrDockManagerPaneType.splitPane,
        orientation: IgrSplitPaneOrientation.horizontal,
        panes: [
            {
                type: IgrDockManagerPaneType.contentPane,
                contentId: 'content1',
                header: 'Pane 1'
            }
        ]
    }
};

ペインのコンテンツをロードするために、ドック マネージャーはスロットを使用します。コンテンツ要素の slot 属性はレイアウト構成のコンテンツ ペインの ContentId と一致する必要があります。エンドユーザーがペインのサイズを変更する場合は、予測可能な応答のために、コンテンツ要素の幅と高さを 100% に設定することを強くお勧めします。

<IgrDockManager id="dockManager">
    <div slot="content1" style={{ width: '100%', height: '100%' }}>Content 1</div>
</IgrDockManager>

ドック マネージャーは複数の pane types を定義します。

• IgrContentPane
• IgrSplitPane
• IgrTabGroupPane
• IgrDocumentHost

各タイプのペインには Size プロパティがあります。親の方向に応じて、サイズはペインの幅または高さに影響します。ペインのサイズはその兄弟ペインのサイズに相対し、デフォルトは 100 です。2 つの兄弟ペインがあり、最初のペインのサイズが 200 に設定され、2 番目のペインのサイズが 100 に設定されている場合、最初のペインは 2 番目のペインの 2 倍のサイズになり、これら 2 つのペインが使用可能なスペースをすべて埋めてしまいます。親の絶対サイズが 900px の場合、それぞれ 600px と 300px にサイズ設定されます。特定のペインのサイズをピクセル単位で指定する場合は、使用可能なすべてのスペースの相対的な配分に依存するのではなく、親の分割ペインの useFixedSize を設定する必要があります。

エンドユーザーは、ランタイムにレイアウトをカスタマイズするために以下のアクションを実行できます。

• ペインをピン設定 / ピン解除します。
• ペインをサイズ変更します。
• ペインを閉じます。
• ペインをフロートさせるためにドラッグします。
• フローティング ペインを移動します。
• フローティング ペインをドックします。
• ペインを最大化します。

これらはすべて、Dock Manager の Layout プロパティに反映されます。

コンテンツ ペイン

IgrContentPane ヘッダーとコンテンツを含むペインを表します。スプリットされたペインまたはタブ グループ ペイン内でホストできます。以下はコンテンツ ペインの定義方法です。

const contentPane: IgrContentPane = {
    type: IgrDockManagerPaneType.contentPane,
    contentId: 'content1',
    header: 'Pane 1'
}

Header プロパティはコンテンツ ペインのテキスト ヘッダーを提供するために使用されます。このテキストは複数の場所で描画されます。トップコンテンツペインヘッダー、ペインがタブグループにある場合はタブヘッダー、ペインが固定解除されている場合は固定解除ヘッダーです。HeaderId、TabHeaderId および UnpinnedHeaderId プロパティを使用してそれぞれこれらの場所にカスタム スロット コンテンツを提供できます。これらのプロパティのいずれかが設定されていない場合、Header テキストが使用されます。以下は、タブ ヘッダー スロット コンテンツを提供する方法です。

<IgrDockManager id="dockManager">
    <div slot="content1" style={{ width: '100%', height: '100%' }}>Content 1</div>
    <span slot="tabHeader1">Pane 1 Tab</span>
</IgrDockManager>

const contentPane: IgrContentPane = {
    type: IgrDockManagerPaneType.contentPane,
    contentId: 'content1',
    header: 'Pane 1',
    tabHeaderId: 'tabHeader1'
}

ペインのピン固定が解除されると、ドック マネージャーのいずれかの端にタブ ヘッダーとして表示されます。エンドユーザーに選択されると、そのコンテンツはドッキングされたピン固定ペインの上に表示されます。コンテンツ ペインのピン固定を解除するには、IsPinned プロパティを false に設定します。

const contentPane = {
    type: IgrDockManagerPaneType.contentPane,
    contentId: 'content1',
    header: 'Pane 1',
    isPinned: false
}

IsPinned プロパティはドキュメント ホストの外部にドッキングされているコンテンツ ペインのみに影響します。また、フローティング ペインでホストされているコンテンツ ペインのピン固定を解除することはできません。

デフォルトでは、コンテンツ ペインのピン固定解除先は、ドキュメント ホストに対するペインの相対的な位置に基づいて自動的に計算されます。複数のドキュメント ホストが定義されている場合、ピン固定されていないコンテンツ ペインの親階層で最も近いホストが使用されます。ドキュメント ホストが定義されていない場合、デフォルトの場所 Left が使用されます。UnpinnedLocation プロパティを使用してピン固定が解除されたペインの行き先を設定することも可能です。

AllowClose、AllowPinning、AllowDocking および AllowFloating プロパティを使用して、コンテンツ ペインで許可されるエンドユーザー操作を設定できます。

コンテンツ ペインを定義するときに、DocumentOnly プロパティを true に設定して、ペインをドキュメント ホストにのみドッキングできるようにすることができます。

コンテンツ ペインとそのコンテンツに対するユーザーの操作を制限するには、Disabled プロパティを true に設定します。これにより、単一のフローティング ペインでない限り、すべてのユーザーがペインを操作できなくなります。後者は移動、最大化、または閉じることができるため (最大化および閉じるためのペインの設定に従って)、ユーザーはその下の要素を見ることができますが、そのコンテンツを操作することはできません。

デフォルトでは、ペインを閉じると、Layout オブジェクトから削除されます。ただし、場合によってはペインを一時的に非表示にして後で表示することもできます。Layout オブジェクトを変更せずにそれを行うには、コンテンツペインの Hidden プロパティを使用できます。プロパティを true に設定すると UI から非表示になりますが、Layout オブジェクトに残ります。デフォルトの閉じる動作をオーバーライドするには、このように PaneClose イベントにサブスクライブできます。

this.dockManager.addEventListener('paneClose', ev => {
    for (const pane of ev.detail.panes) {
        pane.hidden = true;
    }
    ev.preventDefault();
});

分割ペイン

IgrSplitPane は、Orientation プロパティに基づいてすべての子 Panes を水平または垂直に積み重ねるコンテナー ペインです。以下は、2 つの子コンテンツ ペインを持つ水平の分割ペインの定義方法です。

const splitPane: IgrSplitPane = {
    type: IgrDockManagerPaneType.splitPane,
    orientation: IgrSplitPaneOrientation.horizontal,
    panes: [
        {
            type: IgrDockManagerPaneType.contentPane,
            contentId: 'content1',
            header: 'Pane 1'
        },
        {
            type: IgrDockManagerPaneType.contentPane,
            contentId: 'content2',
            header: 'Pane 2'
        }
    ]
}

分割ペインは、他のスプリットされたペインを含むすべてのペイン タイプの子ペインを含むことができます。

デフォルトでは、分割ペインが空の場合は表示されません。ただし、その動作を変更したい場合は、AllowEmpty プロパティを true に設定すると、内部にペインがない場合でも、分割ペインが UI に表示されます。

タブ グループ ペイン

IgrTabGroupPane は、その子コンテンツ Panes をタブ コンポーネントのタブとして表示します。以下は、2 つのタブそれぞれにコンテンツ ペインを持つタブ グループ ペインの定義方法です。

const tabGroupPane: IgrTabGroupPane = {
    type: IgrDockManagerPaneType.tabGroupPane,
    panes: [
        {
            type: IgrDockManagerPaneType.contentPane,
            contentId: 'content1',
            header: 'Pane 1'
        },
        {
            type: IgrDockManagerPaneType.contentPane,
            contentId: 'content2',
            header: 'Pane 2'
        }
    ]
}

すべてのタブ ヘッダーを表示する十分なスペースがない場合、タブ グループは非表示タブを含む [その他のタブ] メニューを表示します。そのメニューのタブ項目をクリックすると、タブが選択され、最初の位置に移動します。

タブは、それらが配置されているタブ グループから切り離さずに並べ替えることもできます。タブをクリックして、希望の位置まで左または右にドラッグできます。選択したタブをタブ領域の外にドラッグすると、フローティング ペインにデタッチされます。

タブがないときにタブ グループ ペインを UI に表示する場合は、AllowEmpty プロパティを true に設定します。

ドキュメント ホスト

IgrDocumentHost コード編集やデザイン ビュー用の Visual Studio のタブと同様のドキュメント タブ領域です。以下は、2 つのドキュメント タブを持つドキュメント ホストを定義する方法です。

const docHost: IgrDocumentHost = {
    type: IgrDockManagerPaneType.documentHost,
    rootPane: {
        type: IgrDockManagerPaneType.splitPane,
        orientation: IgrSplitPaneOrientation.horizontal,
        panes: [
            {
                type: IgrDockManagerPaneType.tabGroupPane,
                panes: [
                    {
                        type: IgrDockManagerPaneType.contentPane,
                        contentId: 'content1',
                        header: 'Grid'
                    },
                    {
                        type: IgrDockManagerPaneType.contentPane,
                        contentId: 'content4',
                        header: "List"
                    }
                ]
            }
        ]
    }
}

フローティング ペイン

フローティング ペインは、フローティング ウィンドウで他のペインの上に描画される分割ペインです。フローティング ペインの定義は、Layout の FloatingPanes プロパティに保存されます。以下は、単一のコンテンツ ペインを含むフローティング ペインを追加する方法です。

const layout: IgrDockManagerLayout = {
    rootPane: {
        // ...
    },
    floatingPanes: [
        {
            type: IgrDockManagerPaneType.splitPane,
            orientation: IgrSplitPaneOrientation.horizontal,
            floatingLocation: { x: 80, y: 80 },
            floatingWidth: 200,
            floatingHeight: 150,
            floatingResizable: true,
            panes: [
                {
                    type: IgrDockManagerPaneType.contentPane,
                    contentId: 'content1',
                    header: 'Floating Pane 1'
                }
            ]
        }
    ]
};

FloatingLocation、FloatingWidth と FloatingHeight プロパティは絶対寸法をピクセル単位で表します。これらのプロパティは、FloatingPanes 配列の分割ペインにのみ適用されることに注意してください。

FloatingResizable と AllowFloatingPanesResize を使用して、フローティング ペインのサイズ変更を許可するかどうかを設定できます。allowFloatingPanesResize は IgcDockManagerComponent プロパティであるため、値が false に設定されている場合、フローティング ペインのサイズを変更することはできません。floatingResizable プロパティは、floatPanes 配列の各分割ペインに個別に適用できます。プロパティ値が設定されていない場合、デフォルトで allowFloatingPanesResize プロパティの値になります。floatingResizable プロパティが特定のペインに設定されている場合、その値は allowFloatingPanesResize プロパティ値に優先されます。

アクティブ ペイン

ドック マネージャー コンポーネントは、フォーカスを含むコンテンツ ペインをハイライト表示し、ActivePane プロパティで公開します。プロパティを設定することによってアクティブ ペインをプログラムで変更できます。ActivePaneChanged イベントにサブスクライブして、ActivePane プロパティの変更をリッスンすることもできます。

this.dockManager.addEventListener('activePaneChanged', ev => {
    console.log(ev.detail.oldPane);
    console.log(ev.detail.newPane);
});

ドッキング

フローティング ペインのドラッグを開始すると、ドラッグしたペインの位置に応じて異なるドッキング インジケーターが表示されます。ドッキングには、ルート ドッキング、ペイン ドッキング、ドキュメント ホスト ドッキング、スプリッター ドッキングの 4 つの主なタイプがあります。ルート ドッキングが無効になっている場合、エッジ ドッキングは追加の動作として使用でき、ルート分割ペインの方向に沿って動作します。

ルート ドッキング

このタイプのドッキングでは、ペインをドラッグしているときに、ドックマネージャーの四隅付近に 4 つの矢印ドッキングインジケーターが表示されます。ペインをドロップすると、Dock Manager の RootPane の直接の子要素になります。視覚的には、新しくドッキングされたペインはそれぞれの端にスナップされ、ドック マネージャーの幅または高さの最大半分を占め、他のすべてのコンテンツは残りの半分に移動します。

ペイン ドッキング

フローティング ペインをコンテンツ ペインまたはタブ グループ ペインの上にドラッグすると、ドッキング インジケーターがペインの中央に表示されます。ペインをドロップすると、ターゲット ペインの任意の側にスナップされるか、ターゲット ペインとグループ化されてタブ付きレイアウトが作成されます。初期レイアウトとドッキング位置の組み合わせにより、ドッキング操作により、ドラッグされたペインとターゲットペインの両方の新しい親となる分割されたペインまたはタブ グループ ペインが動的に作成されることがあります。

ドキュメント ホスト ドッキング

ドラッグしたペインがドキュメント ホストの上にある場合は、ターゲット ペインまたはドキュメント ホスト全体に対するドッキングを可能にする追加のドッキング インジケーターが表示されます。

スプリッター ドッキング

スプリッター ドッキングを使用すると、エンド ユーザーは既存の分割レイアウト内にペインを正確に配置できます。フローティング ペインをドラッグしているときに、カーソルが 2 つのペイン間のスプリッターの近くに移動すると、そのスプリッターの上にドッキング インジケーターが表示されます。

ユーザーがこのインジケーター上にペインをドロップすると、Dock Manager は、ターゲットとなるスプリッターを所有する分割ペインにペインを挿入し、隣接するペインを調整してスペースを確保します。これにより、レイアウト全体を再構築することなく、2 つの既存のペインのちょうど間に新しいツールやビューを挿入して、複雑なレイアウトを簡単に調整できます。

このレベルの精度を必要としないシンプルなエクスペリエンスが必要な場合は、Dock Manager の allowSplitterDock プロパティを false に設定することで、スプリッター ドッキングを無効にできます。

エッジ ドッキング

エッジ ドッキングにより、エンド ユーザーは、特定のスプリッターやペインを慎重にターゲットにすることなく、メイン レイアウトの最初または最後に重要なペインを追加する簡単な方法が提供されます。allowRootDock プロパティを false に設定してルート ドッキングを無効にすると、Dock Manager はルート分割ペインの最初と最後の位置に沿ってエッジ ドッキング インジケーターを自動的に有効にします。ルート分割ペインは水平または垂直のいずれかであるため、エッジ ドッキングはその単一方向 (水平ルートの場合は左/右、垂直ルートの場合は上/下) でのみ使用できます。

この動作は、ルート ペインがスクロール可能な場合 (useFixedSize プロパティが true に設定されており、コンテンツが表示領域を超えている場合) に特に便利です。これらのシナリオでは、ユーザーは次のことができます。

• 水平ルート分割ペインの場合、任意のペインを 左端に向かってドラッグして最初の項目としてドッキングするか、右端に向かってドラッグして最後の項目としてドッキングします。
• 垂直ルート分割ペインの場合、任意のペインを上端に向かってドラッグして最初の項目としてドッキングするか、下端に向かってドラッグして最後の項目としてドッキングします。

ユーザーがエッジ ドッキング インジケーター上にペインをドロップすると、Dock Manager は選択した端にペインを挿入し、自動的にビューにスクロールします。これにより、複雑でスクロール可能なレイアウトでも、新しく追加されたツール ウィンドウやダッシュボードがすぐに表示されるようになります。

レイアウトの編集

一部のシナリオでは、ペインの追加または削除、方向の変更などによって、Dock Manager のレイアウトをカスタマイズする必要がある場合があります。次に例を示します。

const splitPane = this.dockManager.layout.rootPane.panes[0] as IgrSplitPane;
const contentPane = splitPane.panes[0] as IgrContentPane;
this.dockManager.removePane(contentPane);

これは、レイアウト オブジェクトを更新するだけです。Dock Manager の更新をトリガーして変更を UI に反映するには、レイアウト オブジェクトを再割り当てする必要があります。

this.dockManager.layout = { ...this.dockManager.layout };

レイアウトの保存／読み込み

レイアウトを復元または永続化するには、Layout プロパティの値を取得または設定します。以下は、文字列化された JSON としてレイアウトを保存する方法です。

private savedLayout: string;

private saveLayout() {
    this.savedLayout = JSON.stringify(this.dockManager.layout);
}

private loadLayout() {
    this.dockManager.layout = JSON.parse(this.savedLayout);
}

イベント

ドック マネージャー コンポーネントは、ペインを閉じる、ピン固定、サイズ変更、ドラッグするなど、特定のエンドユーザーの操作が実行されるとイベントを発生させます。ドック マネージャーのイベントの完全なリストは、こちらです。

PaneClose イベントのイベント リスナーを追加する方法は以下の通りです。

カスタマイズ

Dock Manager コンポーネントは、スロットとパーツを使用してすべてのボタンをカスタマイズするオプションを提供します。ボタンを変更するには、Dock Manager 内で独自の要素を定義し、slot 属性を対応する識別子に設定します。

これらのスロットとパーツを使用して、カスタマイズされた Dock Manager レイアウトを作成してみましょう。最初に、closeButton、maximizeButton、minimizeButton、pinButton、および unpinButton スロットを使用して独自のアイコンを提供します。

<IgrDockManager id="dockManager">
    <div slot="content1" class="dockManagerContent">Content 1</div>
    <div slot="content2" class="dockManagerContent">Content 2</div>
    <div slot="content3" class="dockManagerContent">Content 3</div>
    {/* ... */}

    <button slot="closeButton">x</button>

    <button slot="maximizeButton">
        <img src="https://www.svgrepo.com/show/419558/arrow-top-chevron-chevron-top.svg" alt="arrow-top-chevron-chevron-top" />
    </button>

    <button slot="minimizeButton">
        <img src="https://www.svgrepo.com/show/419557/bottom-chevron-chevron-down.svg" alt="bottom-chevron-chevron-down" />
    </button>

    <button slot="pinButton">
        <img src="https://www.svgrepo.com/show/154123/pin.svg" alt="pin" />
    </button>

    <button slot="unpinButton">
        <img src="https://www.svgrepo.com/show/154123/pin.svg" alt="pin" />
    </button>
</IgrDockManager>

次に、スタイルシートで公開されたパーツを使用します。こうすることで、コンポーネントのスタイルを完全に制御できるようになります。

igc-dockmanager::part(unpinned-tab-area) {
    background: #bee9ec;
}

igc-dockmanager::part(unpinned-tab-area--left) {
    border-right: 1px dashed #004d7a;
}

igc-dockmanager::part(unpinned-tab-area--bottom) {
    border-top: 1px dashed #004d7a;
}

igc-dockmanager::part(tab-header-close-button),
igc-dockmanager::part(pane-header-close-button) {
    background-color: #e73c7e;
}

igc-dockmanager::part(pane-header-pin-button),
igc-dockmanager::part(pane-header-unpin-button) {
  background: rgb(218, 218, 218);
  border: none;
  width: 24px;
  height: 24px;
  color: #fff;
}

igc-dockmanager::part(tabs-maximize-button),
igc-dockmanager::part(tabs-minimize-button),
igc-dockmanager::part(pane-header-minimize-button),
igc-dockmanager::part(pane-header-maximize-button) {
  width: 24px;
  height: 24px;
  border: none;
  transition: opacity 250ms ease-in-out;
  opacity: 0.3;
  margin-right: 15px;
  margin-top: -5px;
  margin-left: 0px;
}

すべて順調にいけば、アイコンとタブ領域がカスタマイズされた Dock Manager ができあがっているはずです。実際に見てみましょう。

以下に、すべてのボタンおよびスプリッターハンドルのスロット名の一覧を記載しています。

各スロットに対応するパーツは、このページのスタイル設定セクションにあるCSS パーツで確認できます。

CSS 変数

次の表では、ドック マネージャー コンポーネントのスタイル設定に使用されるすべての CSS 変数について説明します。

キーボード ナビゲーション

キーボード ナビゲーションは、ドック マネージャーのアクセシビリティを強化し、すべてのペインをナビゲートしたり、アクティブなペインをドッキングしてビューを複数の方向に分割したりするなど、エンドユーザーにさまざまな操作を提供します。

ショートカットは以下の通りです。

ドッキング

• CMD/CTRL + SHIFT + ↑ グローバルの上へのドック。
• CMD/CTRL + SHIFT + ↓ グローバルの下へのドック。
• CMD/CTRL + SHIFT + → グローバルの右へのドック。
• CMD/CTRL + SHIFT + ← グローバルの左へのドック。
• SHIFT + ↑ タブ グループに複数のタブがある場合、ビューが分割され、フォーカスされたタブが上にドッキングされます。
• SHIFT + ↓ タブ グループに複数のタブがある場合、ビューが分割され、フォーカスされたタブが下にドッキングされます。
• SHIFT + → タブ グループに複数のタブがある場合、ビューが分割され、フォーカスされたタブが右にドッキングされます。
• SHIFT + ← タブ グループに複数のタブがある場合、ビューが分割され、フォーカスされたタブが左にドッキングされます。

ナビゲーション

• CMD/CTRL + F6 または CMD/CTRL + → ドキュメント ホストの次のタブにフォーカスします。
• CMD/CTRL + SHIFT + F6 または CMD/CTRL + ← ドキュメント ホストの前のタブにフォーカスします。
• ALT + F6 次のコンテンツ ペインにフォーカスします。
• ALT + SHIFT + F6 前のコンテンツ ペインにフォーカスします。

ペイン ナビゲーター

次のキーボード ショートカットは、ペインやドキュメントを反復できるナビゲーターを示しています。

• CMD/CTRL + F7 または CMD/CTRL + F8 最初のドキュメントから開始します。
• ALT + F7 または ALT + F8 最初のペインから開始します。
• CMD/CTRL + SHIFT + F7 または CMD/CTRL + SHIFT + F8 最後のドキュメントから逆方向に開始します。
• ALT + SHIFT + F7 または ALT + SHIFT + F8 最後のペインから逆方向に開始します。

その他

• ALT + F3 アクティブなペインを閉じます。

サンプル demo で上記のすべてのアクションを練習しましょう。

スタイル設定

ドック マネージャーは、シャドウ DOM を使用してスタイルと動作をカプセル化します。その結果、通常の CSS セレクターでその内部要素を単純にターゲットにすることはできません。そのため :: part CSS セレクターでターゲットにできるコンポーネント parts を公開しています。

igc-dockmanager::part(content-pane) {
  border-radius: 10px;
}

以下の例では、公開されているCSSパーツを使用してDock Managerをカスタマイズする方法をご紹介します。

CSS パーツ

テーマ

ドック マネージャーには、light (明るい) テーマと dark (暗い) テーマがあります。Light テーマがデフォルトです。Dark に変更するには、igc.themes.css ファイルを css にインポートし、dark-theme クラスをドック マネージャーまたはその親に追加します。

@import 'igniteui-dockmanager/dist/collection/styles/igc.themes';

<IgrDockManager className="dark-theme"></IgrDockManager>

ローカライズ

ドック マネージャーは、コンテキスト メニュー、ツールチップ、および ARIA 属性で使用される文字列のローカライズをサポートします。デフォルトでは、ルートの <html> 要素の lang 属性を読み取って使用する言語を決定します。lang 属性が設定されていないか、サポートされていない値に設定されている場合、ドック マネージャーは 英語 (en) を使用します。

ドック マネージャーは、個々の文字列を直接変更するために使用できる ResourceStrings プロパティも公開します。ResourceStrings プロパティを設定すると、ドック マネージャーはページの lang 属性に関係なく、指定された文字列を使用します。

API リファレンス