帳票定義ファイルの仕様

RapidReportでは、帳票定義はJSON形式のファイルで保存され、 実行時にはそれをデコードしたオブジェクトが生成されて利用されます。 この帳票定義オブジェクトは以下のオブジェクトからなるツリーであり、 それぞれが固有のプロパティを持っています。

レポートはツリーのトップレベルに必ず位置するオブジェクトです。 その他のオブジェクトは全てレポートの子孫として存在することになります。 レポートオブジェクトのプロパティには、用紙設定などの帳票全体にかかわる項目が定義されます。

レポートオブジェクトの下にはグループというオブジェクトが必ず存在します。 帳票に渡されたデータは、グループのプロパティに設定された条件に従って分割されます。 また、グループは後述するコンテントをどのように配置するかを指定するプロパティを持ちます。

グループオブジェクトの下には、コンテントというオブジェクトが必ず1つ以上存在します。 コンテントは帳票の具体的な表示内容を定義するオブジェクトです。 データを表示するためのフィールドや、罫線といった要素(Element)は、コンテントに属します。 要素の詳細については、「要素の仕様」を参照してください。 また、コンテントのプロパティには、 帳票上で割り当てられる領域のサイズや、コンテントをいつ表示するかを制御する条件などの項目があります。

コンテントは、必要に応じて1つの子グループを持つことができます。 子グループには、コンテントの親グループに割り当てられたデータが渡されて再び分割が行われます。 グループの下にはコンテントが存在するので、 この構造をいくつも繰り返すことで多階層グループを表現することができます。

それぞれのオブジェクトの詳細について説明します。 特に断りがない場合、全てのプロパティは省略可能です。

Report(レポート)

先ほども述べたとおり、レポートはツリーのトップレベルに必ず位置するオブジェクトです。

レポートは、以下のプロパティを持ちます。

caption(見出し)

[caption]は文字列型のプロパティで、レポートデザイナにおいて構成ツリーのノード見出しとして利用されます。

id(識別子)

[id]は文字列型のプロパティで、レポートの識別子を指定します。 レポートとグループの識別子はユニークである必要があります。 識別子は、帳票出力の実行時にプログラムから参照して利用することができます。

[caption(見出し)]が設定されていない場合は、識別子がレポートデザイナにおいて構成ツリーのノード見出しとして表示されます。

comment(コメント)

[comment]は文字列型のプロパティで、レポートのコメントを指定します。

コメントの内容は帳票の出力処理にはまったく影響しません。 デザイン作業のための覚え書きとして利用できます。

コメントの付けられたレポートには、レポートデザイナの構成ツリー上で赤いマークが表示されます。 また、レポートが選択されるとコメント内容がヘルプ欄に表示されます。

paper(用紙設定)

[paper]には帳票の用紙についての設定を行うためのオブジェクトを指定します。 このオブジェクトは以下のプロパティを持ちます。

プロパティ 説明
scale_unit(単位) 文字列 位置やサイズの単位を指定します
次の値のいずれかを指定可能です
point(ポイント 1pt = 0.353mm)
mm(ミリ)
inch(インチ 1in = 25.4mm, 1in = 72pt)
省略するとpointになります
type(用紙タイプ) 文字列 用紙の種類を指定します
次の値のいずれかを指定可能です
a3, a4, a5, b4, b5
省略するとa4になります
[size(カスタム用紙サイズ)]が同時に指定されている場合は
このプロパティは無視されます
landscape(横方向) ブール値 用紙を横向きにするかを指定します
size
(カスタム用紙サイズ)
オブジェクト [type(用紙タイプ)]に含まれていない種類の用紙を利用する場合に
その用紙サイズを指定します
このプロパティが設定されている場合、[type]は無視されます
以下のプロパティを持ちます
プロパティ 説明
width(幅) 数値 用紙の幅を指定します
height(高さ) 数値 用紙の高さを指定します
margin(余白) オブジェクト 用紙の余白を指定します
以下のプロパティを持ちます
プロパティ 説明
top(上端) 数値 上端余白を指定します
left(左端) 数値 左端余白を指定します
bottom(下端) 数値 下端余白を指定します
right(右端) 数値 右端余白を指定します
odd_reverse
(裏ページ左右反転)
ブール値 両面印刷の場合に裏となるページ
の左右端余白を入れ替えます

font(フォント)

[font]には、この帳票全体におけるデフォルトのフォントを定義するためのオブジェクトを指定します。 文字を表示する要素 (フィールド, テキスト) で各個の[font]設定を省略すると、ここで指定したフォントが利用されます。 このオブジェクトは以下のプロパティを持ちます。

プロパティ 説明
name(フォント名) 文字列 フォント名を表すキーを指定します
デフォルトではgothic(ゴシック),mincho(明朝)のいずれかを指定可能です
利用可能なフォントを追加する方法については「フォントについて」をご覧ください
省略するとgothicになります
size(フォントサイズ) 数値 フォントサイズを指定します
デフォルト値は10です
bold(太字) ブール値 太字にするかを指定します
italic(イタリック) ブール値 斜体にするかを指定します
underline(下線) ブール値 下線を引くかを指定します

line_width(線太さ)

[line_width]は数値型のプロパティで、帳票全体におけるデフォルトの線の太さを指定します。 線を描画する要素 (直線, 四角形, 円) で各個の[line_width]を省略すると、 ここで指定した線の太さが利用されます。

省略すると、デフォルトの線太さは1となります。

page_capacity(許容ウェイト)

[page_capacity]は数値型のプロパティで、1ページ内に含めることのできるコンテントのウエイト許容量を指定します。 例えば[page_capacity]の値を20とし、明細コンテントの[weight(ウェイト)]を1としておけば、 明細が20行表示される度に改ページするといったことができます。

このプロパティを省略した場合、ウエイトによる改ページは行われなくなります。

reset_page_count(ページ数リセット)

[reset_page_count]はブール型のプロパティです。 Trueを指定すると、レポートが開始するたびにページ数がリセットされるようになります。 (ページ数はデザイン内の式でpage_countメソッドから得ることができます)

このプロパティが意味を持つのは、複数の帳票を続けて出力する場合です。 例えば、以下のようにreportAの後にreportBを続けて出力するとします。

  // C#
  pages = reportA.GetPages();
  pages.AddRange(reportB.GetPages());
  ' VisualBasic
  pages = reportA.GetPages()
  pages.AddRange(reportB.GetPages())
  // Java
  pages = reportA.getPages();
  pages.addAll(reportB.getPages());

このとき、reportBで[reset_page_count]にTrueが指定されていたならば、 そこでページ数が1にリセットされます。

custom_fields(カスタム列)

[custom_field]には、動的に計算されるカスタム列を定義したオブジェクトのリストを設定します。 リストの要素となるオブジェクトは以下のプロパティを持ちます。

プロパティ 説明
key(列名) 変数のキー
exp(式) カスタム列の値を得るための式

カスタム列は、通常のデータ列と区別することなく利用することができます。

printer_name(プリンタ名)

[printer_name]は文字列型のプロパティで、デフォルトのプリンタ名を指定します。 このプロパティは、.NET版の直接印刷またはプレビュー機能を利用しているときにのみ意味を持ちます。

paper_name(用紙名)

[paper_name]は文字列型のプロパティで、デフォルトの用紙名を指定します。 このプロパティは、.NET版の直接印刷またはプレビュー機能を利用しているときにのみ意味を持ちます。

paper_source(用紙トレイ)

[paper_source]は文字列型のプロパティで、デフォルトの用紙トレイを指定します。 このプロパティは、.NET版の直接印刷またはプレビュー機能を利用しているときにのみ意味を持ちます。

group(グループ)

グループオブジェクトを指定します。 このプロパティは省略できません。

Group(グループ)

グループはレポートまたはコンテントに含まれるオブジェクトです。 冒頭で述べたとおり、グループの主な役割は渡されたデータを分割し、 帳票上で適切にそれを配置することです。

caption(見出し)

[caption]は文字列型のプロパティで、レポートデザイナにおいて構成ツリーのノード見出しとして利用されます。

id(識別子)

[id]は文字列型のプロパティで、グループの識別子を指定します。 レポートとグループの識別子はユニークである必要があります。 識別子は、帳票出力の実行時にプログラムから参照して利用することができます。

[caption(見出し)]が設定されていない場合は、識別子がレポートデザイナにおいて構成ツリーのノード見出しとして表示されます。

comment(コメント)

[comment]は文字列型のプロパティで、グループのコメントを指定します。

コメントの内容は帳票の出力処理にはまったく影響しません。 デザイン作業のための覚え書きとして利用できます。

コメントの付けられたグループには、レポートデザイナの構成ツリー上で赤いマークが表示されます。 また、グループが選択されるとコメント内容がヘルプ欄に表示されます。

keys(ブレーク条件キー)

[keys]はリスト型のプロパティで、 グループをブレーク(分割)するためのキーとなるデータ列名を指定します。

レポートデザイナ上で複数のキーを指定する場合は、カンマ区切りで書きます。

  KEY1, KEY2, KEY3

指定するのは列名であって式ではないことに注意してください。 例えば上記の例を以下のように書くのは間違いです。

  # 間違った例
  .KEY1, .KEY2, .KEY3

detail(明細)

[detail]はブール型のプロパティで、 Trueを指定するとデータ1行毎にグループがブレークするようになります。
この要素をTrueにすると、[keys(ブレーク条件キー)]は無視されます。

max_count(最大件数)

[max_count]は数値型のプロパティで、グループに属することのできるデータ行数の最大値を指定します。

[keys(ブレーク条件キー)],[detail(明細)],[max_count]を全て省略すると、ブレークしないグループになります。

blank_data(空データ割当)

[blank_data]はブール型のプロパティです。 Trueを指定すると、グループに空データが割り当てられます。 空データの割り当てられたグループの内容は、そのままでは表示されなくなります。

[layout(配置)][blank(空行を出力)]プロパティと組み合わせて指定することによって、 親コンテントに余白がある場合にのみ、その余白を埋めるようにグループの内容を表示することができます。

page_break(改ページ)

[page_break]はブール型のプロパティです。 Trueを指定すると、グループがブレークするたびに改ページが行われるようになります。

reset_page_count(ページ数リセット)

[reset_page_count]はブール型のプロパティです。 Trueを指定すると、グループがブレークするたびにページ数がリセットされるようになります。

sort_keys(ソートキー)

[sort_keys]はリスト型のプロパティで、 割り当てられたデータをソートするためのキーとなるデータ列名を指定します。 省略すると、ソートは行われません。

crosstab(クロス集計表)

[crosstab]は文字列型のプロパティで、 このグループをクロス集計表のパーツとして構成するための設定を行います。

※クロス集計表を作成する場合は、このプロパティを手動で直接設定するのではなく、 レポートデザイナの「クロス集計表を追加」機能から自動生成することをお勧めします。

このプロパティには、以下のいずれかの値を設定可能です。

説明
none
(デフォルト値)
特別な制御を行いません
root クロス集計表のルートとして扱われます
caption クロス集計表の見出し行として扱われます
上位に root が設定されたグループが存在する必要があります
vdetail クロス集計表の縦方向の明細行として扱われます
上位に root が設定されたグループが存在する必要があります
さらに、[keys(ブレーク条件キー)]、[layout(配置).max_count(並べる最大数)]が指定されている必要があります
hdetail クロス集計表の縦方向の明細行として扱われます
上位に vdetail が設定されたグループが存在する必要があります
さらに、[keys(ブレーク条件キー)]、[layout(配置).max_count(並べる最大数)]が指定されている必要があります
summary クロス集計表の集計行として扱われます
上位に root が設定されたグループが存在する必要があります

split_string(文字列行分割)

[split_string]には、文字列行分割を行うための設定項目を含んだオブジェクトを設定します。 文字列行分割とは、このグループに渡された文字列型データを、 改行位置または指定した幅で分割し、その結果を割り当てた子グループを生成する機能です。 この機能を活用することで、文字列全体を出力するために必要な行の数だけグループを繰り返すことができ、 親コンテントのサイズを可変にすることができます。

このオブジェクトは、以下のプロパティを持ちます。

プロパティ 説明
key(列名) 数値 分割した文字列を参照する列名となるキーを指定します。
exp(式) 文字列 分割する文字列を得る式を指定します。
省略した場合は、キーの先頭にドット(.)を付けた式が評価されます。
例えば、キーに TEXT と指定した場合は
.TEXT
と指定したのと同じ効果となります。
width(幅) 数値 文字列を分割する幅を指定します。
文字幅は 半角文字:1 全角文字:2 とカウントされます。
文字列は、ここで指定した幅を超えるか、改行が出現するたびに分割されます。

例: width=10 の場合
---------------------------入力文字列
開発者のための
帳票ツール
---------------------------分割結果
> 開発者のた
> めの
> 帳票ツール

省略した場合は、改行位置でのみ分割されます。
break_rule
(改行ルール)
ブール値 文字列を分割する際に、改行ルールを有効にするかを指定します。
改行ルールを有効にすると、単語(半角)の途中、句読点の直前、開きカッコの直後、
閉じカッコの直前等での分割ができるだけ避けられます。

例: width=10、break_rule=trueの場合
---------------------------入力文字列
1234567890
ABCDE ABCDEFG
あいうえお。
あいうえ「お」
「あいうえ」お
---------------------------分割結果
> 1234567890
> ABCDE
> ABCDEFG
> あいうえ
> お。
> あいうえ
> 「お」
> 「あいう
> え」お

layout(配置)

[layout]には、グループをどのように配置すべきかを指定するオブジェクトを指定します。 このオブジェクトは以下のプロパティを持ちます。

プロパティ 説明
x 数値 グループの左端位置を指定します
y 数値 グループの上端位置を指定します
size(サイズ) 数値 グループの幅を指定します
[direction(並べる向き)]が[horizontal(横方向)]ならば、グループの高さを指定します
direction(並べる向き) 文字列 グループを並べる向きを指定します
以下の値のいずれかを指定できます
vertical : 縦方向
horizontal : 横方向
max_count(並べる最大数) 整数 1ページ内に表示することのできるグループの最大数を指定します
グループの数が[max_count]を超えた場合は改ページが行われます
省略するとグループの数による改ページは行われなくなります
max_count_exp
(並べる最大数_式)
文字列 1ページ内に表示することのできるグループの最大数を動的に計算する式を指定します
省略すると[max_count]の値が採用されます
blank(空行を出力) ブール値 データが存在しなかったとしても空のグループを表示するかを指定します
clip_overflow
(溢れた内容を切捨)
ブール値 ページ内にグループが収まらない場合でも改ページせずに、
溢れた内容を切り捨てるかを指定します
このプロパティは、[max_count]または[locates]プロパティが
同時に設定されている場合のみ有効です
locates(絶対座標配置) リスト グループを配置する位置をリストで指定します
このプロパティを指定すると[x][y][direction][max_count]は無効になります
リストの要素は以下のプロパティを持ったオブジェクトとなります
プロパティ 説明
x 数値 グループを配置する位置のx座標を指定します
y 数値 グループを配置する位置のy座標を指定します
count 数値 この位置にグループをいくつ並べて配置するかを指定します
省略すると、この位置には1つだけグループが配置されます

custom_fields(カスタム列)

[custom_fields]には、動的に計算されるデータ列を定義したオブジェクトのリストを設定します。 レポートの[custom_fields]プロパティと設定方法は同じです。

alternative_content(コンテント切替)

[alternative_content]はブール型のプロパティです。 Trueにすると、レポートデザイナ上でグループに属するコンテントのうち、 選択中のものだけが表示されるようになります。 コンテントが多すぎてデザイン作業中に画面からはみ出してしまう場合などに利用します。

このプロパティの値はレポートデザイナに対してのみ影響します。 実際にプログラムから帳票を出力する際の動作には全く影響しません。

contents(コンテンツ)

コンテントのリストを指定します。このプロパティは省略できません。 また、リストには少なくとも1つのコンテントが含まれている必要があります。

Content(コンテント)

コンテントは帳票に表示される内容を定義するためのオブジェクトです。 コンテントは、グループに含まれます。

caption(見出し)

[caption]は文字列型のプロパティで、レポートデザイナにおいて構成ツリーのノード見出しとして利用されます。

id(識別子)

[id]は文字列型のプロパティで、コンテントの識別子を指定します。 識別子は、帳票出力の実行時にプログラムから参照して利用することができます。

[caption(見出し)]が設定されていない場合は、識別子がレポートデザイナにおいて構成ツリーのノード見出しとして表示されます。

comment(コメント)

[comment]は文字列型のプロパティで、コンテントのコメントを指定します。

コメントの内容は帳票の出力処理にはまったく影響しません。 デザイン作業のための覚え書きとして利用できます。

コメントの付けられたコンテントには、レポートデザイナの構成ツリー上で赤いマークが表示されます。 また、コンテントが選択されるとコメント内容がヘルプ欄に表示されます。

size(サイズ)

コンテントの高さを設定するオブジェクトを指定します。

親グループの[layout(配置)]>[direction(並べる向き)]が[horizontal(横方向)]ならば、コンテントの幅を指定するオブジェクトを指定します。

プロパティ 説明
initial(初期) 数値 コンテントのサイズの初期値を指定します
省略すると0になります
initial_exp(初期_式) 文字列 コンテントのサイズの、初期値を動的に計算する式を指定します
省略すると[initial]の値が採用されます。
max(最大) 数値 コンテントのサイズの最大値を指定します
コンテントはグループを持っていた場合、
その内容に応じてサイズが拡張されますが、
ここで指定した値をを超えて拡張されることはありません
省略すると、親コンテントが存在するならばそのサイズの最大値が引き継がれ、
存在しなければ余白を除いた用紙サイズが最大値となります
max_exp(最大_式) 文字列 コンテントのサイズの、最大値を動的に計算する式を指定します
省略すると[max]の値が採用されます。
rev_initial (初期逆向指定) ブール値 [initial(初期)]をページの下端または右端を基準とした値とするかを指定します
このプロパティは[初期]が指定されていないと意味を持ちません
rev_max(最大逆向指定) ブール値 [max(最大)]をページの下端または右端を基準とした値とするかを指定します
このプロパティは[最大]が指定されていないと意味を持ちません
not_extendable(拡張しない) ブール値 Trueを指定すると、コンテントが初期のサイズから拡張されなくなります

グループのサイズとコンテントのサイズは、 グループの[layout(配置)]>[direction(並べる向き)]に応じて次のように意味が変わります。

[direction]が[vertical(縦方向)]ならばグループのサイズは幅、 コンテントのサイズは高さを意味します。

[direction]が[horizontal(横方向)]ならばグループのサイズは高さ、 コンテントのサイズは幅を意味します。

layout(配置) ※サブコンテントのみ

[layout]はサブコンテントにのみ設定可能なプロパティです。 サブコンテントが、メインとなるコンテント内にどのように配置されるかを示すオブジェクトを指定します。 このオブジェクトは以下のプロパティを持ちます。

プロパティ 説明
x1 数値 サブコンテントの左端座標を指定します
y1 数値 サブコンテントの上端座標を指定します
x2 数値 サブコンテントの右端座標を指定します
省略するとメインコンテントの右端になります
y2 数値 サブコンテントの下端座標を指定します
省略するとメインコンテントの下端になります
rev_x1(x1逆向指定) ブール値 x1をメインコンテントの右端を基準とした値とするかを指定します
このプロパティはx1が指定されていないと意味を持ちません
rev_y1(y1逆向指定) ブール値 y1をメインコンテントの下端を基準とした値とするかを指定します
このプロパティはy1が指定されていないと意味を持ちません
rev_x2(x2逆向指定) ブール値 x2をメインコンテントの右端を基準とした値とするかを指定します
このプロパティはx2が指定されていないと意味を持ちません
rev_y2(y2逆向指定) ブール値 y2をメインコンテントの下端を基準とした値とするかを指定します
このプロパティはy2が指定されていないと意味を持ちません

every_page(毎ページ表示)

[every_page]はブール型のプロパティで、コンテントを改ページするたびに毎回表示するかを指定します。

every_page_blank_group(毎ページ空グループ)

[every_page_blank_group]はブール型のプロパティで、コンテントが[every_page]によって表示された場合、 子グループに空のデータを割り当てるかを指定します。

existence_cond(生成条件)

[existence_cond]は文字列型のプロパティで、コンテントの生成条件を表す式を指定します。

ここで指定した式を評価した結果がtrueならばコンテントは生成され、falseならば生成されません。省略した場合は常に生成されます。

[visibility_cond(表示条件)]プロパティと機能が似ていますが、このプロパティを利用する方が、 コンテントの生成自体を行うかどうかを制御するために、帳票の出力処理が高速になります。

ただし[existence_cond]では、[visibility_cond]に比べて利用できるメソッドの種類に制限があります。 詳しくはを参照してください。

visibility_cond(表示条件)

[visibility_cond]は文字列型のプロパティで、コンテントの表示条件を表す式を指定します。

ここで指定した式を評価した結果がtrueならばコンテントは表示され、falseならば表示されません。省略した場合は常に表示されます。

[existence_cond(生成条件)]プロパティと機能が似ていますが、 このプロパティではコンテントの生成は常に行った上で、表示するかどうかのみを制御します。 表示されないコンテントが大量に存在すると、帳票の改ページ処理(GetPages関数)の実行に時間がかかる場合があります。 その場合は[existence_cond]プロパティの利用を検討して下さい。

ただし[existence_cond]では、[visibility_cond]に比べて利用できるメソッドの種類に制限があります。 詳しくはを参照してください。

aggregate_src(集計対象)

[aggregate_src]はブール型のプロパティで、このコンテントがXX_at,XX_pageメソッドの集計対象かを指定します。 同じグループに属するコンテントのうち、1つだけが集計対象となることができます。

集計対象コンテントが同じレベルに存在しない場合、XX_at,XX_page系のメソッドは利用できません。

unbreakable(改ページ禁止)

[unbreakable]はブール型のプロパティで、 Trueを指定すると、このコンテントの直後で改ページされなくなります。 このプロパティによって、ヘッダの直後やヘッダの直前、 またはグループの途中で改ページされることを防ぐことができます。

以下の構造を持った帳票を例として、具体的に説明します。 この中にはheader,body,footerそしてdetailという4つのコンテントが存在します。

headerの[unbreakable]をTrueに設定すると、headerの直後(bodyの直前)で改ページすることを防げます。

bodyの[unbreakable]をTrueに設定すると、bodyの直後(footerの直前)で改ページすることを防げます。 なお、この指定だけではbodyの途中での改ページを防ぐことはできません。

detailの[unbreakable]をTrueに設定すると、bodyの途中で改ページすることを防げます。 なお、この指定だけではbodyの直後(footerの直前)での改ページを防ぐことはできません。

bodyの途中とbodyの直後(footerの直前)での改ページをともに防ぐには、 body, detailの両方で[unbreakable]をTrueに設定する必要があります。

header, body, detailの全てで[unbreakable]をTrueに設定すると、 グループの途中で改ページすることを防げます。

weight(ウェイト)

[weight]は整数型のプロパティで、レポートの[page_capacity(許容ウェイト)]とともに利用されます。 詳しくは[page_capacity]の説明を参照してください。

variables(変数)

[variables]には、このコンテントに含まれる要素から利用可能な変数を定義したオブジェクトのリストを設定します。 リストの要素となるオブジェクトは以下のプロパティを持ちます。

キー 説明
key(変数名) 変数名を表すキー
exp(式) 変数値を得るための式

変数は var.[変数名] という式で参照することができます。 変数の値はコンテントが出力される際に計算されるため、[カスタム列]等では利用できないメソッドも利用することができます。

merge_content_id(差込コンテントID)

このコンテントに差し込む、共有コンテントのIDを指定します。

elements(要素)

このコンテントに含まれる要素のリストを指定します。

group(グループ)

グループオブジェクトを指定します。

sub(サブコンテント)

このコンテントに含まれるサブコンテントのリストを指定します。 サブコンテントは、親コンテントの上に重ねて表示されるコンテントです。

通常のコンテントと同様に、サブコンテントもグループを持つことができますが、 そのグループは改ページの判断に利用されることはありません。

1つのコンテントには複数のサブコンテントを含めることができるので、 例えばそれぞれに個別の[visibility_cond(表示条件)]を設定しておくことで、 表示される内容を動的に切り替えることができます。