kintoneコーディングガイドライン

目次

概要

kintoneの「JavaScript/CSSでカスタマイズ」機能を使用すると、kintoneの各機能、アプリの動作や画面をカスタマイズできます。
また、kintone REST APIを使用することで、外部システムとデータを連携できます。
このページでは、kintoneのJavaScriptカスタマイズや外部システムと連携する際に注意すべき点について説明します。

JavaScriptでkintoneやアプリをカスタマイズする方法は、kintoneユーザーヘルプを参照してください。

JavaScriptコーディング上の注意点

文字コード

UTF-8(BOMなし)で保存してください。

変数・ネームスペース

kintoneが正常に動作しなくなることを防ぐため、既存のグローバルオブジェクトを書き換えないでください。
また、グローバル変数を使わず、即時関数のスコープ内またはブロックスコープ内で変数を定義してください。

やむを得ずスコープ間で共有する変数を使用する場合は、次の方法でグローバル汚染を防いでください。

グローバル変数を使わない
1
2
3
4
5
6
7
// 即時関数内のローカル変数として変数を定義する
(() => {
  // 悪い例
  globalVariable = 1; // グローバル変数として変数を定義している
  // 良い例
  const localVariable = 1; // 即時関数内のローカル変数として変数を定義する
})();

letconstを使う場合は、以下のようにブロックスコープを使って変数を定義してもよいです。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// ブロックスコープ内のローカル変数として変数を定義する
{
  // 悪い例
  // どちらもグローバル変数として変数を定義している
  globalVariable1 = 1;
  var globalVariable2 = 1;
  // 良い例
  // どちらもブロックスコープ内のローカル変数として変数を定義している
  const localVariable1 = 1;
  let localVariable2 = 1;
}
既存のグローバルオブジェクトの追加や書き換え、参照はしない
1
2
3
4
5
6
7
8
(() => {
  // 悪い例
  cybozu.foo = 'bar'; // 既存のグローバルオブジェクトに、新しいプロパティを追加したり書き換えしたりしている
  const foo = cybozu.foo; // 既存のグローバルオブジェクトを参照している
  // 良い例
  myNameSpace = {}; // 空間オブジェクトを使用する
  myNameSpace.foo = 'bar';
})();

kintoneで使われているidやclass属性

各要素に付与されているidやclass属性の値は、予告なく変更されます。
DOM構造についても変更されることがあります。

カスタマイズするときは、次を参照または変更するようなカスタマイズを加えないでください。

  • 各要素のidやclass属性の値
  • kintone JavaScript API以外の方法で取得する製品のDOM構造

DOM要素を操作する場合、予告なく変更されることのないkintone JavaScript APIを使ってください。

JavaScript APIで取得した要素へのカスタマイズ

JavaScript APIで取得した要素内へ追加する要素は、kintoneのCSSに影響される場合があります。
そのためkintoneのアップデートによって、追加した要素の表示が変わる可能性があります。

要素を取得できるAPIの一覧は、次のページを確認してください。 kintone JavaScript API:要素の取得

URLの取得

kintone.api.url()またはkintone.api.urlForGet()を利用して、kintoneのURLを取得してください。
将来のバージョンでも動作できるようにするためです。

JavaScript APIによるカスタマイズができない箇所

スペースやスレッドの本文に貼り付けた以下のパーツは、JavaScript APIでカスタマイズできません。

  • アプリのレコード一覧
  • グラフ

複数のWebブラウザーで動作を確認する

動作確認の際には、複数のWebブラウザーを使用することを推奨します。
Webブラウザーの種類やバージョンの違いによって、期待した動作にならない場合があります。

読み込むJavaScriptプログラムに問題があると、kintoneが正常に動作しません。
カスタマイズしたkintoneの機能が意図とおりに動作していることを十分確認してください。

kintone REST APIの利用上の注意点

問題のあるプログラムによって、性能の低下やサービスを利用できなくなることがあります。

短時間で大量のリクエスト送信を避ける

自動的に大量のリクエストを送信するようなプログラムや、並列で多数のリクエストを同時実行するプログラムは、レスポンス悪化などのサービス低下を招く原因になります。
サーバーの高負荷や大量リソース消費を生じさせるリクエストについては、アクセス制限を実施する場合があります。

適切なユーザーエージェントを設定する

どのようなサービスやツールからリクエストを送信しているか判別可能にするため、適切なユーザーエージェント(「User-Agent」ヘッダー)を設定してください。

ユーザーエージェントのガイドラインは、RFC 9110の「User-Agent」の項を参照してください。
10.1.5. User-Agent | RFC 9110 (External link)

並列で実行するのをなるべく避ける

アプリやレコードに対する登録や更新、削除が同時に実行されると、デッドロックが発生しやすくなりエラーの原因になります。
kintone REST APIを並列で実行する場合は、注意してください。

kintoneのアップデートによる影響

作成したプログラムの実装によっては、kintoneがアップデートしたときにカスタマイズが動作しなくなる場合があります。
必要に応じてJavaScriptファイルやCSSファイルを編集し、再度アップロードしてください。

kintoneのアップデートによる影響を少なくするため、kintone JavaScript APIを利用してください。
APIの仕様公開と仕様変更の方針

セキュリティ

カスタマイズによるセキュリティ上の問題の発生を防ぐため、セキュアコーディングガイドラインにしたがってコーディングしてください。
セキュアコーディングガイドライン