kintone コーディングガイドライン
概要
kintone の「JavaScript/CSS でカスタマイズ」機能を使用すると、kintone の各機能、アプリの動作や画面をカスタマイズできます。
また、kintone REST API を使用することで、外部システムとデータを連携できます。
このページでは、kintone の JavaScript カスタマイズや外部システムと連携する際に注意すべき点について説明します。
JavaScript で kintone やアプリをカスタマイズする方法は、kintone ユーザーヘルプを参照してください。
JavaScript コーディング上の注意点
文字コード
UTF-8(BOM なし)で保存してください。
変数・ネームスペース
kintone が正常に動作しなくなる可能性があるため、既存のグローバルオブジェクトを書き換えないでください。
また、グローバル変数を使わず、即時関数のスコープ内またはブロックスコープ内で変数を定義してください。
やむを得ずスコープ間で共有する変数を使用する場合は、次の方法でグローバル汚染を防いでください。
- webpack などの JavaScript バンドラーツールを使う。
kintone カスタマイズで webpack を使う方法は、 目指せ!JavaScriptカスタマイズ中級者(1) 〜webpack編〜 を参照してください。 - 名前空間オブジェクトを使用する。
グローバル変数を使わない
|
|
let
と const
を使う場合は、以下のようにブロックスコープを使って変数を定義してもよいです。
|
|
既存のグローバルオブジェクトの追加や書き換え、参照はしない
|
|
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 の仕様公開と仕様変更の方針
セキュリティ
カスタマイズによるセキュリティ上の問題の発生を防ぐため、 セキュアコーディングガイドライン にしたがってコーディングしてください。