見出し画像

kintone UI Componentの実装(本番環境への導入方法と注意点)

kintone UI Componentとは

kintone UI Component(以降「KUC」と略す場合もあります)は、kintone カスタマイズでの UI 開発などで「kintone のフォームのパーツを自作する」ためのライブラリです。
JavascriptコードでKintoneライクなフォームのパーツを自作できます。

kintone UI Componentを使用することで、JavaScript 内で HTML の要素や属性を書いたり、CSS で色や大きさなどを変更する必要なく、簡単に kintone ライクな UI (ユーザーインターフェイス)を作成できます。

kintone UI Component は、V0が2023年12月31日でセキュリティ対策を含むメンテナンス対応が終了したので、kintone UI Component v1の利用が推奨となっています。

https://cybozu.dev/ja/kintone/sdk/library/kintone-ui-component-v1/

通常、Kintoneのフィールドの設定値(例:ラジオボタンの選択肢等)は、Javascriptで変更することはできません。
しかし、kintone UI Componentで自作したフィールドパーツの設定値は、Javascriptで変更できます。例えば、条件によって値リストが動的に変化するラジオボタンやドロップダウンリストが作れます。

kintone UI Componentの利用方法

kintone UI Componentを利用するには、KUC専用のライブラリを予め実行環境(アプリの設定>JavaScript / CSSでカスタマイズ)に読み込む必要があります。
KUC の利用方法にはCDN と UMD と npm パッケージが用意されています。npmパッケージ版は、node.js実行環境が有るユーザー向けです。
通常は、CDN版かUMD版を選択することになりますが、CDNでの利用にはリスクがありますので、本番環境ではUMD版の利用が推奨されています。


CDN版のKUC利用方法(推奨:試験環境)

最新版の kintone UI Component (KUC)は、以下のCDNで利用できます。
しかし、後で述べる通り本番環境でCDNの利用は非推奨です。

https://unpkg.com/kintone-ui-component/umd/kuc.min.js

https://kintone-ui-component.netlify.app/ja/docs/getting-started/quick-start/

Kintoneのアプリの設定>JavaScript / CSSでカスタマイズの画面で、上記のKUCのCDNをURL指定で追加し、次に自作したJavascriptコードをアップロードして追加します。

下記注意事項の通り、本番環境でCDNの利用は推奨されていません。

【注意事項】
unpkg はサイボウズが提供している CDN サービスではありません。
検証用としてお使いいただくことをお勧めします。
本番環境では、unpkg の障害や不具合による影響を避けるため、UMD の kuc.min.js をご利用ください。

https://ui-component.kintone.dev/ja/docs/getting-started/quick-start/#npm-パッケージを利用する

CDNで利用する場合は、正常に動いてたJavascriptコードが、CDNを提供しているサーバーの障害で突然動かなくなるリスクがあります。

私も実際に、2024年4月12日の午後にunpkg .comのCDNに障害が発生してKUCオブジェクトが突然動作しなくなる(KUCオブジェクトの呼出で未定義エラー発生)という経験をしました。

unpkg .comの障害はサイボウズ社の責任外なので、本番環境で他社CDNを利用した場合の責任は取れません、ということの様です。


UMD版のKUC利用方法(推奨:本番環境)

UMD(Universal Module Definition)版のKUCライブラリファイルを入手します。(入手方法は、後で説明します☆★★)
次に、Kintoneのアプリの設定>JavaScript / CSSでカスタマイズの画面から、入手したKUCライブラリファイル(kuc.min.js)をアップロードして、その次に自作したJavascriptコードをアップロードして追加します。
これでKUCの各パーツが正常に動作します。

UMD版のKUCライブラリファイル入手方法 ☆★★

kintone UI Component リポジトリ内の各バージョン Release 欄に添付のアーカイブフォルダ(kintone-ui-component-{version}.tgz)を解凍して、./package/umd/kuc.min.jsをkintone アプリ設定の JavaScript / CSS でカスタマイズにて指定します。

言い換えると、githubで一般公開されているkintone UI Componentの専用倉庫(リポジトリ)から、最新バージョンの圧縮ファイルをダウンロードして、解凍したumdフォルダの中にある「kuc.min.js」を利用します。

(手順1)
kintone UI Component のgithubリポジトリ(倉庫)の各バージョン Release 欄のリンクページの▼Assetsセクションから、最新バージョンの.tgz圧縮ファイルをクリックでダウンロードして解凍します。

(手順2)
ファイルを解凍したら、./package/UMDフォルダの中にある「kuc.min.js」をkintoneアプリ設定の JavaScript / CSS でカスタマイズ画面でアップロードして追加します。


UMD版のバージョン指定について

v1.4.0 以降のバージョンを利用する場合は、KUCコンポーネントを呼び出す際に Kuc オブジェクトの代わりに Kucs["1.x.x"] を使ってバージョンを指定してください。(例) new Kucs["1.17.0"].Button()

システム上に kuc.min.js が 1つしかない、もしくは最後に読み込まれた kuc.min.js の利用で問題ない場合は、Kuc オブジェクトを利用して問題ありません。(例) new Kuc.Button()

Kintone 内に「KUCオブジェクト」を使用するアプリを複数作成する場合は、ライブラリのバージョン違いで競合エラー発生のリスクがありますので、 Kucs["1.x.x"] を使ってバージョンを指定する方が安全です。

詳細は、以下のページの「UMDを利用する」の章をご参照ください。


以上が、kintone UI Componentを利用する準備の説明と注意点です。
本番環境では、CDN版は利用しないでUMD版のライブラリ(kuc.min.js)をダウンロードして使う方が良いです。


よろしければサポートお願いします! いただいたサポートは、note記事制作の活動費に使わせていただきます!