customize-uploader

目次

customize-uploaderとは

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

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

GitHub

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

ライセンス

MITライセンス (External link)

ドキュメント

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

下準備

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

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

information

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