rex0220 kSQL アクションプラグイン - ① 詳細画面編（ボタンとイベント）

Last updated at 2026-11-08Posted at 2026-11-01

1 件のレコードに対してアクションを動かす方法 — 詳細画面のボタン、保存・ステータス変更のイベント、実行時に値を聞く入力項目、出し分けの計算式 — をまとめます。

詳細画面のボタン

設定したアクションが、詳細画面のヘッダーにボタンで出ます。表示条件（計算式）でレコードごとに出し分けできます。

押すと、実行条件の検証 → 入力ダイアログ（入力項目があるとき）→ 書き込みの確認 → 実行 → 結果表示、の順に動きます。画面は自動で再読み込みせず、このアプリに書いたときだけ結果に［画面を更新］が出ます。

レコードの保存・ステータス変更・削除に、アクションを紐づけられます（関連レコード集計プラグインと同じ方式）。

イベント	タイミング
保存後（追加）	レコードの追加の保存後
保存後（編集）	レコードの編集の保存後（一覧のインライン編集を含む）
ステータス変更	変更が確定した後（変更後のレコードの値で実行されます）
削除したあと	レコードの削除が成功した後（消す直前に取っておいた控えの値で実行されます）

イベントの実行は「確認なし + 書き込み上限」に固定です（保存のたびに確認は出ません）。実行条件（計算式）で対象を絞ります
保存後のイベントは、処理が終わるまで画面の遷移を待たせます。SQL の処理時間の分だけ、保存後の画面の切り替えが遅くなります。実行時間が長い処理は、ボタン実行か kSQL Flow を利用してください
保存後の SQL 実行が失敗しても、保存済みのレコードは元に戻りません。失敗は遷移後の画面で通知します
ブラウザーの画面の操作だけが対象です。

操作	イベント実行
PC のレコード追加・編集の保存	対象
PC の一覧のインライン編集	対象
PC のステータス変更	対象
モバイルのレコード追加・編集の保存、ステータス変更	対象
PC の詳細画面・一覧からのレコード削除、モバイルの詳細画面からの削除	対象（起動に「削除したあと」を選んだとき）
REST API による更新・削除（他システム・他プラグインを含む）	対象外
CSV（ファイル）読み込みによる更新	対象外

アクションの実行時に、利用者から値を聞けます。

型: 文字列 / 数値 / 日付 / 日時 / 選択肢 / 相対日付
値は SQL の DECLARE @名前 = '既定値' のパラメーターの値として渡されます。SQL の文字列へ直接連結しない方式で、入力値が SQL の構文として解釈されることはありません
予約パラメーター（@_record など）も、SQL で DECLARE した名前にだけ実行時の値が入ります。実行時の値が無いときは DECLARE の既定値が使われます。表示中のレコード番号を使うなら、SQL の先頭に DECLARE @_record = '0'; と書きます（値は文字列で渡されるので、既定値も文字列で書きます）
パラメーターの源泉は 3 つ: 予約（@_app・@_record・@_user など。プラグインが自動で渡す）/ 計算式（レコードの値などから作る）/ 入力項目

「選択肢」の候補は、固定の一覧だけでなく計算式でも作れます。押したときに評価するので、その日を基準にした候補を出せます。

請求月を前月・当月・翌月から選ばせるなら、こう書きます。

ARRAY(DATE_ADD("TODAY", -1, "month", "YYYY-MM"),
      DATE_FORMAT("TODAY", "YYYY-MM"),
      DATE_ADD("TODAY",  1, "month", "YYYY-MM"))

画面に出す文字と、SQL に渡す値を分けられます。 担当者を選ばせるとき、画面には表示名を出して、SQL にはログイン名を渡す、という形です。

	計算式	出るもの
選択肢の値（SQL に渡る）	`SEL_CODE(担当者, "array")`	`sato`、`suzuki`
選択肢のラベル（画面に出る）	`SEL_NAME(担当者, "array")`	`佐藤太郎`、`鈴木花子`

値とラベルは同じ数・同じ順で返します。数が違うときは実行しません
候補が 1 つも残らないときも実行しません（空の値で条件が広く当たるのを防ぐため）
式にレコードの項目を書けるのは、一覧から実行しないアクション（詳細画面のボタンだけ）です。入力は実行 1 回につき 1 回しか聞かないので、一覧からの実行では対象のレコードが決まりません。日付計算やログイン情報は、どの起動でも使えます

入力欄の初期値も計算式で決められます。選択肢では、同じ値の候補があるときだけ選ばれます。

設定	効く型	例
既定値（計算式）	すべて	`顧客コード`、`10`、`DATE_FORMAT("TODAY", "YYYY-MM")`
最小値・最大値	数値	1 〜 999
最小文字数・最大文字数	文字列	3 〜 10 文字

指定した範囲は入力欄の右に小さく出ます。範囲の外のまま実行しようとすると、理由を出して止まります。

計算式プラグインと同じ式です。使える場所は 5 つで、すべて読み取り専用です。

表示条件はボタンを出すかどうか、実行条件は押されたときに実行してよいかの判定です。表示条件で消したボタンは押せませんが、一覧の一括処理では選んだレコードごとに実行条件を見るので、条件から外れたレコードは「条件外」として数えます。

論理の組み合わせは関数形で書きます: AND(金額 > 0, 処理状況 = "未処理")
式には // から行末までのコメントが書けます（計算式プラグインと同じ）
結果メッセージでは実行の結果の変数が使えます: $result_status・$result_inserted・$result_updated・$result_deleted・$result_total・$result_ms など