JavaScriptでカンバン機能を実現できるライブラリ「jKanban」の使い方 〜 その(1)

2021/11/12 · · 投稿者 Takashi Okutsu

画像現在、弊社では TeamPage のカンバン機能の開発を進めています。この開発には jKanban という JavaScript のライブラリをカスタマイズして使いました。

このライブラリは、jQuery などの他のライブラリに依存しないピュアな「Vanilla Script」で書かれており、簡単なものを構築できる手軽さだけでなく、細かなカスタマイズを加えられる柔軟性も持ち合わせています。

今回は、この jKanban の使い方の基本をご紹介します。

カンバンとは?

カンバンは、ホワイトボードに付箋を貼ってタスクを管理するようなイメージで、タスクの進捗を視覚的に確認・管理するための機能です。日本語の「看板」が語源となっています。

一枚のカンバンは、複数のカラムで構成されており、カラムにはタスクを表すカードが貼られています。タスクが進行してフェーズが変わると、カードをカラムから剥がして次のカラムに移動させます。

例えば、「商品を発送する」というタスク(カード)が「準備中」というカラム(フェーズ)に貼られているのを見れば、誰もが「あ、今、商品の発送を準備しているところなんだな」「まだ発送されていないんだな」ということがわかります。そのカードが「完了」というカラム(フェーズ)に移動したのを見れば、「あ、もう商品は発送されたのだな」ということがわかります。

デモンストレーション

本家のデモ

jKanban の作者が公開しているデモです。

http://www.riccardotartaglia.it/jkanban/

私が作成したデモ

このブログ記事を書くに当たって、私が作成したデモです。GitHub からダウンロードできます。

https://github.com/bunatree/jkanban-examples/blob/main/example1.html

動くデモは CodePen に作成してあります。 https://codepen.io/bunatree/pen/XWaYPwb

See the Pen jKanban Example 1 by bunatree (@bunatree) on CodePen.

以下、このデモを見本として説明します。

使い方

それでは、jKanban によるカンバンを構築してみましょう。

jKanban を入手する

GitHub の jKanban ページに行き、jKanban のファイルをダウンロードします。

ダウンロードした zip ファイルを展開し、「dist」フォルダに入っている jkanban.min.css と jkanban.min.js ファイルを適当な場所に保存し、HTML ファイルの <head>...</head> で指定します。下記の「path/to」の部分は例ですので、実際のパスに置き換える必要があります。

<link rel="stylesheet" href="path/to/jkanban.min.css">
<script src="path/to/jkanban.min.js"></script>

ファイルをダウンロードする代わりに、こちらの CDN を利用する方法もあります。今回のデモでは、この CDN を使用します。

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/jkanban@1.3.1/dist/jkanban.min.css">
<script src="https://cdn.jsdelivr.net/npm/jkanban@1.3.1/dist/jkanban.min.js"></script>

HTML を書く

次の HTML ファイルを作成します。

<body>...</body> 内に <div id="kanban-canvas">...</div> を配置しています。これがカンバンが表示される場所になります。

<!DOCTYPE html>
<html lang="ja">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>jKanban サンプル (1)</title>
  <!-- jKanban の .css ファイルを読み込む -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/jkanban@1.3.1/dist/jkanban.min.css">
  <!-- jKanban の .js ファイルを読み込む -->
  <script src="https://cdn.jsdelivr.net/npm/jkanban@1.3.1/dist/jkanban.min.js"></script>
</head>
<body>
  <div id="kanban-canvas">
    <!-- ここにカンバンが表示される -->
  </div>  
  <script>

    // カンバンに表示されるカラムやカードを定義
    var dataContent = [
      {
        "id"    : "column-id-1",
        "title" : "カラム (1)",
        "item"  : [
          {
            "id"      : "item-id-1",
            "title"   : "カード 1"
          },
          {
            "id"      : "item-id-2",
            "title"   : "カード 2"
          }
        ]
      },
      {
        "id": "column-id-2",
        "title": "カラム (2)",
        "item": [
          {
            "id": "item-id-3",
            "title": "カード 3"
          }
        ]
      },
      {
        "id": "column-id-3",
        "title": "カラム (3)",
        "item": [
          {
            "id": "item-id-4",
            "title": "カード 4"
          },
          {
            "id": "item-id-5",
            "title": "カード 5"
          }
        ]
      }
    ];

    // ここで jKanban を実行する
    var kanban = new jKanban({
      element: '#kanban-canvas',  // カンバンを表示する場所のID
      boards: dataContent,        // カンバンに表示されるカラムやカードのデータ
      gutter: '16px',             // カンバンの余白
      widthBoard: '250px',        // カラムの幅 (responsivePercentageの「true」設定により無視される)
      responsivePercentage: true, // trueを選択時はカラム幅は%で指定され、gutterとwidthBoardの設定は不要
      dragItems: true,            // trueを選択時はカードをドラッグ可能
      dragBoards: true            // カラムをドラッグ可能にするかどうか
    });

  </script>
</body>
</html>

JavaScript の実行

jKanban の実行は簡単で、「jKanban」というインスタンスを作るだけです。

var kanban = new jKanban({
  // ここにオプションや表示データを書く
});

しかし、これだけでは「どこに表示するのか」と「どんなデータをカンバンとして表示するのか」が指定されていないので、何も表示されません。

カンバンを表示する場所の指定

「どこに表示するか」は、jKanban インスタンス内の element: オプションで指定します。この値に、上記の <div id="kanban-canvas">...</div> で指定された id の「kanban-canvas」を半角シャープ記号を添えて記述します。

element: '#kanban-canvas'

カンバンに表示する内容の指定

「どんな内容を表示するか」は、jKanban インスタンス内の boards: オプションで、JSON 形式のデータとして定義します。

id: でカラムの ID を指定、title: でカラムのタイトル(カラム上部に表示される見出し)を指定します。item: には、カラムに表示したいカードを入れ子にして定義します。

[
  {
    "id"    : "column-id-1",
    "title" : "カラム1のタイトル",
    "item"  : [
      { "title": "カード 1" },
      { "title": "カード 2" },
      { "title": "カード 3" }
    ]
  }
]

実際のデータは長くなるので、ここでは「dataContent」という変数に格納することにします。

var dataContent = [
  {
    "id"    : "column-id-1",
    "title" : "カラム (1)",
    "item"  : [
      {
        "id"      : "item-id-1",
        "title"   : "カード 1"
      },
      {
        "id"      : "item-id-2",
        "title"   : "カード 2"
      }
    ]
  },
  {
    "id": "column-id-2",
    "title": "カラム (2)",
    "item": [
      {
        "id": "item-id-3",
        "title": "カード 3"
      }
    ]
  },
  {
    "id": "column-id-3",
    "title": "カラム (3)",
    "item": [
      {
        "id": "item-id-4",
        "title": "カード 4"
      },
      {
        "id": "item-id-5",
        "title": "カード 5"
      }
    ]
  }
];

そして、この変数 dataContentboards: オプションの値として指定します。

var kanban = new jKanban({
  element: '#kanban-canvas',
  boards: dataContent
});

記入が終わったら、HTML ファイルをブラウザーで開いて動作確認してみましょう。次のように、3 つのカラムとカード 1〜5 が表示されれば成功です。

オプションの設定

jKanban には細かなオプションが用意されており、「jKanban」インスタンスを作るときに次のようにして設定します。

var kanban = new jKanban({
  element: '#kanban-canvas',  // カンバンを表示する場所のID
  boards: dataContent,        // カンバンに表示されるカラムやカードのデータ
  gutter: '16px',             // カンバンの余白
  widthBoard: '250px',        // カラムの幅 (responsivePercentageの「true」設定により無視される)
  responsivePercentage: true, // trueを選択時はカラム幅は%で指定され、gutterとwidthBoardの設定は不要
  dragItems: true,            // trueを選択時はカードをドラッグ可能
  dragBoards: true            // カラムをドラッグ可能にするかどうか
});

本家 GitHub の README.md に細かな使い方が書かれていますので、参照してください。

jKanban の用語と構造

jKanban では、カンバンの中に表示される「カラム」のことを「board」と呼んでいます。

日本語の「看板」の「板」は、英語にすると「board」なので、私はカンバンが表示される領域全体(HTML の「kanban-canvas」の部分)のことを「board」と呼びたくなるのですが、カラムであることに注意が必要です。

例えば、「widthBoard」というオプションがありますが、これは「board の幅」つまり「カラムの幅」を指定するためのオプションです。カンバン全体の幅ではありません。

また、カラムの中に表示される「カード」のことを「item」と呼んでおり、「el」(「element」の略)という変数が使われています。

例えば、「dragItems」というオプションは、「item をドラッグできるようにするか」つまり「カードのドラッグを許可するか」のオプションです。

また、jKanban には dragEldropEl などのコールバックが用意されていますが、この「El」はカードのことを表しています。コールバックの使い方については第3回のブログ記事で紹介します。

カラムは、「kanban-board」というクラス名が付けられた <div> で、子要素として <header><main> があります。前者にはカラムのタイトルが、後者にはカードが表示されます。

図にまとめると次のようになります。

画像

以上で、jKanban の簡単な使い方その 1 を終わります。

次回のブログ記事では、カラムに色を付けたり、カードの中にコンテンツを表示したりする例を紹介します。

Page Top