AI can fly !!

AI がやりたい Web エンジニアのアウトプット (AI の知識は無い)

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

Angular

はじめに

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 gridTypefixed を指定した場合に適用される、一列あたりの固定幅。 Number 250
fixedRowHeight gridTypefixed を指定した場合に適用される、一行あたりの固定高さ。 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 ignoreContenttrue にした場合、ここで指定したクラスを持つ要素のみがドラッグ可能要素となる。ドラッグの可否は 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 や商用ソフトウェアを含む様々なパッケージやライブラリを使用してきましたが、日本語の公式ドキュメントや多くの日本語ブログなどに、知らず知らずのうちに助けられてきたのだなと改めて痛感させられました。

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

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

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

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