customize-uploader

目次

customize-uploader とは

customize-uploader は、kintone カスタマイズの CSS や JavaScript ファイルを kintone へ適用できる CLI ツールです。
このツールを利用すると、画面上からファイルをアップロードする必要がなくなり、kintone カスタマイズの開発効率が上がります。

npm パッケージとして提供されているため、Windows/macOS/Linux 環境で利用できます。

GitHub

https://github.com/kintone/js-sdk/tree/master/packages/customize-uploader/ (External link)

ライセンス

MIT ライセンス (External link)

ドキュメント

https://github.com/kintone/js-sdk/blob/master/packages/customize-uploader/README.md (External link)

下準備

customize-uploader を実行するには、Node.js とパッケージ管理ツールの npm が必要です。
Node.js をインストールすると、npm は自動でインストールされます。

  1. Node.js 公式サイト (External link) からインストーラーをダウンロードします。
    必要な Node.js のバージョンは、リポジトリの packages/customize-uploader/package.json (External link) にある engines プロパティを確認してください。
    たとえば次の記載の場合、Node.js のバージョン 14 以上が必要です。

    1
    2
    3
    
    "engines": {
      "node": ">=14"
    },
  2. ダウンロードしたインストーラーを実行し、画面にしたがってセットアップします。

Quickstart

レコード一覧のメニューの右側に赤文字で「Hello World」と表示するカスタマイズを、cutsomize-uploader を使って kintone に適用します。

Step1: kintone アプリの準備

  1. フィールドを設置せずに、kintone アプリを作成します。

  2. 作成したアプリの URL で、アプリ ID を確認します。
    URL の https://sample.cybozu.com/k/123 の末尾の数字部分が、アプリ ID です。
    上記の場合、アプリ ID は、「123」です。

Step2:必要なパッケージのインストール

customize-uploader をインストールします。
ここでは、例として customize-uploader をグローバルインストールする手順を説明します。

1
npm install -g @kintone/customize-uploader

Step3:マニフェストファイルの作成

  1. 作業用ディレクトリーを作成します。ここでは、例として「sample」というディレクトリー名にします。

    1
    
    mkdir sample
  2. 作成した作業用ディレクトリーに移動します。

    1
    
    cd sample
  3. 次のコマンドで、マニフェストファイルを作成します。

    1
    
    kintone-customize-uploader init
  4. 対話形式で、適用する kintone アプリのアプリ ID や適用範囲を入力します。
    今回は、次の値を指定します。

    • アプリ ID:Step1 で確認したアプリ ID
    • カスタマイズの適用範囲:今回は「ALL」(すべてのユーザーに適用)
    1
    2
    3
    4
    5
    
    kintone-customize-uploader init
    
    ? アプリIDを入力してください: 123
    ? カスタマイズの適用範囲を選択してください: ALL
    dest/customize-manifest.json を生成しました

「dest」ディレクトリーの下に、「customize-manifest.json」が生成されます。

Step4:カスタマイズファイルの準備

  1. 次の内容で、「sample」ディレクトリーの下に、カスタマイズの JavaScript ファイルを作成します。
    文字コードを「UTF-8」、ファイルの拡張子を「.js」にしてファイルを保存します。
    この記事ではファイル名を「desktop.js」としています。

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    
    (() => {
      'use strict';
      kintone.events.on('app.record.index.show', (event) => {
        const divElement = document.createElement('div');
        divElement.className = 'kintone-customize';
        divElement.textContent = 'Hello World';
    
        const element = kintone.app.getHeaderMenuSpaceElement();
        element.appendChild(divElement);
        return event;
      })();
    })();
  2. 次の内容で、「sample」ディレクトリーの下に、カスタマイズの CSS ファイルを作成します。
    文字コードを「UTF-8」、ファイルの拡張子を「.css」にしてファイルを保存します。
    この記事ではファイル名を「desktop.css」としています。

    1
    2
    3
    
    .kintone-customize {
      color: #ff0000;
    }

カスタマイズファイルを作成した後のディレクトリー構成は、次のようになります。

1
2
3
4
5
sample
├── desktop.css
├── desktop.js
└── dest
    └── customize-manifest.json

Step5:カスタマイズファイルの編集

「dest」ディレクトリーの下の「customize-manifest.json」を、次のように編集します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "app": "123",
  "scope": "ALL",
  "desktop": {
    "js": ["desktop.js"],
    "css": ["desktop.css"]
  },
  "mobile": {
    "js": [],
    "css": []
  }
}

Step6:カスタマイズの適用

次のコマンドを実行して、カスタマイズを kintone に適用します。
環境に合わせて、次の値を変更してください。

  • sample.cybozu.com:適用する kintone のドメイン名
  • ログイン名:kintone のログイン名
  • パスワード:kintone のパスワード
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
kintone-customize-uploader \
  --base-url https://sample.cybozu.com --username ログイン名 --password パスワード dest/customize-manifest.json

カスタマイズのアップロードを開始します
desktop.js をアップロードしました!
desktop.css をアップロードしました!
JavaScript/CSS ファイルをアップロードしました!
JavaScript/CSS カスタマイズの設定を変更しました!
運用環境への反映の完了を待っています...
運用環境への反映の完了を待っています...
運用環境に反映しました!

Step7:動作確認

  1. カスタマイズを適用したアプリの一覧画面を開きます。
    メニューの右側に、赤い文字で「Hello World」と表示されていることを確認します。

  2. 「JavaScript / CSS でカスタマイズ」画面で、カスタマイズが適用されていることを確認します。

補足

適用済みのカスタマイズの情報をマニフェストファイルに反映させる

すでに適用したカスタマイズファイルをダウンロードし、マニフェストファイルに反映させることができます。

1
2
kintone-customize-uploader import dest/customize-manifest.json \
  --base-url https://sample.cybozu.com --username ログイン名 --password パスワード

更新履歴

customize-uploader の変更履歴は、 CHANGELOG (External link) を確認してください。

information

この記事で紹介しているサンプルコードは、2022 年 5 月版 kintone および @customize-uploader v6.0.0 で動作を確認しています。