Tips

「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行目のvalueにitemsの要素を追加することでチェックの初期状態を変更できます。
作成した要素はコンポーネントの関数の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で動作を確認しています。