グローバル変数

皆さんは kintone で JavaScript API を利用する際、js ファイルをどう分けているでしょうか。

1 アプリに適用する全ての機能を 1 つの js ファイルにまとめてしまう方もいれば、1 機能 1 ファイルで管理されている方もいるかと思います。

もし複数ファイルに分ける場合、ファイル間をまたいで利用できるグローバル定数や変数が欲しくなりますよね？

しかし kintone ではグローバル変数・定数は基本的に使用禁止です。

cybozu developer network に以下のように記載があります。

kintone が正常に動作しなくなる可能性があるため、既存のグローバルオブジェクトを書き換えないようにしてください。 グローバル変数を使わず、即時関数のスコープ内で変数を定義してください。やむを得ずスコープ間で共有する変数を使用する場合は、名前空間オブジェクトを使用してください。

ただどうしても使いたい！という方向けに、名前空間オブジェクトを使う方法はガイドラインで認められています。この記事ではその定義方法・パターンをいくつか紹介します。

なお、ファイル間で値を共有したいだけであれば、webpack や esbuild などのバンドラーで複数ファイルを 1 つの js にまとめ、import / export で受け渡す方法もあります。グローバル領域を一切使わずに済むため、規模が大きい場合はこちらも検討してください。

禁止されている定義方法の例

// 既存のグローバルオブジェクトの書き換え、プロパティの追加はNG
kintone.foo = 100;
// Windowオブジェクトであっても、直接プリミティブ型の定義は避ける
window.bar = 'test';

(() => {
  // 即時関数の中であってもNG
  cybozu.baz = { label: 'テスト' };
  kintone.app.qux = () => console.log('テスト');
})();

グローバル変数・定数をアプリ内で定義する

今回は例として、名前空間「RIBBIT」を定義します。

javascript 一覧の先頭に「global.js」のようなファイルを 1 つ用意し、以下のように記述します。

(() => {
  window.RIBBIT = window.RIBBIT || {};
  RIBBIT.foo = {
    bar: 'value',
    baz: () => {
      console.log('グローバルに定義された名前空間の関数です');
    },
  };

  // スプレッド構文を使って、このようにも書けます
  window.RIBBIT = {
    ...(window.RIBBIT || {}),
    foo: {
      bar: 'value',
      baz: () => {
        console.log('グローバルに定義された名前空間の関数です');
      },
    },
  };
})();

スクリプトを実行しているウィンドウを表すグローバル変数である window のパラメータとして、利用したい変数を登録することで利用できます。

NG 例で紹介した window.bar のように、window 直下へ直接プリミティブ値を定義する方法はガイドライン的に NG です。ただ、定義した変数名がユニークであれば動作はします。

一方、window.RIBBIT のように名前空間オブジェクトを 1 つだけ定義し、その中に値を持たせる方法は認められています。名前空間も、他の js や kintone 自体と衝突しないよう、できる限りユニークな名前にしてください。

また、global.js は他のファイルより先に読み込まれるよう、JavaScript ファイル一覧の先頭に配置する必要があります。順序を間違えると、他のファイルから参照した時点で undefined になります。

グローバル定数を kintone 全体に定義する

JavaScript API はアプリ単位だけでなく kintone 全体にも反映することができるため、上述したグローバル変数・定数の定義を、kintone 全体へ反映されるよう記述することも可能です。

こうすることでアプリ内の JavaScript ファイル間だけでなく、各アプリ間で共有できるグローバル変数・定数を定義することができます。

ただ、それだけ変数の競合が発生する可能性も高まるため、最低限の利用にとどめておくほうが良いと思います。

(() => {
  window.RIBBIT = window.RIBBIT || {};
  RIBBIT.apps = [
    { id: 111, name: 'アプリA' },
    { id: 222, name: 'アプリB' },
    { id: 333, name: 'アプリC' },
  ];
})();

今回定義した名前空間はすべて大文字のアルファベットを使いましたが、これはあくまで通例に沿ったものです。

それぞれの命名ルールに従った名前で問題ありません。