警告

このページで説明しているAPIは、開発を検討中のAPIです。

アップデートオプション内の「検討中の新機能」から動作をお試しいただけます。
設定方法は、 新機能の有効／無効の切り替え手順 を参照してください。

APIに関するフィードバックを、ユースケースとともに、 kintoneの改善に協力する フォームへぜひご登録ください。

フィードバックの例

• 「APIラボで提供されているAPIを早く本番環境で利用したい」
• 「こういう用途で使うために、このようなAPIを提供してほしい」

この機能を有効にすると、大きく次の3点が変わります。

• 画面上でテーブルフィールドへ新しく追加した行のidとして一時的な値が割り当てられ、JavaScript APIで取得できます。
• JavaScript APIでテーブルフィールドを更新するとき、行の追加／更新／削除／並び替えをidをもとに判断する挙動へ変わります。
• JavaScript APIでテーブルの行を追加、削除、または並べ替えたときにも、テーブルフィールドの「フィールドの値を変更したときのイベント」が発生します。

利用するには、検討中の新機能の「JavaScript API：テーブルの行へのID付与、テーブル操作時のイベント発生、およびテーブル操作用APIを追加する機能」を有効にしてください。

テーブルフィールドの行のidには、次の2種類の値が入ります。

仮IDはレコードのデータとしては保存されず、レコード保存時に永続化済みIDへ置き換えられるため、保存の前後で同じ行のidは一致しません。
また、仮IDは、異なるテーブルフィールドの行を含めて重複しません。
仮IDは、既存の永続化済みIDとも重複しません。

次のテーブルフィールドの値の例は、1行目が保存済みの行、2行目が画面上で追加した行のものです。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

"テーブル": {
  "type": "SUBTABLE",
  "value": [
    {
      "id": "147",
      "value": {
        "文字列__1行__0": {
          "type": "SINGLE_LINE_TEXT",
          "value": "サンプル１"
        },
        "数値_0": {
          "type": "NUMBER",
          "value": "1"
        }
      }
    },
    {
      "id": "5969ccdc-a8dd-4a31-bb8b-af27905100e9",
      "value": {
        "文字列__1行__0": {
          "type": "SINGLE_LINE_TEXT",
          "value": "サンプル２"
        },
        "数値_0": {
          "type": "NUMBER",
          "value": "2"
        }
      }
    }
  ]
}

対象の画面とAPI

PC版とモバイル版の、レコード追加画面とレコード編集画面が対象です。
仮IDは、これらの画面での次のイベントまたはAPIで取得できるレコードのデータにだけ含まれます。

• イベントオブジェクトのrecordプロパティ
  • レコード追加画面を表示したときのイベント - app.record.create.show、mobile.app.record.create.show
  • レコード編集画面を表示したときのイベント - app.record.edit.show、mobile.app.record.edit.show
  • レコード追加画面でフィールドの値を変更したときのイベント - app.record.create.change.フィールドコード、mobile.app.record.create.change.フィールドコード
  • レコード編集画面でフィールドの値を変更したときのイベント - app.record.edit.change.フィールドコード、mobile.app.record.edit.change.フィールドコード
  • レコード追加画面で保存するときのイベント - app.record.create.submit、mobile.app.record.create.submit
  • レコード編集画面で保存するときのイベント - app.record.edit.submit、mobile.app.record.edit.submit
• JavaScript API
  • レコードの値を取得する - kintone.app.record.get()、kintone.mobile.app.record.get()
  • レコードに値をセットする - kintone.app.record.set()、kintone.mobile.app.record.set()

REST APIでの仮IDの扱い

リクエストにレコードのデータを指定するREST API（レコードの登録や更新など）でも、行のidに仮IDを指定できます。
仮IDを指定した行は、idを指定しない行と同じく、新規行として保存されます。
このため、kintone.app.record.get()で取得したレコードのデータを、そのままREST APIのリクエストに利用できます。

kintone.app.record.set()やイベントオブジェクトのreturnでテーブルフィールドの値を書き換えると、行のidに基づいて、行の追加／更新／削除／並べ替えが行われます。

新しい行の追加

次の行は新しく追加した行として扱われ、新しい仮IDが割り当てられます。

• idキーを省略した行
• idの値に「null」または書き換え前のテーブルに存在しない値を指定した行

書き換え前のテーブルに存在しない値をidとして指定した場合、その値が仮IDの形式に沿っていたとしても、指定した値は無視されて新しい仮IDを割り当てます。
仮IDとして、任意の値は指定できません。

行の更新と並び替え

書き換え前のテーブルに存在するidを指定した行は、書き換え前の対応するidの行の更新として扱われます。

• 行のidは変更されず、維持されます。
• 行の並び替えをするには、行のidを含めて行のデータを入れ替えます。
• 同じidの値を複数の行に指定していた場合、最初の行のみが既存の行の更新として扱われます。
  残りの行は新しい行の追加として扱われます。

行の削除

書き換え前のテーブルに存在したidが、書き換え後のテーブルにはない場合、その行は削除されます。

テーブルフィールドの書き換えの例

次にテーブルフィールドの書き換えの例を示します。
書き換え前は、idが「147」、「148」と仮IDの3行がある状態とします。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

"テーブル": {
  "type": "SUBTABLE",
  "value": [
    {
      "id": "147",
      "value": {
        "文字列__1行__0": {
          "type": "SINGLE_LINE_TEXT",
          "value": "サンプル１"
        },
        "数値_0": {
          "type": "NUMBER",
          "value": "1"
        }
      }
    },
    {
      "id": "148",
      "value": {
        "文字列__1行__0": {
          "type": "SINGLE_LINE_TEXT",
          "value": "サンプル２"
        },
        "数値_0": {
          "type": "NUMBER",
          "value": "2"
        }
      }
    },
    {
      "id": "b9805947-a88c-4c56-b0ad-13e589971378",
      "value": {
        "文字列__1行__0": {
          "type": "SINGLE_LINE_TEXT",
          "value": "サンプル３"
        },
        "数値_0": {
          "type": "NUMBER",
          "value": "3"
        }
      }
    }
  ]
}

次のデータで書き換えます。

• idが「147」の行と仮IDの行を更新しつつ並び替え
• idが「148」の行を削除
• 先頭に新しい行を追加

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

"テーブル": {
  "type": "SUBTABLE",
  "value": [
    {
      "value": {
        "文字列__1行__0": {
          "type": "SINGLE_LINE_TEXT",
          "value": "サンプル４"
        },
        "数値_0": {
          "type": "NUMBER",
          "value": "4"
        }
      }
    },
    {
      "id": "b9805947-a88c-4c56-b0ad-13e589971378",
      "value": {
        "文字列__1行__0": {
          "type": "SINGLE_LINE_TEXT",
          "value": "サンプル３（更新）"
        },
        "数値_0": {
          "type": "NUMBER",
          "value": "30"
        }
      }
    },
    {
      "id": "147",
      "value": {
        "文字列__1行__0": {
          "type": "SINGLE_LINE_TEXT",
          "value": "サンプル１（更新）"
        },
        "数値_0": {
          "type": "NUMBER",
          "value": "10"
        }
      }
    }
  ]
}

書き換え後のデータは次のようになります。
追加した1行目には、新しい仮IDが割り当てられます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

"テーブル": {
  "type": "SUBTABLE",
  "value": [
    {
      "id": "5e3719f9-64d7-422f-922d-9618b80b70d3",
      "value": {
        "文字列__1行__0": {
          "type": "SINGLE_LINE_TEXT",
          "value": "サンプル４"
        },
        "数値_0": {
          "type": "NUMBER",
          "value": "4"
        }
      }
    },
    {
      "id": "b9805947-a88c-4c56-b0ad-13e589971378",
      "value": {
        "文字列__1行__0": {
          "type": "SINGLE_LINE_TEXT",
          "value": "サンプル３（更新）"
        },
        "数値_0": {
          "type": "NUMBER",
          "value": "30"
        }
      }
    },
    {
      "id": "147",
      "value": {
        "文字列__1行__0": {
          "type": "SINGLE_LINE_TEXT",
          "value": "サンプル１（更新）"
        },
        "数値_0": {
          "type": "NUMBER",
          "value": "10"
        }
      }
    }
  ]
}

対象イベントとAPI

• イベントオブジェクトのreturnによる書き換え
  • レコード追加画面を表示したときのイベント - app.record.create.show、mobile.app.record.create.show
  • レコード編集画面を表示したときのイベント - app.record.edit.show、mobile.app.record.edit.show
  • レコード追加画面でフィールドの値を変更したときのイベント - app.record.create.change.フィールドコード、mobile.app.record.create.change.フィールドコード
  • レコード編集画面でフィールドの値を変更したときのイベント - app.record.edit.change.フィールドコード、mobile.app.record.edit.change.フィールドコード
  • レコード追加画面で保存するときのイベント - app.record.create.submit、mobile.app.record.create.submit
  • レコード編集画面で保存するときのイベント - app.record.edit.submit、mobile.app.record.edit.submit
• JavaScript API
  • レコードに値をセットする - kintone.app.record.set()、kintone.mobile.app.record.set()

この機能を有効にすると、テーブルフィールドと、テーブル内のフィールドの「フィールドの値を変更したときのイベント」について、発生するタイミングが変わります。

対象イベント

• PC版

  • レコード追加画面でフィールドの値を変更したときのイベント - app.record.create.change.フィールドコード
  • レコード編集画面でフィールドの値を変更したときのイベント - app.record.edit.change.フィールドコード

• モバイル版

  • レコード追加画面でフィールドの値を変更したときのイベント - mobile.app.record.create.change.フィールドコード
  • レコード編集画面でフィールドの値を変更したときのイベント - mobile.app.record.edit.change.フィールドコード

テーブルフィールドで値を変更したときのイベントが発生するタイミング

テーブルフィールドのフィールドコードを指定したイベントは、次のいずれかのタイミングで発生します。

• ユーザーが画面上の操作により行を追加、または削除したとき
• JavaScript APIで行を追加、削除、または並べ替えたとき

JavaScript APIでテーブルフィールドの値を書き換えた場合、行の追加、削除、並べ替えを組み合わせた変更でも、イベントは1回だけ発生します。
行の追加、削除、並べ替えは、行のidをもとに判定されます。

この機能を有効にしていない場合、JavaScript APIによる行の操作ではイベントは発生しません。

テーブル内のフィールドで値を変更したときのイベントが発生するタイミング

テーブル内のフィールドのフィールドコードを指定したイベントは、そのフィールドの値が変わったときにだけ発生します。
行の追加、削除、並べ替えだけを行い、フィールドの値が変わらない場合は発生しません。

新規追加行のフィールドは、初期値と異なる値が指定されている場合にイベントが発生します。

この機能を有効にしていない場合、JavaScript APIによるテーブルの書き換えは、書き換え前後の行の対応関係を考慮せずにすべてのフィールドの値を上書きします。
そのため、行を並べ替えただけでも、テーブル内のフィールドのイベントが発生します。
この機能を有効にすると、行の並べ替えのように行の値そのものが変わらない操作では、テーブル内のフィールドのイベントは発生しなくなります。

イベントの発生順序

JavaScript APIでテーブルフィールドの値を書き換えたときは、テーブル内のフィールドの値を変更したときのイベントが発生した後に、テーブルフィールドの値を変更したときのイベントが発生します。

イベントオブジェクトのchangesプロパティ

テーブルフィールドのフィールドコードを指定したイベントでは、イベントオブジェクトのchangesプロパティに、操作の種類を表すtypeが追加されます。
また、JavaScript APIでテーブルを書き換えたときのchanges.rowは「null」になります。

JavaScript APIによる書き換えが起きた場合に、行の並び替えなどの変更内容を確認するには、書き換え後のテーブルの値と書き換え前の値を比較してください。

複数のイベントハンドラーを同じイベントに登録している場合、先に呼ばれたハンドラーの書き換えにより、イベント発生時点のchanges.fieldやchanges.rowに対応する行がすでに削除されていることもあります。
この場合、後続のイベントハンドラーではchanges.fieldとchanges.rowが「null」になります。

サンプルコード

次のコードは、テーブル（フィールドコード：テーブル）をJavaScript APIで書き換えたときに、書き換え後の行のidの一覧を取得する例です。

1
2
3
4
5
6
7

kintone.events.on('app.record.create.change.テーブル', (event) => {
  if (event.changes.type === 'API_UPDATE_TABLE') {
    const rows = event.changes.field.value;
    const rowIds = rows.map((row) => row.id);
  }
  return event;
});