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

kintone API ドキュメント

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

概要

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

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

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

文字コード

UTF-8（BOM なし）で保存してください。

変数・ネームスペース

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

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

webpack などの JavaScript バンドラーツールを使う。
kintone カスタマイズで webpack を使う方法は、目指せ！JavaScriptカスタマイズ中級者（１）〜webpack編〜を参照してください。
名前空間オブジェクトを使用する。

グローバル変数を使わない

1
2
3
4
5
6
7


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

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

 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 属性の値、および DOM 構造を変更するカスタマイズを加えないでください。

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

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

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

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

セキュリティ

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

kintone API ドキュメント