データの取得
データの取得
Word APIでは、テンプレートファイルと記入済みファイルの2つのファイルを比較して、 書き込まれた内容「データ」とデータに対応する「ラベル（項目名）」を取得することができます。
テンプレートファイルはラベル（項目名）と入力欄を定義したファイルです。
Word APIでは、入力欄を段落と表で分類しています。
表は形式によって3つのタイプに分類しています。
「ラベル（項目名）-データ」を取得するための入力欄で、上図の赤枠が該当します。ラベル（項目名）のみを定義します。
「ラベル（項目名）-データ」を取得するための入力欄で、上図の緑枠が該当します。ラベル（項目名）と入力欄を隣り合う形式で定義します。
「ラベル（項目名）-複数データ」を取得するための入力欄で、上図の青枠が該当します。表のヘッダー行にラベル（項目名）を定義します。
上記の2つを組み合わせた形式で、上図の紫枠が該当します。「ラベル（項目名）-複数データ」を取得するための入力欄を定義します。ラベル名が「列のラベル（項目名）_行のラベル（項目名）」になります。上図の場合は出張先_出張内容、目的_出張内容、出発日_出張内容、帰着日_出張内容がラベル（項目名）になります。
上記で述べた通り、Word APIでは表を形式によって3つのタイプに分類しています。
ここでは、表のタイプの判別方法を説明します。
本節の表の例について、「背景色あり」はラベル、「背景色なし」はデータを表します。
「赤字」のデータはセルの内容が2つのファイルで異なることを表します。
テンプレートファイルの図の緑枠に該当する表のタイプで、ラベル（項目名）とデータが隣り合います。
取得するデータは基本的に「ラベル（項目名）-データ」の連想配列になります。
ラベル（項目名）が重複した際は、複数データになります。
| A | A_1 | C | C_1 |
| B | B_1 | ||
| C | C_2 | ||
上の表の場合「ラベル（項目名）-データ」の連想配列は以下の通りになります。
先頭行に変更が無い表のタイプで、テンプレートファイルの図の青枠または紫枠に該当する表のタイプです。
この表のタイプでは、最初に変更が発生した行の先頭セルの変更有無でさらに2つのタイプに分類します。
テンプレートファイルの図の青枠に該当する表のタイプです。
取得するデータは列番号が同一のヘッダー行とデータ行の「ラベル（項目名）-複数データ」の連想配列になります。
| A | B | C | D |
| A_1 | B_1 | C_1 | D_1 |
| A_2 | B_2 | C_2 | D_2 |
| A_3 | B_3 | C_3 | D_3 |
上の表の場合「ラベル（項目名）-データ」の連想配列は以下の通りになります。
テンプレートファイルの図の紫枠に該当する表のタイプです。
取得するデータは列番号が同一のヘッダー行とデータ行の「列のラベル（項目名）_行のラベル（項目名）-複数データ」の連想配列になります。
| A | B | C | D |
| X | B_1 | C_1 | D_1 |
| Y | B_2 | C_2 | D_2 |
| Z | B_3 | C_3 | D_3 |
上の表の場合「ラベル（項目名）-データ」の連想配列は以下の通りになります。
これまでは、表のタイプを説明するために単純な表を例にとりましたが、実際の表ではセルの結合が存在します。
Word APIのデータ取得では、結合されたセルはすべて同じ値が入力されているものとして扱います。
以下の表のように、2行目と3行目の1,2列目、3,4列目が結合されている表を例にとります。
| A | A_1 | C | C_1 |
| B | B_1 | ||
| C | C_2 | ||
上の表の場合、以下の表と等価として扱います。
| A | A_1 | C | C_1 |
| B | B | B_1 | B_1 |
| C | C | C_2 | C_2 |
先頭行に変更有の表のタイプの場合、ラベル（項目名）とデータは隣り合うため、 「ラベル（項目名）-データ」の連想配列は以下の通りになります。
以下の表のように、3行目の1,2列目、4行目の3,4列目が結合されている表を例にとります。
| A | B | C | D |
| A_1 | B_1 | C_1 | D_1 |
| A_2 | C_2 | D_2 | |
| A_3 | B_3 | C_3 | |
上の表の場合、以下の表と等価として扱います。
| A | B | C | D |
| A_1 | B_1 | C_1 | D_1 |
| A_2 | A_2 | C_2 | D_2 |
| A_3 | B_3 | C_3 | C_3 |
上の表の場合「ラベル（項目名）-データ」の連想配列は以下の通りになります。
これまでは、すべてのセルが記入済み。かつ行数と列数が同数の場合を例としてとりました。
実際には未記入のセルや、列数が異なる場合があります。
ここでは、先頭行に変更無かつ先頭セルの変更有についてこれらのパターンの「ラベル（項目名）-データ」の取得方法を説明します。
セルが未記入の場合は、2つのファイルに変更が発生していないことになります。
以下の表のように、未記入のセルが最初に変更が発生した行の先頭セルの場合、
先頭セルに変更無の条件に一致しますが、
未記入の場合のみは、先頭セルに変更有（リンク）と判断します。
| A | B | C | D |
| B_1 | C_1 | D_1 | |
| A_2 | A_2 | C_2 | D_2 |
| A_3 | B_3 | C_3 | C_3 |
列番号が一致するように、未記入のセルは空のデータとして扱います。
上の表の場合「ラベル（項目名）-データ」の連想配列は以下の通りになります。
以下の表のように、データ行に変更無のセルが存在する場合は、あらかじめ入力されたデータとして扱います。
| A | B | C | D |
| A_1 | B_1 | C_1 | D_1 |
| X | A_2 | C_2 | D_2 |
| A_3 | B_3 | C_3 | C_3 |
上の表の場合「ラベル（項目名）-データ」の連想配列は以下の通りになります。
以下の表のように、データ行に変更無のセルが先頭に存在する場合は、 先頭セルに変更無 と同様に扱われ、1行目のみ取得されます。
| A | B | C | D |
| X | B_1 | C_1 | D_1 |
| A_2 | B_2 | C_2 | D_2 |
| A_3 | B_3 | C_3 | C_3 |
上の表の場合「ラベル（項目名）-データ」の連想配列は以下の通りになります。
行単位で、すべてのセルが未記入の場合は、対象の行を無視します。
| A | B | C | D |
| A_1 | B_1 | C_1 | D_1 |
| A_3 | B_3 | C_3 | C_3 |
上の表の場合「ラベル（項目名）-データ」の連想配列は以下の通りになります。
データ行のセルが異なる場合、対象行の先頭のセルの内容で以下の2パターンに分かれます。
対象の行は、先頭セルに変更無と同様で、列番号が同一のヘッダー行とデータ行の「列のラベル（項目名）_行のラベル（項目名）-複数データ」の連想配列を取得します。
| A | B | C | D |
| A_1 | B_1 | C_1 | D_1 |
| A_2 | B_2 | C_2 | D_2 |
| X | C_3 | D_3 |
上の表の場合「ラベル（項目名）-データ」の連想配列は以下の通りになります。
対象のセルは入力が省略されたセル（空データ）として扱います。
| A | B | C | D |
| A_1 | B_1 | C_1 | D_1 |
| A_2 | B_2 | C_2 | D_2 |
| B_3 | C_3 | D_3 |
上の表の場合、以下の表と等価として扱います。
| A | B | C | D |
| A_1 | B_1 | C_1 | D_1 |
| A_2 | B_2 | C_2 | D_2 |
| B_3 | C_3 | D_3 |
上の表の場合「ラベル（項目名）-データ」の連想配列は以下の通りになります。
Word APIでは、「ラベル（項目名）-データ」の組をフォームデータと呼びます。
Word APIでデータの取得を実行すると、コマンドラインインターフェイス以外では以下の配列を返します。
| クラス | 説明 |
|---|---|
| ParagraphFormData | 段落の入力欄を扱うクラスで、「ラベル（項目名）-データ」の連想配列をメンバ変数に持ちます。 |
| TableFormData | 表の入力欄を扱うクラスで、「ラベル（項目名）-複数データ」の連想配列をメンバ変数に持ちます。 |
コマンドラインインターフェイス以外で、フォームデータの取得を実行した例を説明します。
以下の図は、記入済みファイル（左）と取得したフォームデータ（右）のイメージです。
テンプレートファイルに対して、灰色背景と赤文字の箇所が書き込まれたデータを表しています。
取得したフォームは、以下の連想配列が返されます。
コマンドラインインターフェイスでは、取得したフォームデータが以下の形式で表示されます。
[Install directory]/samples/templates/データ取得.zipにデータの取得のサンプルファイルを含んでおります。