はじめに
今回は@kintone/dts-genというkintoneでTypeScriptを使いやすくするツールとkintone JavaScript Client (@kintone/rest-api-client)を使って、実践的なTypeScriptコードを書きます。
TypeScriptを使ってJavaScriptカスタマイズをする基本的な方法にについては、当サイトの別記事TypeScriptでkintoneカスタマイズ開発をしてみようで紹介しています。
シリーズの記事一覧はこちら。
TypeScriptとは。TypeScriptを使うメリット
TypeScriptとは、Microsoftが開発したオープンソースのプログラミング言語で、JavaScriptに「型」情報を追加できるようになっています。
「型」というのは変数などに格納される値が、数値なのか文字列なのかなど判別するために宣言します。
数値型や文字列型など基本的なもの以外にも、ユーザーが独自に定義することもできます。
型情報のおかげで、扱おうとしているデータの中身が実行せずともコードを書くタイミングで明らかになるため、バグを起こしにくくなります。
例えば、APIから取得できるkintoneの数値・計算フィールドの値は数字ではなく文字列ですが、それに直接乗算を行おうとすると、数値ではないのでエラーと判断されます。
- 数値・計算フィールドにそのまま乗算を行おうとするとエラーになる例
計算フィールド「合計金額」に "record.合計金額.value * 0.1" で乗算を行おうとしてエラーが表示されています。
他にも、あるオブジェクトの中に該当のキーが無い場合など、アクセスしようとするとIDEがエラーと判断します。
- オブジェクトにアクセスしようとするとエラーになる例
オブジェクト "record.文字列.value" に値を代入しようとしたが、実際には「文字列」というフィールドコードが存在しないためエラーが表示されています。
TypeScriptで、kintoneのアプリの各フィールドの型情報を用意し、それを利用することで上記のようにkintoneのフィールドコードを間違えたりせずに書くことができるようになります。
特にテーブルの階層が深い複雑な構造や、REST API のリクエストパラメーターやレスポンスに対して大きな効果を発揮します。
実際にやるとどうなるのか、サンプルを試してみましょう。
準備
コード: https://github.com/cybozudevnet/sample-kintone-webpack-for-intermediate
git clone またはリンク先右上の緑色の Clone or download ボタンから Zip ファイルをダウンロードしてご利用ください。
以降の導入方法は上記ページの Readme を参照ください。
前回までの記事をお試しいただいた方も念の為再度ディレクトリ直下で npm install をやっておいてください。
細かい設定内容は後述しますが、これでTypeScriptを利用するための必要パッケージがインストールされます。
サンプル
第4回の記事、目指せ中級者!実践JavaScriptカスタマイズレベルアップ(4) 〜kintone REST API Client編〜と同様のサンプルでTypeScriptならどう書くかという感じでコードを書いてみたいと思います。
第4回の記事と同様のアプリを利用するので上記記事の「アプリの用意と設定」のようにアプリを用意してから以下お試しください。
型情報の取得
コードを実際に編集する前に、JavaScript APIにアクセスするための型定義を用意します。 @kintone/dts-gen というライブラリを使うことで、JavaScriptAPIで扱うための型定義をアプリから取得できます。
下記コマンドを実行し、見積アプリから型情報を取得しておきます。作成されたものを型定義ファイルといいます。
npx @kintone/dts-gen --base-url https://kintoneのドメイン.cybozu.com -u ユーザー名 -p パスワード --app-id アプリID --type-name Quote --namespace KintoneTypes -o src/types/Quote.d.ts
コマンドが成功すると、下記のような型定義ファイルが生成されます。
ファイル: src/types/Quote.d.ts
サンプルコード
ファイル: src/apps/quote_ts/index.ts
実際にコードを編集してみて、27行目あたりでrecordの中身をみようとするとどうなるか、Visual Studio Codeの挙動を試してみてください。
下記画像のように、「record.」と入力していくと見積アプリのフィールドに基づいたサジェストがされるはずです。
サンプルコードの説明
ここではTypeScriptのすべてを説明することはできませんが、サンプルコードの概要をかいつまんで紹介します。
実際には、第4回で紹介しているコードとはあまり差分はありません。下記に示す型情報の扱いのみ違いがあります。
- 26行目: event.recordの型情報を付与
const record = event.record as kintoneTypes.Quote;
とかかれた箇所ですが、これは先述の @kintone/dts-gen で作成した型定義を当てています。こうすることで、「event.record は 見積アプリのレコードですよ」ということを定義できます。
これを型アサーションといいます。 - 4行目〜18行目: 製品アプリの型定義(@kintone/rest-api-client用)
実は、@kintone/rest-api-clientはTypeScriptをサポートしています。
ただし、@kintone/rest-api-clientの型定義は、@kintone/dts-genのようにコマンドから作成することができません。
そのため、このように製品アプリの型を自身で用意する必要があります。
@kintone/rest-api-clientの型定義方法の詳細はこちらを御覧ください。 - 48行目: @kintone/rest-api-clientに型情報を渡す
products = await client.record.getRecords<SavedProduct>({
としている行ですが、4行目~18行目で定義した製品アプリの型情報(SavedProduct)を渡すことで、getRecords()で返ってくるレコードは、SavedProduct型ですよと教えています。
これにより、REST APIから返却されたレコードについてもサジェストされるようになります。
サンプルコードのビルド
ブラウザにTypeScriptを直接動作させることはできませんが、TypeScript→JavaScriptに変換できるようにWebpackの設定を追記しています。
ビルドコマンドを打つことで、JavaScriptに変換できるので、それをアップロードします。
npx webpack --mode production
詳細は、目指せ中級者!実践JavaScriptカスタマイズレベルアップ(3) 〜自動で一括ファイルアップロード編〜をご確認ください。自動ファイルアップロードもできます。
おわりに
TypeScript自体と、それに対応するkintoneのエコシステムが醸成されてきた結果、このようにかなりよい開発体験を得ることができるようになってきました。
kintoneを扱う上で完全には避けられない、フィールドコードの勘違いなど、大分減らせることでバグも未然に防ぐことができ、かなりTypeScriptでkintoneをカスタマイズするのは大分魅力的だと思っています。
今回の記事でTypeScriptに興味がでたら、ぜひ入門者用の書籍などを参考にして学んでみてください。TypeScriptは昨今ではかなり人気でもあり、今後の開発の役に立つと思います。
シリーズの記事一覧はこちら。
このTipsは、2021年2月版 kintone、@kintone/rest-api-client@1.10.0 で確認したものになります。
記事に関するフィードバック
記事のコメント欄は記事に対するフィードバックをする場となっております。
右の記事フィードバックのためのガイドを参照してコメントしてください。
記事のリンク切れなど、気になる点がある場合も、こちらのフォームからフィードバックいただけますと幸いです。