リファレンスマニュアル

クイックスタートガイド

Excel/PDF出力では、Excelファイル形式のテンプレートをもとに、kintoneのレコードデータを当てはめて、ExcelまたはPDFファイルを作成します。

予めの準備として、以下のものをご用意ください。

  • 本リファレンスマニュアルに従って作成された、Excelファイル形式のテンプレート。
  • テンプレートを格納するkintoneアプリ。上記テンプレートファイルを添付ファイルフィールドに保存しておきます。
  • 出力結果をkintoneアプリに保存したい場合には、保存したいkintoneアプリに添付ファイルフィールドを追加しておきます。

テンプレートファイルは、Excel形式で自由に作成することが可能です。

  • テンプレートファイルはMicrosoft Excelを利用しxlsx形式で作成してください。
  • マクロ(.xlsm形式)およびVBAはご利用頂くことができません。
  • 各セルの書式設定は常に有効になります。色指定などと合わせて、テンプレートファイルを作成することが可能です。
  • テンプレートはkintoneアプリカスタマイズ版・Job Runner版で共通のものが利用できます。ただしメタデータフィールドの一部に互換性がない部分がありますので、ご注意ください。

サンプルのアプリやテンプレートをダウンロードして、すぐ試すことのできるスターターキットもご用意しておりますので、合わせてご確認ください。

シート名の仕様

テンプレートファイルのシート名は、任意のシート名をつけることが可能です。

gusukuコマンドを使用して、フィールドの値をシート名に利用することも可能です。使用できるコマンドは以下になります。

$(フィールドコード) 指定したフィールドコードを出力します。
$("文字列") 指定した文字列をそのまま出力します。

シート名の先頭に「#」を付けると、一覧画面などから複数のレコード数分のシートを出力することが可能です。

#任意のシート名 選択したレコード数分のシートが追加されます。

シート名に「#」をつけてレコード数分のシートを出力する場合、以下の点に注意してください。

  • 元のシートのセル数が1万セル以内でなければなりません。
  • 元の「#」のついたシートは削除されます。他のシートから「#」のついたシートを参照するような数式があると、参照先がなくなってしまっているので、その数式でエラーが発生します。

gusukuコマンドの仕様

ほとんどgusukuコマンドは、フィールドコードの指定とともに利用します。フィールドコードは、日本語記述でも英語記述でもそのまま記述することが可能です。

注意すべき点

  • 置換できなかったgusukuコマンドは、空白が出力されます。
  • 確認できるエラーが発生した場合、エラーを報告するシートが追加されます。

gusukuコマンドの文字列結合について

  • 1つのセルに「$(year)年」「$(year)年$(month)月$(day)日」「$(sei)$(mei)様」などと記述可能です。
  • 1個めのコマンドは有効です。有効な例:「$STR(a)$(b)」「$IF,真,真偽(フィールドA)$(フィールドB)」も有効ですが$IFの判定はフィールドAに対して行われます。
  • 数値演算ではなく、全て文字列として扱われます。「$NUM(a)$(b)」は有効ですが、セルには文字列として格納されます。
  • 「西暦$(year)」という表記は利用できません。代わりに文字列を直接出力するコマンドを利用し、「$(“西暦”)$(year)」という形で記述してください。
  • 「$STR(a) $STR(b)」のように間に空白スペースが含まれる場合、空白スペースも出力されます。

gusukuコマンド一覧

gusukuコマンド 説明
$(フィールドコード) 指定したフィールドコードを出力します。
$STR(フィールドコード) 指定したフィールドコードを文字列として扱い出力します。
$NUM(フィールドコード) 指定したフィールドコードを数値として扱い出力します。
$DATE(フィールドコード) 指定したフィールドコードを日付として扱い出力します。
デフォルトではJSTのタイムゾーンで処理されます。
タイムゾーンを指定する場合には $DATE,UTC(フィールドコード) とタイムゾーン名を指定するか、
$DATE,GMT+1:00(フィールドコード)とオフセットで指定します。
$("文字列") 指定した文字列をそのまま出力します。

メタデータフィールド一覧

メタデータフィールドはいずれのシートでも利用可能です。

メタデータフィールド 説明
$($gusuku.meta.loginuser.code) 帳票を出力したkintoneユーザのログイン名を出力します(Job Runner版では非対応です)。
$($gusuku.meta.loginuser.name) 帳票を出力したkintoneユーザの表示名を出力します(Job Runner版では非対応です)。
$($gusuku.meta.loginuser.email) 帳票を出力したkintoneユーザのメールアドレスを出力します(Job Runner版では非対応です)。
$DATE($gusuku.meta.timestamp) 帳票を出力した日時を出力します。セルの書式設定でお好みの日付表記に変更してください。

特殊コマンド一覧

$IFはセルの先頭でのみ動作します。そのため、他のgusukuコマンドと結合させて「$(a)$IF(…)」のような形で指定することはできません。

gusukuコマンド 説明
$IF,真ラベル,偽ラベル(フィールドコード) フィールドコードで指定した値が"true"の文字列であれば「真ラベル」に、それ以外なら「偽ラベル」に書かれた文字列に置換します。ture/falseを別の表記方法で出力したい場合に便利です。
$IF(フィールドコードA)請求あり$DATE(日付)請求はありません フィールドコードAで指定した文字列が「請求あり」の場合、日付フィールドの日付を出力し、それ以外なら「請求はありません」と出力されます。
$IF(フィールドコードA)$("請求あり")$("請求があります")$("請求はありません") フィールドコードAで指定した文字列が「請求あり」の場合、「請求があります」と出力し、それ以外なら「請求はありません」と出力されます。 上の例と似ていますが、「条件の値」「一致した時の値」「一致しなかった時の値」のうち2つ以上を続けて固定文字列にしたい場合、$("~~")形式にする必要があります。

レコードの一覧に対して利用できるgusukuコマンドの仕様

gusukuコマンド 説明
$FOREACH および $END $FOREACHを記述した行から、$ENDを記述した行までを、選択されたレコード数分ループします。
ループの中では、各レコードのフィールドコードを指定したgusukuコマンドを記述することが可能です。

レコードの詳細に対して利用できるgusukuコマンドの仕様

gusukuコマンド 説明
$FOREACH(フィールドコード)
および $END
$FOREACHを記述した行から、$ENDを記述した行までをループします。
フィールドコードには、「テーブル」「関連レコード一覧」「添付ファイル」「文字列(複数行)」のフィールドコードを指定することが可能です。
ループの中ではテーブル内や関連レコードの参照しているアプリのフィールドコードを指定したgusukuコマンドや、後述の$または$IMGを指定することが可能です。
$IMG $FOREACHで添付ファイルのフィールドコードを指定した場合、ループの中に記述することが可能です。
PNG/JPEG/GIF/BMP形式の画像が添付されている場合、そのカラムに出力されます(画像本来のサイズを超えて拡大はしません)。
$EXTIMG $FOREACHで添付ファイルのフィールドコードを指定した場合、ループの中に記述することが可能です。
$IMGコマンド同様画像を出力しますが、こちらは画像本来のサイズを超えてカラムに合わせて拡大します。添付画像のサイズによっては、出力時に非常に荒い画像になりますのでご注意ください。
$(contentType)
$(fileKey)
$(name)
$(size)
$FOREACHで添付ファイルのフィールドコードを指定した場合、ループの中に記述することが可能です。
添付ファイルの各情報を出力することが可能です。
$ $FOREACHで文字列(複数行)のフィールドコードを指定した場合、ループの中に記述することが可能です。
指定のフィールドコードを改行で区切った1行の文字列が出力されます。

スライス:一部を取り出して出力する

FOREACHを使って、一部分だけ取り出して出力することが可能です。この機能をスライスと言います。

例: 1件目から10件目まで出力する。開始が0からであることに注意してください。

$FOREACH(フィールドコード)(0..9)

「..」の前後の数字は、省略することが可能で、省略すると「全て」の意味になります。
「5..」と指定すると、6行目から後ろ全てという指定になります。「..5」と指定すると、最初の6行という指定になります。

スライスできる対象

  • レコード
  • 関連レコード
  • テーブル
  • チェックボックス、複数選択
  • ユーザ選択、組織選択、グループ選択

また、改行を含む文字列の場合、1行1要素として指定可能です。

  • 文字列(複数行)
  • リッチエディター

FOREACH詳細

FOREACH可能なフィールドの直接指定

「添付ファイル」や「文字列(複数行)」などのフィールドは、FOREACHでループを記述する代わりに数値を直接指定することも可能です。

  • $(複数行フィールド名)(0)

と指定すると、複数行フィールド名の値を改行で区切った1行目を出力することが可能です。

$(..)

FOREACHでテーブル行や関連レコードを展開している場合、$(フィールドコード) で参照されるのはテーブルの列や関連レコードのフィールドと解釈されます。FOREACH 展開中は $(フィールドコード) で親レコードのフィールドを指定しても出力されません。

FOREACH内では $(..) で親レコードを参照できます。テーブル行や関連レコードの展開中の元レコードのフィールドを参照したい場合は次のように記載します。

$(..)(親レコードのフィールドコード)

FOREACHと連動するもの

以下の要素は$FOREACH~$ENDによる行の増減と連動して、位置や範囲が変わります。

  • 印刷範囲
  • 改ページ位置
  • Excelのテーブル

組織選択フィールドなどの出力

※グループ選択フィールド、ユーザー選択フィールドも同様となります。

組織選択フィールドを用いて選択された組織名を出力したい場合、以下のように記述します。「(name)」を記述しない場合にはコードが出力されます。

  • $(組織選択フィールドコード)(0)(name)

複数ある場合は数字の部分を増やしつつ、想定される個数を記述してください。

  • $(組織選択フィールドコード)(0)(name) $(組織選択フィールドコード)(1)(name)

制限事項

  • PDF出力時には、フォントをはじめいくつかの制限事項があります。
    詳細は「PDF出力時の制限事項」をご確認ください。

  • テンプレート内に配列数式がある場合、通常の数式に置き換わります。

  • テンプレート内で使用できる Excel 関数には制限があります。使用できる関数の一覧はこちらをご覧ください。

  • 関連レコード一覧は500レコードまで出力可能です。501レコード以上は出力できません。

  • シート名に「#」をつけてレコード毎にシートを出力する場合、元のシートのセル数は1万セル以内にする必要があります。

  • Microsoft Excel自体の制限 として、シートに含められる最大行数は1048576行(約100万行)です。100万行を超えるような大量のレコードを$FOREACHで展開すると、この制限によりエラーが発生します。

  • $FOREACH~$END内のセルにつけられたコメントは、展開後に削除されます。

関連記事