295 lines
13 KiB
Markdown
295 lines
13 KiB
Markdown
# kintone自動化開発ツールのアクションのアドイン開発手順
|
||
|
||
## 1. アクションの登録
|
||
|
||
アクションプラグインをシステムに登録するためには、以下の情報をデータベースの`action`表に挿入する必要があります。
|
||
|
||
|列名 | 項目 | 説明 |
|
||
|----- |-------------|-------------------------------------------|
|
||
|name | 名前 | アクションプラグイン名（ユニークな名前が必要） |
|
||
|title |タイトル | タイトル （20文字以内） |
|
||
|subtitle|サブタイトル | サブタイトル |
|
||
|outputpoint|出力ポイント | 出力値に分岐がある場合の接続点 |
|
||
|property|プロパティ | アクションプラグインの属性（json形式） |
|
||
|
||
### 登録の例
|
||
|
||
以下は「表示／非表示」アクションプラグインを登録する例です。
|
||
|
||
- name: "表示／非表示"
|
||
- title: "指定項目の表示・非表示を設定する"
|
||
- subtitle: "表示／非表示"
|
||
- outputpoint: "[]"
|
||
- property:
|
||
|
||
```json
|
||
[
|
||
{
|
||
"component": "FieldInput",
|
||
"props": {
|
||
"displayName": "フィールド",
|
||
"modelValue": {},
|
||
"name": "field",
|
||
"placeholder": "対象項目を選択してください"
|
||
}
|
||
},
|
||
{
|
||
"component": "SelectBox",
|
||
"props": {
|
||
"displayName": "表示／非表示",
|
||
"options": ["表示", "非表示"],
|
||
"modelValue": "",
|
||
"name": "show",
|
||
"placeholder": ""
|
||
}
|
||
},
|
||
{
|
||
"component": "ConditionInput",
|
||
"props": {
|
||
"displayName": "条件",
|
||
"modelValue": "",
|
||
"name": "condition",
|
||
"placeholder": "条件式を設定してください"
|
||
}
|
||
}
|
||
]
|
||
```
|
||
|
||
### プロパティ属性設定画面
|
||
|
||
|
||
|
||
### 属性UIコンポーネントの共通属性
|
||
| 属性 | 設定値の例 | 説明 |
|
||
|-------------|--------------------|----------------------------------------------------------------------------|
|
||
| component | InputText | コンポーネントの種類を示しており、この場合は選択リストを意味します。<br>使用可能なコンポーネントを参照|
|
||
| displayName | 表示／非表示 | ユーザーに対して表示されるコンポーネントの名前です。 |
|
||
| options | ["表示", "非表示"] | ユーザーが選択できるオプションの配列です。<br>SelectBoxのみ使用可能 |
|
||
| modelValue | 空文字 | コンポーネントの初期値を設定します。<br>初期設定ないの場合は空文字で設定する。
|
||
| name | field | 属性の設定値の名前です。 |
|
||
| placeholder | 対象項目を選択してください| 入力フィールドに表示されるプレースホルダーのテキストです。この場合は設定されていません。 |
|
||
| hint | 説明文| 長い説明文を設定することが可能です。（markdown形式サポート予定、現在HTML可能） |
|
||
| selectType |`single` or `multiple`| フィールド選択・他のアプリのフィールド選択の選択モードを設定する |
|
||
|
||
|
||
|
||
### 使用可能なコンポーネント
|
||
| No. | コンポーネント名 | コンポーネントタイプ | 説明 |
|
||
|-----|------------------|------------------|-----------------------------------------|
|
||
| 1 | テキストボックス | InputText | 一行のテキスト入力が可能なフィールドです。 |
|
||
| 2 | テキストボックス（改行可能） | MuiltInputText | 複数行のテキスト入力が可能なテキストエリアです。 |
|
||
| 3 | 日付 | DatePicker | 日付を選択するためのカレンダーコンポーネントです。 |
|
||
| 4 | フィールド選択 | FieldInput | システムのフィールドを選択するための入力コンポーネントです。 |
|
||
| 5 | 選択リスト | SelectBox | 複数のオプションから選択するためのドロップダウンリストです。 |
|
||
| 6 | 条件式設定 | ConditionInput | 条件式やロジックを入力するためのコンポーネントです。 |
|
||
| 7 | イベント設定 |EventSetter | ボタンイベント設定のコンポーネントです。 |
|
||
| 8 | 色選択 | ColorPicker | 色を設定する（追加予定中） |
|
||
| 9 | 他のアプリのフィールド選択 | AppFieldPicker | 他のアプリのフィールドを選択する（追加予定中） |
|
||
| 10 |ユーザー選択 | UserPicker | ユーザーを選択する（追加予定中） |
|
||
|
||
## 2.アクションアドインの開発
|
||
|
||
### 1. Action pluginファイルの追加
|
||
アクションプラグインを作成するためには、以下のディレクトリ構造に`TypeScript`ファイルを追加します。
|
||
```
|
||
KintoneAppBuilder
|
||
└─ plugin
|
||
└─ kintone-addins
|
||
└─ src
|
||
└─ actions
|
||
└─ your-action.ts // ここにアクションプラグインのtsファイルを追加
|
||
```
|
||
### 2. アクションクラスの実装手順
|
||
`IAction` インターフェースに従ってアクションクラスを実装します。
|
||
```typescript
|
||
|
||
/**
|
||
* アクションのインターフェース
|
||
*/
|
||
export interface IAction{
|
||
// アクションのユニークな名前
|
||
name:string;
|
||
//属性設定情報
|
||
actionProps: Array<IActionProperty>;
|
||
//アクションのプロセス実行関数
|
||
process(prop:IActionNode,event:any,context:IContext):Promise<IActionResult>;
|
||
//アクションの登録関数
|
||
register():void;
|
||
}
|
||
```
|
||
#### サンプルコード
|
||
```ts
|
||
// アクションの属性定義
|
||
interface IShownProps{
|
||
field:IField;
|
||
show:string;
|
||
condition:string;
|
||
}
|
||
|
||
// 表示／非表示アクション
|
||
export class FieldShownAction implements IAction{
|
||
name: string;
|
||
actionProps: IActionProperty[];
|
||
props:IShownProps;
|
||
constructor(){
|
||
this.name="表示／非表示"; // DBに登録したアクション名一致する必要があり
|
||
this.actionProps=[];
|
||
//プロパティ属性の初期化
|
||
this.props={
|
||
field:{code:''},
|
||
show:'',
|
||
condition:''
|
||
}
|
||
//アクションの自動登録
|
||
this.register();
|
||
}
|
||
/**
|
||
* アクションの実行を呼び出す
|
||
* @param actionNode
|
||
* @param event
|
||
* @returns
|
||
*/
|
||
async process(actionNode:IActionNode,event:any,context:IContext):Promise<IActionResult> {
|
||
// ... (アクション処理の実装)
|
||
}
|
||
|
||
register(): void {
|
||
actionAddins[this.name]=this;
|
||
}
|
||
}
|
||
new FieldShownAction();
|
||
|
||
```
|
||
アクションプラグインを実装するには、`IAction`インターフェースの定義に従って、必要なメソッドとプロパティをクラスに実装します。
|
||
以下に、`IAction`インターフェースを用いて`表示／非表示`アクションを実装する手順を説明します。
|
||
1. **アクションの属性定義**
|
||
|
||
2. **アクションクラスの作成**:
|
||
- `IAction`インターフェースを実装する新しいクラス`FieldShownAction`を作成します。
|
||
|
||
3. **コンストラクタの定義**:
|
||
- アクション名や初期プロパティを設定します。
|
||
- このクラスのインスタンスが作成された際に、自動的にアクションが登録されるように、コンストラクタ内で`register`メソッドを呼び出します。
|
||
|
||
4. **プロセス実行関数の実装** (`process`):
|
||
- `process`メソッドは、アクションの主要なロジックを含み、アクションの実行時に呼び出されます。
|
||
|
||
|
||
- * 以下は`process`関数のパラメータとその用途を説明します。
|
||
|
||
| パラメータ名 | 型 | 用途 |
|
||
|----------|----------------|------------------------------------------------------------------------------------------------|
|
||
| actionNode | `IActionNode` | Kintone自動化ツールのアクションの設定やプロパティ情報を保持します。 |
|
||
| event |kintoneのイベント情報| レコードやエラー制御で使用します |
|
||
| context | `IContext` | 現在のレコード情報や変数など、実行に必要なデータへのアクセスを提供します。 |
|
||
|
||
- このメソッド内で、アクションに必要な処理を行います。
|
||
- 1. アクションプロパティの取得:
|
||
`Kitone自動化ツール`を設定したプロパティの値を取得する
|
||
|
||
```ts
|
||
//プロパティ設定を取得する
|
||
this.actionProps=actionNode.actionProps;
|
||
//プロパティ設定のデータ型は必要な情報が含めますか
|
||
if (!('field' in actionNode.ActionValue) && !('show' in actionNode.ActionValue)) {
|
||
return result
|
||
}
|
||
//既定のプロパティのインターフェースへ変換する
|
||
this.props = actionNode.ActionValue as IShownProps;
|
||
```
|
||
|
||
- 2. 条件式の評価
|
||
getConditionResult関数を呼び出して条件式を評価します。この関数は、現在のコンテキストに基づいて条件式が真か偽かを返します。
|
||
```ts
|
||
//条件式の計算結果を取得
|
||
const conditionResult = this.getConditionResult(context);
|
||
/**
|
||
*
|
||
* @param context 条件式を実行する
|
||
* @returns
|
||
*/
|
||
getConditionResult(context:any):boolean{
|
||
//プロパティ`condition`から条件ツリーを取得する
|
||
const tree =this.getCondition(this.props.condition);
|
||
if(!tree){
|
||
//条件を設定されていません
|
||
return true;
|
||
}
|
||
return tree.evaluate(tree.root,context);
|
||
}
|
||
```
|
||
- 3. Kintone APIを使用して、フィールドの表示／非表示の制御
|
||
```ts
|
||
//条件式の計算結果を取得
|
||
const conditionResult = this.getConditionResult(context);
|
||
if(conditionResult){
|
||
if(this.props.show==='表示'){
|
||
kintone.app.record.setFieldShown(this.props.field.code,true);
|
||
}else if (this.props.show==='非表示'){
|
||
kintone.app.record.setFieldShown(this.props.field.code,false);
|
||
}
|
||
}
|
||
```
|
||
5. **登録関数の実装** (`register`):
|
||
- アクションをアドインシステムに登録するための`register`メソッドを実装します。
|
||
|
||
6. **アクションプロセス`ActionProcess`に参照追加**
|
||
```ts
|
||
import { actionAddins } from "../actions";
|
||
import '../actions/must-input';
|
||
import '../actions/auto-numbering';
|
||
import '../actions/field-shown';
|
||
import '../actions/your-action'; //ここに新規のアクションの参照を追加する
|
||
...
|
||
```
|
||
### 3. デプロイ
|
||
1. **プロジェクトをビルドする**
|
||
- 本番環境にデプロイする場合
|
||
```bash
|
||
cd plug\kintone-addins\
|
||
npm install
|
||
npm run build
|
||
```
|
||
- 開発環境にデプロイする場合（ソースマップ出力ます）
|
||
```bash
|
||
cd plug\kintone-addins\
|
||
npm install
|
||
npm run build:dev
|
||
```
|
||
2. **Azureにデプロイする**
|
||
- Azure 拡張機能のインストール:
|
||
VSCode の拡張機能ペインで`Azure Tools`を検索し、インストールします。
|
||
|
||
- Azure にログイン:
|
||
- Azure Account 拡張機能を使用して Azure にログインします。
|
||
|
||
- Azure へのデプロイ:
|
||
- 「Deploy to Web App」オプションを使用し、デプロイするファイルやフォルダを指定します。
|
||
|
||
- デプロイの確認:
|
||
- Azure App Service 拡張機能でデプロイが完了したことを確認します。
|
||
- ka-addin の URL にアクセスしてアプリケーションが正常に動作しているか確認します。
|
||
|
||
3. **ローカルでプラグインをテストする**
|
||
1. kintone-addinsをPreviewで起動する
|
||
```bash
|
||
yarn build:dev
|
||
yarn preview
|
||
#またはyarn devは yarn build:dev + yarn preview と同じです
|
||
yarn dev
|
||
```
|
||
2. **ngrokをインストールする**
|
||
1. [ngrok の公式ウェブサイト](https://ngrok.com/)にアクセスします。
|
||
2. 「Sign up」をクリックしてアカウントを登録するか、既存のアカウントにログインします。
|
||
3. 登録またはログイン後、ダッシュボードに進み、ダウンロードリンクが表示されます。操作システム（Windows、macOS、Linux）に応じて、適切なバージョンを選択してダウンロードします。
|
||
4. ダウンロード後、`.zip` ファイルを解凍します。
|
||
5. ngrok を設定する
|
||
1. ngrok ダッシュボードにログインし、ホームページで認証トークンを見つけます。
|
||
2. ターミナル（またはコマンドプロンプト）を開き、以下のコマンドを実行して認証トークンを追加します：
|
||
```bash
|
||
ngrok config add-authtoken <認証トークン>
|
||
```
|
||
6. ngrok を起動する
|
||
```bash
|
||
ngrok https http://localhost:4173/
|
||
``` |