【Angular】angular-gridster2 の使い方をまとめてみた (日本初かもしれない)

はじめに

Angular で Windows 10 のスタートメニューにあるような Drag and Drop ができるタイルを実装するにあたり、何か良さげなパッケージが無いか探していたところ、 angular-gridster2 というパッケージを教えてもらったので、その使い方を調べてみました。

github.com

angular-gridster2 は Drag and Drop で移動可能なタイル群を Grid Layout で配置でき、タイルの追加・削除・リサイズも簡単に実装することができる素敵パッケージです。

また、オプションやイベントが複数用意されているため、行数・列数の上限やタイル周囲の margin などの細かい指定のほか、ユーザの操作に応じたコールバック関数の実行も可能です。

ライセンスは MIT License なので、著作権表示および本許諾表示といったルールさえ順守すれば商用利用も問題ありません。

そんな魅力あふれるパッケージではありますが、色々調べる中で直面した大きな問題が…

それは、日本語で書かれたドキュメントが皆無だということ！！

使い方は難しくないですが、 GitHub の公式リポジトリ と 公式 Demo サイト を参考にしつつ、実際にコードを書いて動かしながら記事にまとめるのはなかなか大変でした。。

tiberiuzuld.github.io

もしかしたら、この記事が angular-gridster2 を日本語で取り上げた最初のエントリーかもしれません！？

動作環境

OS	Version
Ubuntu	20.04 LTS

※ Windows 10 Pro の Windows Subsystem for Linux (WSL 2) を使用

Environment	Version
Node.js	14.17.0
npm	6.14.13

Package	Version
@angular/cli	12.1.2
angular-gridster2	12.1.0

前提条件

• Angular CLI がインストールされている
• Angular CLI を使用した Angular アプリケーションが作成されている

angular-gridster2 概論

導入

インストール

npm install angular-gridster2 --save

インストールは npm でサクッと行います。

--save オプションって、いつの間にか指定しなくてもデフォルトで ON になっていたらしい…

知らなかった… (npm 5.0.0 以降だそうです)

使い方

NgModule (app.module.ts)

...
import { GridsterModule } from 'angular-gridster2';

@NgModule({
  ...
  imports: [
    ...
    GridsterModule,
  ],
})
export class AppModule {}

Angular のコンポーネントで使用するために、まずは NgModule で GridsterModule クラスをインポートします。

HTML (app.component.html)

<button type="button" (click)="addItem()">タイル追加</button>

<gridster [options]="options">
  <gridster-item [item]="item" *ngFor="let item of items; let index = index">
    <div class="draggable-handler">
      Header
    </div>
    <div>
      Content
    </div>
    <div>
      <button type="button" (click)="removeItem(index)">削除</button>
    <div>
  </gridster-item>
</gridster>

Element	Property: Type	Description
gridster	option: GridsterConfig	各種設定やコールバック関数を指定
gridster-item	item: GridsterItem	タイルの位置やサイズを指定

gridster タグを配置し、 option プロパティへ GridsterConfig 型のデータをバインドします。

gridster の Style には width: 100%; と height: 100%; が指定されているので、配置先の親要素と同サイズまで広がります。

gridster タグ内部の gridster-item タグが一つのタイルに相当し、 item プロパティへ GridsterItem 型のデータをバインドすることでタイルの位置やサイズを設定します。

Component (app.component.ts)

...
import { GridsterConfig, GridsterItem } from 'angular-gridster2';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  options: GridsterConfig = {};
  items: Array<GridsterItem> = [];

  ngOnInit(): void {
    this.options = {
      draggable: {
        enabled: true,
        ignoreContent: true,
        dragHandleClass: 'draggable-handler',
      },
      resizable: {
        enabled: true,
      },
      swap: true,
    };

    this.items = [
      { x: 0, y: 0, rows: 1, cols: 1 },
      { x: 0, y: 1, rows: 1, cols: 1 },
    ];
  }

  /** タイル追加 */
  addItem(): void {
    this.items.push({ x: 1, y: 0, rows: 1, cols: 1 });
  }

  /** タイル削除 */
  removeItem(index: number): void {
    this.items.splice(index, 1);
  }
}

gridster コンポーネントの option プロパティにバインドする GridsterConfig データと、 gridster-item コンポーネントの item プロパティにバインドする GridsterItem データを定義します。

また、タイル (gridster-item コンポーネント) の追加や削除も、このサンプルコードのように動的に行うことができます。

今回はサンプルのため固定位置にタイルを追加していますが、追加するタイルの位置とサイズには、本来配置したい任意の位置とサイズを指定してください。

リファレンス

主要そうなプロパティをリファレンスとしてまとめました。

各項目の説明は僕の独断と偏見に満ちた超訳になりますので、正確な内容は GitHub の公式リポジトリ か 公式 Demo サイト などの一次ソースをご確認ください。

また、こちらで紹介するプロパティは一部だけなので、さらに多くのプロパティを知りたい場合は、同じく公式 (ry

そして、今回は時間の都合上、イベントとコールバック関数については取り上げていないので、こちらについても (ry

GridsterConfig

Property	Description	Type	Default
gridType	Grid 内部の幅と高さの設定方法。 'fit' はスクロールバーが表示されないように Grid 内部の幅と高さの中で調整される。	String	'fit'
compactType	Grid 内の Item の自動整列方法 (上寄せや左寄せなど) 。 'none' は自動整列無し。	String	'none'
displayGrid	Grid 内の境界線の表示方法。 'onDrag&Resize' はドラッグ中やリサイズ中のみ、境界線を表示する。	String	'onDrag&Resize'
margin	Grid 外枠と内部の Item の余白。 Grid の padding と同義。	Number	10
outerMargin	Grid 外枠の内部の Item の余白有無。	Boolean	true
outerMarginTop	Grid 外枠と内部の Item の上部余白。 margin の値より優先される。 Grid の padding-top と同義。	Number	null
outerMarginRight	Grid 外枠と内部の Item の右部余白。 margin の値より優先される。 Grid の padding-right と同義。	Number	null
outerMarginBottom	Grid 外枠と内部の Item の下部余白。 margin の値より優先される。 Grid の padding-bottom と同義。	Number	null
outerMarginLeft	Grid 外枠と内部の Item の左部余白。 margin の値より優先される。 Grid の padding-left と同義。	Number	null
fixedColWidth	gridType に fixed を指定した場合に適用される、一列あたりの固定幅。	Number	250
fixedRowHeight	gridType に fixed を指定した場合に適用される、一行あたりの固定高さ。	Number	250
minCols	Grid の最小列数。	Number	1
maxCols	Grid の最大列数。	Number	100
minRows	Grid の最小行数。	Number	1
maxRows	Grid の最大行数。	Number	100
defaultItemCols	Grid 内の Item の横方向の規定サイズ。最小値は 1 。 Item の cols が省略された場合に使用される。	Number	1
defaultItemRows	Grid 内の Item の縦方向の規定サイズ。最小値は 1 。 Item の rows が省略された場合に使用される。	Number	1
swap	Grid 内の Item を移動する際、移動先に別の Item が存在した場合の制御。 true を指定すると、移動先の Item と位置の入れ替えを行う。	Boolean	true
pushItems	Grid 内の Item を移動・リサイズする際、移動・リサイズ先に別の Item が存在した場合の制御。 true を指定すると、移動先の Item を移動させる。	Boolean	false
disablePushOnDrag	Grid 内の Item を移動する際、移動先に別の Item が存在した場合の制御。 true を指定すると、移動先の Item を移動しない。 pushItems より優先される。	Boolean	false
disablePushOnResize	Grid 内の Item をリサイズする際、リサイズ先に別の Item が存在した場合の制御。 true を指定すると、リサイズ先の Item を移動しない。 pushItems より優先される。	Boolean	false
pushResizeItems	Grid 内の Item をリサイズする際、リサイズ先に別の Item が存在した場合の制御。 true を指定すると、リサイズ先の Item のサイズを縮小する。 pushItems と併用した場合、先に移動先の Item が可能な限り縮小された後に移動させる。	Boolean	false
draggable	Grid 内の Item のドラッグ制御方法。	Draggable	-
resizable	Grid 内の Item のリサイズ制御方法。	Resizable	-

GridsterConfig.Draggable

Property	Description	Type	Default
enabled	Grid 内の Item のドラッグ可否。 true を指定すると Item がドラッグ可能になる。	Boolean	false
ignoreContent	Grid 内の Item 全域のドラッグ可否。 true を指定すると、 dragHandleClass で指定したクラスを持つ要素以外のドラッグが不可になる。	Boolean	false
dragHandleClass	ignoreContent を true にした場合、ここで指定したクラスを持つ要素のみがドラッグ可能要素となる。ドラッグの可否は enabled の値に準ずる。	String	‘drag-handler’

GridsterConfig.Resizable

Property	Description	Type	Default
enabled	Grid 内の Item のリサイズ可否。 true を指定すると Item がリサイズ可能になる。	Boolean	false

GridsterItem

Property	Description	Type	Default
x	Item の横方向の表示開始位置。 0 始まり。省略時、または既に Item が存在する場合は、自動的に空き位置に配置される。	Number	undefined
y	Item の縦方向の表示開始位置。 0 始まり。省略時、または既に Item が存在する場合は、自動的に空き位置に配置される。	Number	undefined
cols	Item の横方向のサイズ。最小値は 1 。省略時は GridsterConfig.defaultItemCols の値が使用される。	Number	undefined
rows	Item の縦方向のサイズ。最小値は 1 。省略時は GridsterConfig.defaultItemRows の値が使用される。	Number	undefined
dragEnabled	Item のドラッグ可否。 GridsterConfig.Draggable.enabled を Item 毎に上書きしたい場合に使用する。	Boolean	undefined
resizeEnabled	Item のリサイズ可否。 GridsterConfig.Resizable.enabled を Item 毎に上書きしたい場合に使用する。	Boolean	undefined

おわりに

今まで OSS や商用ソフトウェアを含む様々なパッケージやライブラリを使用してきましたが、日本語の公式ドキュメントや多くの日本語ブログなどに、知らず知らずのうちに助けられてきたのだなと改めて痛感させられました。

自分の力だけでやってきたと思い込んできたものも、先人たちの偉大な教えや知恵の上で回っていたに過ぎなかったのです…

そして、これもまた過去何度も思ったことではありますが、やっぱり英語ができるエンジニアは有利だなと思いました。

日本語のドキュメントが無いだけで一気に作業効率がガタ落ちしますし、大体どこの (公式を含む) ドキュメントを見ても一次ソースは英語であることがほとんどです。

やっぱり、少しずつ英語の勉強もしないといかんな… _(-ω-`_)⌒)_