action開発手順作成

plugin/kintone-addins/readme.md

@@ -0,0 +1,230 @@
+# kintone自動化開発ツールのアクションのアドイン開発手順
+
+## 1. アクションの登録
+
+アクションプラグインをシステムに登録するためには、以下の情報をデータベースの`action`表に挿入する必要があります。
+
+|列名    | 項目          | 説明                                     |
+|-----   |-------------|-------------------------------------------|
+|name    | 名前        | アクションプラグイン名（ユニークな名前が必要）  |
+|title   |タイトル      | タイトル                                   |
+|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": "条件式を設定してください"
+    }
+  }
+]
+```
+
+### プロパティ属性設定画面
+![プロパティ属性設定画面](../../document/action-property.png)
+
+
+### 属性UIコンポーネントの共通属性
+| 属性          | 設定値の例                  | 説明                                                                         |
+|-------------|--------------------|----------------------------------------------------------------------------|
+| component   | InputText  | コンポーネントの種類を示しており、この場合は選択リストを意味します。<br>使用可能なコンポーネントを参照|
+| displayName | 表示／非表示         | ユーザーに対して表示されるコンポーネントの名前です。                                         |
+| options     | ["表示", "非表示"]   | ユーザーが選択できるオプションの配列です。<br>SelectBoxのみ使用可能 |
+| modelValue  | 空文字             | コンポーネントの初期値を設定します。<br>初期設定ないの場合は空文字で設定する。
+| name        | field              | 属性の設定値の名前です。   |
+| placeholder | 対象項目を選択してください| 入力フィールドに表示されるプレースホルダーのテキストです。この場合は設定されていません。          |
+
+### 使用可能なコンポーネント
+| No. | コンポーネント名      | コンポーネントタイプ | 説明                                     |
+|-----|------------------|------------------|-----------------------------------------|
+| 1   | テキストボックス    | InputText        | 一行のテキスト入力が可能なフィールドです。                 |
+| 2   | テキストボックス（改行可能） | MuiltInputText   | 複数行のテキスト入力が可能なテキストエリアです。          |
+| 3   | 日付            | DatePicker       | 日付を選択するためのカレンダーコンポーネントです。          |
+| 4   | フィールド選択     | FieldInput       | システムのフィールドを選択するための入力コンポーネントです。   |
+| 5   | 選択リスト        | SelectBox        | 複数のオプションから選択するためのドロップダウンリストです。   |
+| 6   | 条件式設定       | ConditionInput   | 条件式やロジックを入力するためのコンポーネントです。         |
+| 7   | 色選択       | ColorPicker   | 色を設定する（追加予定中）         |
+| 8   | 他のアプリのフィールド選択       | AppFieldPicker   | 他のアプリのフィールドを選択する（追加予定中）         |
+| 9   |ユーザー選択       | 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`メソッドを実装します。
+