「kintone UI Component v0」を使って簡単に kintone ライクな UI を設置する

目次

caution
警告

kintone UI Component v0 は、セキュリティアップデートを含めたすべての開発を終了しました。
今後は、安定的に利用できる kintone UI Component v1 への移行を推奨しています。
kintone UI Component v0 メンテナンス終了のお知らせ

はじめに

2018 年 5 月に、次の GitHub 上に、「kintone UI Component」が公開されました。
「kintone UI Component」は、kintone 技術者のために開発された、kintone ライクな UI を簡単に作成できるライブラリです。

GitHub

kintone-labs/kintone-ui-component (External link)

ドキュメント

kintone UI Component (External link)

「kintone UI Component」を使用することで、JavaScript 内で HTML の要素や属性を書いたり、CSS で色や大きさなどを変更する必要なく、簡単に kintone ライクな UI を作成できます。
当記事では、今まで kintone ライクな UI を作成するために書いていたコードと、「kintone UI Component」を使用したコードを比較しながら、使い方を紹介していきたいと思います。

比較を飛ばして読みたい方は「 kintone UI Componentを利用してチェックボックスを作成する」からお読みください。

注意事項

ソースコードの変更および再配布、商用利用等はライセンスにしたがってご利用可能です。

information

2021 年 3 月 5 日追記
kintone UI Component v1 をリリースしました。使い方などの詳細は、 kintone UI Component v1 を参照してください。
この記事で利用している v0 は、メンテナンスモードに移行しています。

kintone ライクなチェックボックス設置までの流れ

STEP1:通常のチェックボックスを設置する

まずは、JavaScript でチェックボックスを作成します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
(function() {
  'use strict';

  function createCheckElemet(value, checkedflg, disabledflg) {

    const checkElm = document.createElement('div');
    const checkSpan = document.createElement('span');
    const checkInput = document.createElement('input');
    const checkLabel = document.createElement('label');
    checkInput.type = 'checkbox';
    checkInput.checked = checkedflg;
    checkInput.disabled = disabledflg;
    checkLabel.innerText = value;
    checkElm.appendChild(checkSpan);
    checkSpan.appendChild(checkInput);
    checkSpan.appendChild(checkLabel);

    return checkElm;
  }

  kintone.events.on('app.record.detail.show', (event) => {

    const orangediv = createCheckElemet('Orange', true, false);
    const bananadiv = createCheckElemet('Banana', false, false);
    const lemondiv = createCheckElemet('Lemon', false, true);

    kintone.app.record.getSpaceElement('nativeUI').appendChild(orangediv);
    kintone.app.record.getSpaceElement('nativeUI').appendChild(bananadiv);
    kintone.app.record.getSpaceElement('nativeUI').appendChild(lemondiv);

    return event;

  });

})();

この段階では、そこまでコードが読みづらくないですが、デザインが kintone に合っていません。
次のステップでは、CSS を用いてデザインを変更します。

STEP2:modern-default css を使用する

先ほど作成したチェックボックスのデザインを kintone ライクな UI にするためには CSS を適用させ、デザインを変更する必要があります。
kintone ライクな UI をデザインする CSS は、 GitHub (External link) の「51-modern-default.css」に公開しています。
対象のファイルをダウンロードしてアプリに適用し、 51-modern-default の記事を参考に、チェックボックスの DOM 構造を JavaScript のコード内で再現する必要があります。

kintone ライクな UI を作成できましたが、JavaScript のコードは、コード内で HTML 要素の各属性を宣言しており、読みづらいコードとなっています。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
/*
 * 51-modern-default を使ってチェックボックスを作成する
 * Copyright (c) 2018 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/license/mit/
 */

(function() {
  'use strict';
  function createCheckElemet(value, checkedflg, disabledflg, id) {

    const checkElm = document.createElement('div');
    const checkSpan = document.createElement('span');
    const checkInput = document.createElement('input');
    const checkLabel = document.createElement('label');
    checkElm.className = 'kintoneplugin-input-checkbox';
    checkSpan.className = 'kintoneplugin-input-checkbox-item';
    checkInput.type = 'checkbox';
    checkInput.checked = checkedflg;
    checkInput.disabled = disabledflg;
    checkInput.id = id;
    checkLabel.innerText = value;
    checkLabel.htmlFor = id;
    checkElm.appendChild(checkSpan);
    checkSpan.appendChild(checkInput);
    checkSpan.appendChild(checkLabel);

    return checkElm;
  }

  kintone.events.on('app.record.detail.show', (event) => {

    const orangediv = createCheckElemet('Orange', true, false, 'checkbox-0');
    const bananadiv = createCheckElemet('Banana', false, false, 'checkbox-1');
    const lemondiv = createCheckElemet('Lemon', false, true, 'checkbox-2');

    kintone.app.record.getSpaceElement('modern-default-UI').appendChild(orangediv);
    kintone.app.record.getSpaceElement('modern-default-UI').appendChild(bananadiv);
    kintone.app.record.getSpaceElement('modern-default-UI').appendChild(lemondiv);

    return event;

  });
})();

STEP3:jQuery を利用する

次に、読みやすいコードにするため、 Cybozu CDN でも公開されている jQuery を利用してみます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
/*
 * jQuery を使ってチェックボックスを作成する
 * Copyright (c) 2018 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/license/mit/
 */

jQuery.noConflict();
(function($) {
  'use strict';

  function createCheckElemet(value, checkedflg, disabledflg, id) {

    const $checkElm = $('<div>', {
      class: 'kintoneplugin-input-checkbox'
    });
    const $checkSpan = $('<span>', {
      class: 'kintoneplugin-input-checkbox-item'
    });
    const $checkInput = $('<input>', {
      type: 'checkbox',
      checked: checkedflg,
      disabled: disabledflg,
      id: id
    });
    const $checkLabel = $('<label>', {
      For: id,
      text: value
    });
    $checkElm.append($checkSpan);
    $checkSpan.append($checkInput);
    $checkSpan.append($checkLabel);

    return $checkElm;
  }

  kintone.events.on('app.record.detail.show', (event) => {

    const $orangediv = createCheckElemet('Orange', true, false, 'checkbox-0');
    const $bananadiv = createCheckElemet('Banana', false, false, 'checkbox-1');
    const $lemondiv = createCheckElemet('Lemon', false, true, 'checkbox-2');

    $(kintone.app.record.getSpaceElement('jQuery-UI')).append($orangediv);
    $(kintone.app.record.getSpaceElement('jQuery-UI')).append($bananadiv);
    $(kintone.app.record.getSpaceElement('jQuery-UI')).append($lemondiv);

    return event;

  });

})(jQuery);

先ほどより読みやすくなりましたが、まだ class や細かい HTML の要素を指定する必要があり、楽にコーディングできるようになったとはいえません。

kintone UI Component を利用してチェックボックスを作成する

kintone UI Component のダウンロード

kintone UI Component を使用すれば今までより簡単に kintone ライクな UI を設置できます。

以下の手順でダウンロードおよび kintone アプリに適用します。

  1. kintone-labs/kintone-ui-component (External link) を開きます。
  2. v0.〜 で始まる最新バージョン(2021 年 03 月 05 日時点の最新は v0.7.7)の「Assets」から「kintone-kintone-ui-component-0.x.tgz」をダウンロードします。
    0.x はバージョン番号です。
  3. ダウンロードした tgz ファイルを解凍します。
  4. 解凍後のフォルダー package > dist 以下の「kintone-ui-component.min.js」と「kintone-ui-component.min.css」を kintone アプリに適用します。
    参考: JavaScript や CSS でアプリをカスタマイズする (External link)

サンプルコード

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
/*
 * kintone UI Component を利用してチェックボックスを作成する
 * Copyright (c) 2018 Cybozu
 *
 * Licensed under the MIT License
 * https://opensource.org/license/mit/
 */

(function() {
  'use strict';

  kintone.events.on('app.record.detail.show', (event) => {
    const checkbox = new kintoneUIComponent.CheckBox({
      items: [
        {
          label: 'Orange',
          value: 'Orange',
          isDisabled: false
        },
        {
          label: 'Banana',
          value: 'Banana',
          isDisabled: false
        },
        {
          label: 'Lemon',
          value: 'Lemon',
          isDisabled: true
        },
      ],
      value: ['Orange']
    });
    kintone.app.record.getSpaceElement('component-UI').appendChild(checkbox.render());

    return event;
  });
})();

いかがでしょうか。今までとは違い、特に HTML 要素や属性を指定することなく、簡単に kintone ライクな UI が作成できます。
簡単にコードを解説します。

12 行目の items に要素を追加することで簡単にチェックボックスの要素を増やすことが可能です。
また、31 行目の valueitems の要素を追加することでチェックの初期状態を変更できます。
作成した要素はコンポーネントの関数の render() で DOM 要素として扱うことが可能です。

kintone UI Component 独自の関数

kintone UI Component には、先ほどチェックボックスで紹介した、render() 以外にも、コンポーネントを扱うための独自の関数が用意されています。
先ほど作成したチェックボックスを例に、コンポーネントの独自関数を紹介していきます。
他の UI についてはドキュメントを確認してください。

render()

作成したコンポーネントを DOM 要素として扱うための関数です。

1
console.log(checkbox.render());

addItem(item)

チェックボックスに選択肢をふやします。

1
2
3
4
5
6
const item = {
  label: 'Grape',
  value: 'Grape',
  isDisabled: false
};
checkbox.addItem(item);

getItem(index)getItems()

チェックボックスの選択肢を取得します。

1
2
console.log(checkbox.getItem(0));
console.log(checkbox.getItems());

removeItem(index)

チェックボックスの選択肢を削除します。

1
checkbox.removeItem(0);

getValue()setValue(value)

チェックが入っている選択肢の値を取得、または設定します。

1
2
console.log(checkbox.getValue());
checkbox.setValue(['Banana']);

disableItem(value)enableItem(value)

選択肢の無効、有効を設定します。

1
2
checkbox.disableItem('Orange');
checkbox.enableItem('Lemon');

on(eventName, callBack)

コンポーネントに対して、特定のイベントが発生した際に実行される callBack 関数です。
チェックボックスの eventName は「change」で、チェックボックスを選択したり解除したりしたときに実行されます。
その他のコンポーネントでも同様の on(eventName, callBack) が用意されています。
たとえば、ボタンでは eventName は「click」で、ボタンをクリックしたときに実行されます。
他にもコンポーネント毎にイベントが用意されているので、詳細はドキュメントを確認してください。

1
2
3
checkbox.on('change', (value) => {
  console.log(value);
});

show()hide()

コンポーネントを表示、非表示に設定します。

1
checkbox.hide();

disable()enable()

チェックボックス全体の無効、有効を設定します。

1
checkbox.disable();

チェックボックス以外のUIについて(一部)

この記事ではチェックボックスについて紹介しましたが、他にも実装のたいへんな Table や、
「51-modern-default.css」では実装できなかった UI を簡単に実装できます。
一部について紹介していきます。詳しい実装方法はドキュメントの方を確認してください。

Table

1
2
3
4
5
const table = new kintoneUIComponent.Table({
  rowTemplate: [radioBtn, dropdown],
  header: ['Fruit', 'Color']
});
kintone.app.record.getSpaceElement('component-UI').appendChild(table.render());

Table の callBack 関数の、on() には、さまざまなイベントが実装されています。

rowAdd
行が追加された際に発行します。
イベントオブジェクトには、Table の値や、追加ボタンを押した行番号が含まれます。
rowRemove
行が削除された際に発行します。
イベントオブジェクトには、Table の値が含まれます。
cellChange
セルの値が変更された際に発行します。
イベントオブジェクトには、Table の値やセルの値、変更されたセルの位置が含まれます。
cellClick
セルがクリックされた際に発行します。
イベントオブジェクトには、Table の値やセルの値、クリックされたセルの位置が含まれます。

コールバック関数で受け取るデータの詳細は ドキュメント (External link) を確認してください。
上記のイベントを使うことで、さまざまな動きを実装できます。

NotifyPopup

1
2
3
4
5
const notifyPopup = new kintoneUIComponent.NotifyPopup({
  text: 'Submitted successfully',
  type: 'success'
});
kintone.app.record.getSpaceElement('component-UI').appendChild(notifyPopup.render());

ポップアップも簡単に実装できます。

Spinner

1
2
3
const spinner = new kintoneUIComponent.Spinner();
kintone.app.record.getSpaceElement('component-UI').appendChild(spinner.render());
spinner.show();

ロード中の画面に使えるスピナーも kintone UI Component を使用することで、簡単に作成できます。

IconButton

1
2
3
4
5
6
const insertBtn = new kintoneUIComponent.IconButton({
  type: 'insert',
  color: 'blue',
  size: 'large'
});
kintone.app.record.getSpaceElement('component-UI').appendChild(insertBtn.render());

「+」「-」「×」ボタンを作成できます。
IconButton の on() 関数には、クリックイベントがあるので、ボタンを押下した際の処理も簡単に実装できます。

おわりに

kintone UI Componet は、簡単に kintone ライクな UI を作成するだけでなく、UI の動きに対応したイベントが用意されているため、さまざまな処理を実装できます。
ドキュメントを確認しながら、kintone ライクな UI を作成してみてください。

information

この Tips は、2018 年 4 月版 kintone で動作を確認しています。