kintone-devCamp-Boost-2023

kintone devCamp Boost! (2023 年) のセッション用リポジトリです。

目次

• 構成
• セットアップ
• 開発方法
• ライセンス

構成

kintone カスタマイズを快適に開発できるように、以下のツール群を設定済みです。

セットアップ

手順 1. 必須ツールのインストール

以下のツールをインストールします。

※Git のインストールは任意です。

手順 2. リポジトリのクローン・セットアップ

開発用テンプレートリポジトリをダウンロードしてセットアップします。

Git のインストール状況と GitHub アカウントの有無で手順が異なります。
作業内容をセッション後も保存するために Git と GitHub アカウントを用意することを推奨しています。

• Git をインストールしている・GitHub アカウントがある
• Git をインストールしている・GitHub アカウントがない
• Git をインストールしていない

GitHub アカウントを持っている場合

以下のページの「Use this template」ボタンから自分のリポジトリを作成してください。

https://github.com/tasshi-me/kintone-devCamp-Boost-2023

作成したリポジトリをクローンしてください。

## HTTPSの場合
git clone https://github.com/作成したリポジトリのオーナー/リポジトリ名.git

## SSHの場合
git clone git@github.com:作成したリポジトリのオーナー/リポジトリ名.git

リポジトリのディレクトリに移動し、以下のコマンドを実行してください。

npm install
npm run setup

GitHub アカウントを持っていない場合

リポジトリをクローンしてください。

## HTTPSの場合
git clone https://github.com/tasshi-me/kintone-devCamp-Boost-2023.git

## SSHの場合
git clone git@github.com:tasshi-me/kintone-devCamp-Boost-2023.git

リポジトリのディレクトリに移動し、以下のコマンドを実行してください。

npm install
npm run setup

Git を使用しない場合

以下の手順でリポジトリをダウンロードしてください

• リポジトリのトップページにアクセス
• このページの「Code」→「Download ZIP」から ZIP ファイルをダウンロード
• ダウンロードした ZIP ファイルを展開してください

リポジトリのディレクトリに移動し、以下のコマンドを実行してください。

npm install
npm run setup

手順 3. Visutal Studio Code のセットアップ

Visual Studio Code でリポジトリをオープンします。

拡張機能(Extensions)メニューを開いて検索バーに @recommended と記入し、WORKSPACE RECOMMENDATIONS に表示された拡張機能をインストールします。

手順 4. アプリの作成

カスタマイズを追加するアプリを作成します。

セッションでは「営業支援パック」の「案件管理」アプリにカスタマイズを追加します。 https://jp.cybozu.help/k/ja/user/create_app/sales_pack.html

手順 5. 認証情報・アプリ情報の設定

以下のファイルを編集します。

• .env
  • KINTONE_BASE_URL: kintone 環境の URL（例：https://example.cybozu.com）
  • KINTONE_USERNAME: ユーザ名
  • KINTONE_PASSWORD: パスワード
• customize-manifest.json
  • app: カスタマイズを追加するアプリのアプリ ID

手順 6. 動作確認

以下のコマンドを実行します。

npm run build
npm run upload

アプリのレコード一覧画面にアクセスしてダイアログが表示されたら成功です！

開発方法

カスタマイズのビルド・アップロード

以下のコマンドを実行します。
srcディレクトリ内のソースコードを変更すると自動的にカスタマイズのビルド・アップロードが行われます。

npm run start

自動テストの実行

※VSCode の Vitest 拡張機能をインストールしている場合は、拡張機能からテストを実行することを推奨します。

以下のコマンドを実行します。
ファイルの変更に応じてテストは自動的に再実行されます。

npm run test

テストの書き方は Vitest の公式ドキュメントを参照してください。

Getting Started | Guide | Vitest

リンター・フォーマッターの実行

※VSCode の ESLint・Prettier 拡張機能をインストールしている場合はファイル保存時に自動実行されます。

以下のコマンドを実行します。

# チェックのみ
npm run lint

# 自動修正
npm run fix

Tips 1. kintone.events.onのハンドラに型を指定する

現在、@kintone/dts-gen の提供する型ではkintone.events.onのイベントオブジェクトの型は any になっています。

declare namespace kintone {
  namespace events {
    function on(event: string | string[], handler: (event: any) => any): void;

js-sdk/packages/dts-gen/kintone.d.ts at master · kintone/js-sdk

このテンプレートリポジトリではいくつかのイベントオブジェクトについて型定義を提供しています。
これを指定することでイベントハンドラ内で受け取ったイベントを安全に扱うことができます。

// eventTypes[イベントタイプ]で型を指定
kintone.events.on(
  "app.record.edit.submit",
  (event: eventTypes["app.record.edit.submit"]) => {
    console.log(event.appId);
  }
);

Tips 2. @kintone/dts-gen の使い方

@kintone/dts-gen を使うことで レコードの型定義ファイルを生成することができます。

生成した型は、JS API でレコードを扱う際に指定することができます。

型定義ファイルの生成方法

以下のコマンドを実行してください。

npm run generate:dts アプリID

src/@types/app-アプリID.d.tsというファイルが作成されます。

型定義ファイルの使い方

イベントハンドラから取得したレコードに対して型を指定してください。

kintone.events.on("app.record.edit.submit", (event) => {
  const record: App123.Record = event.record;
  console.log(record);
});

Tips 3. @kintone/rest-api-client の使い方

@kintone/rest-api-client を使うことで kintone REST API を簡単に操作することができます。

レコードの型には dts-gen で生成したAppアプリID.SavedRecordと、KintoneRestAPI.RecordまたはKintoneRestAPI.PartialRecordを組み合わせて指定してください。

import { KintoneRestAPIClient } from "@kintone/rest-api-client";

// クライアントの作成
const client = new KintoneRestAPIClient();

// レコードの取得
const records = await client.record.getAllRecords<
  KintoneRestAPI.Record<App123.SavedRecord>
>({
  app: 123,
});

// レコードの追加
const recordsToAdd: Array<KintoneRestAPI.PartialRecord<App123.SavedRecord>> =
  [{...}, {...}, {...}];
client.record.addAllRecords({ app: 1, records: recordsToAdd });

詳しくはドキュメントを参照してください。

https://cybozu.dev/ja/kintone/sdk/rest-api-client/kintone-javascript-client/

ライセンス

MIT