要素の仕様

要素(Element)は、帳票に表示されるテキスト、線、矩形などを定義するためのオブジェクトです。

各レンダラ(pdf,xls,xlsx,gdi...)には、要素レンダラというクラスが定義されています。 その名が示す通り、このクラスの役割は要素を描画することです。 要素レンダラは要素の種類毎に用意されていて、 例えば直線を描画するLineElementRendererや、文字列を描画するTextElementRendererなどがあります。

要素は必ず[type(種類)]というプロパティを持たなければいけません。 [type]の値によって、どの要素レンダラが利用されるかが決定されます。 各レンダラはSetting内にElementRendererMapという名前のハッシュを持っており、 ここに[type]値に対応するキーと、要素レンダラオブジェクトの組が格納されています。

要素レンダラを自作してElementRendererMapに登録すれば、 独自の要素を利用することができます。

共通のプロパティ

全ての要素はその[type]に関わりなく、以下のプロパティを持ちます。

type(種類)

[type]は文字列型のプロパティで、要素の種類を指定します。 このプロパティを省略することはできません。

デフォルトで指定可能な値を以下に示します。

caption(見出し)

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

このプロパティの値が、出力される帳票の内容に影響を与えることはありません。

id(識別子)

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

[caption(見出し)]が設定されていない場合は、識別子がレポートデザイナにおいてプロパティ表の項目見出しとして表示されます。

comment(コメント)

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

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

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

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が指定されていないと意味を持ちません

visibility_cond(表示条件)

[visibility_cond]は文字列型のプロパティで、要素を表示すべきかを判断するための式を指定します。 式についての詳しい説明は、「式の仕様」にあります。 このプロパティを省略するか、指定した式を評価した結果が真ならば要素は表示されます。

background(背景)

[background]はブール型のプロパティで、Trueを指定すると、 その要素は背景として描画されるようになります。 帳票が描画される際は、まず[background]が設定された要素が全て描画された後に、 残りの要素が描画されます。

customize(カスタマイズ)

[customize]はリスト型のプロパティで、 要素のプロパティを動的に書き換えるためのルールを示すオブジェクトを指定します。

リストの要素となるオブジェクトは、以下のプロパティを持ちます。

プロパティ 説明
property(プロパティ) 文字列 書き換えを行うプロパティの名前を指定します。
ネストしたプロパティは[.(ドット)]で繋いで指定します。
例えば、フォントのサイズを書き換えるならば以下のように指定します。
  font.size
cond(適用条件) 文字列(式) プロパティの書き換えを行うかどうかを制御する式を指定します。
ここで指定した式を評価した結果がtrueならばプロパティ値が書き換えられ、
falseならば書き換えは行われません。
常に書き換えを行うのであればtrueを指定してください。
exp(式) 文字列(式) 書き換える値を取得するための式を指定します。

※[customize]要素自身を動的に書き換えることはできません。

field(フィールド)

[field]は任意の式を評価して得た値を表示するための要素です。

exp(式)

[exp]は文字列型のプロパティで、表示する値を取得するための式を指定します。 式についての詳しい説明は、「式の仕様」にあります。

formatter(書式)

[formatter]には、[exp(式)]から得られたデータをどのような形式(カンマ編集,ゼロ埋め等) で表示するかを制御するためのオブジェクトを指定します。

実際に出力形式への変換を行うのは、テキストフォーマッタというオブジェクトです。 帳票が利用可能なテキストフォーマッタはSetting.TextFormatterMapというハッシュに登録されており、 どれを利用するかは[type(種類)]プロパティによって決められます。 さらに、選択されたテキストフォーマッタには実行時にformatterオブジェクトがパラメータとして渡されます。

テキストフォーマッタは自作して登録・利用することもできますが、 標準の実装が"default"というキーで登録されており、 以下のプロパティを受け取るようになっています。

プロパティ 説明
type(種類) 文字列型 テキストフォーマッタの種類を指定します
デフォルトの実装を利用するには"default"と指定します
format(書式文字列) 文字列 書式を指定します
以下の書式指定文字が利用できます
  # : 数値
  0 : 数値(ゼロ埋)
  , : 数値のカンマ
  . : 数値の少数点
  yyyy : 西暦年4桁
  yy : 西暦年2桁
  gg : 年号
  nn : 年号の年
  NN : 年号の年(1年を元年と表示する)
  MMMM : 月(英語表記)
  MMM : 月(英語略表記)
  MM : 月(ゼロ埋)
  M : 月
  dd : 日付(ゼロ埋)
  d : 日付
  dddd : 曜日(英語表記)
  ddd : 曜日(英語略表記)
  AAA : 曜日
  hh : 時間(ゼロ埋)
  h : 時間
  mm : 分(ゼロ埋)
  m : 分
  ss : 秒(ゼロ埋)
  s : 秒

halign(水平揃え)

[halign]は文字列型のプロパティで、水平方向のアライメントを指定します。

leftを指定すると左寄せ、rightを指定すると右寄せ、centerを指定すると中央寄せになります。 省略すると左寄せになります。

valign(垂直揃え)

[valign]は文字列型のプロパティで、垂直方向のアライメントを指定します。

topを指定すると上寄せ、bottomを指定すると下寄せ、centerを指定すると中央寄せになります。 省略すると上寄せになります。

color(色)

[color]は文字列型のプロパティで、文字の色を指定します。 RGB値を直接指定する方法と、色名を指定する方法の2種類の書き方があります。

RGB値を指定するには、先頭に#を付けたあとにR,G,Bの順でそれぞれ2桁ずつ16進数で指定します。 例えば#FF0000なら赤、#FF00FFなら紫、#888888ならグレーです。

色名を指定する場合は、HTMLで利用可能なものを書くことができます。 例えば、red, blue, grayなどです。

font(フォント)

[font]には、フォントを定義するオブジェクトを指定します。 省略すると、Report.fontに指定したフォントが利用されます。 このオブジェクトは、以下のプロパティを持ちます。

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

wrap(改行して全体を表示)

[wrap]はブール型のプロパティで、 Trueを指定すると表示内容が要素の範囲に収まりきらない場合、 改行して表示します。

distribute(均等割付)

[distribute]はブール型のプロパティで、Trueを指定すると文字が水平方向に均等割り付けされます。

vertical(縦書き)

[vertical]はブール型のプロパティで、Trueを指定すると縦書きになります。

decimal_place(小数点位置)

[decimal_place]は数値型のプロパティで、 小数点以下の桁数を指定すると、小数点位置を固定にすることができます。

このプロパティは、Excel(XLS/XLSX)形式では無効です。

shrink_to_fit(縮小して全体を表示)

[shrink_to_fit]はブール型のプロパティで、 Trueを指定すると表示内容が要素の範囲に収まりきらない場合、 自動的にフォントサイズを小さくして全体を表示します。

xls_format(Excel書式)

[xls_format]は文字列型のプロパティで、 Excel(XLS/XLSX)出力を行ったときに、セルに設定される書式文字列を指定します。

省略すると、値は常に[format(書式)]に基づいて文字列に変換された上でセルに設定されます。

rect(四角形)

[rect(四角形)]には背景として表示される四角形を定義するオブジェクトを指定します。

rect(四角形)要素と同じプロパティを持ったオブジェクトを指定することで、同じ場所に四角形が表示されます。

このプロパティを利用することで、背景色や枠線を表示できます。

text(テキスト)

[text]は静的な文字列を表示するための要素です。 後述する式埋め込みによって動的な値を表示することもできます。 [text]は[field(フィールド)]とほぼ同じ要素を持ちます。 異なるのは[exp(式)]の代わりに[text(テキスト)]というプロパティを持つという点です。

text(テキスト)

[text]には表示する文字列を指定します。 [text]内には#{}で囲むことによって式を埋め込むことができます。 例えばページ数を表示するならば以下のように書くと便利です。

 ページ: #{page_count} / #{page_count.total}

line(直線)

[line]は直線を描画するための要素です。 線は(x1, y1)から(x2, y2)に引かれます。

line_width(線太さ)

[line_width]は数値型のプロパティで、線の太さを指定します。 省略するとレポートの[line_width]に指定した値が利用されます。

line_style(線スタイル)

[line_style]は文字列型のプロパティで、線のスタイルを指定します。 指定可能な値はsolid(実線),dot(点線),dash(破線),dashdot(破線と点線)のいずれかです。 省略すると実線になります。

line_pattern(線パターン)

[line_pattern]は文字列型のプロパティで、点線のパターンを指定します。 パターンは偶数個の数値をカンマ区切りで指定します。 例えば、4,3,2,1と指定したならば、 4ptの線,3ptの空白,2ptの線,1ptの空白というパターンとなります。

このプロパティが設定されていた場合、[line_style(線スタイル)]は無効になります。

このプロパティは、Excel(XLS/XLSX)形式では無効です。

doublet(二重線)

[doublet]はブール型のプロパティで、trueを指定すると二重線になります。

color(色)

[color]は文字列型のプロパティで、線の色を指定します。

start_cap(始点スタイル), end_cap(終点スタイル)

[start_cap]と[end_cap]は文字列型のプロパティで、線の始端と終端のスタイルを指定します。 指定可能な値はflat, arrowのいずれかです。 省略するとflatになります。

rect(四角形)

[rect]は四角形を表示するための要素です。

line_width(枠線太さ)

[line_width]は数値型のプロパティで、四角形の枠線の太さを指定します。 省略すると線の太さは1になります。 また、0を指定すると枠線のない矩形とすることができます。

line_style(線スタイル)

[line_style]は文字列型のプロパティで、矩形の境界線のスタイルを指定します。 指定可能な値はsolid(実線),dot(点線),dash(破線),dashdot(破線と点線)のいずれかです。 省略すると実線になります。 [line_pattern(線パターン)]が指定されていると、この要素は無効になります。

line_pattern(線パターン)

line_patternは文字列型のプロパティで、矩形の境界線の点線パターンを指定します。 パターンは偶数個の数値をカンマ区切りで指定します。 例えば、4,3,2,1と指定したならば、 4ptの線,3ptの空白,2ptの線,1ptの空白というパターンとなります。

このプロパティが設定されていた場合、[line_style(枠線スタイル)]は無効になります。

このプロパティは、Excel(XLS/XLSX)形式では無効です。

color(枠線色)

[color]は文字列型のプロパティで、四角形の枠線の色を指定します。

fill_color(塗りつぶし色)

[fill_color]は文字列型のプロパティで、四角形の内部を塗りつぶす色を指定します。 省略すると塗りつぶしは行われません。

round(角の丸さ)

[round]は数値型のプロパティで、矩形の角を丸める大きさをポイント単位で指定します。 省略すると丸めは行われません。

このプロパティは、Excel(XLS/XLSX)形式では無効です。

hide_top(上枠線を隠す), hide_left(左枠線を隠す), hide_bottom(下枠線を隠す), hide_right(右枠線を隠す)

[hide_X]はブール型のプロパティで、矩形の各辺(top:上,bottom:下,left:左,right:右)を非表示にするかを指定します。

circle(円)

[circle]は円を表示するための要素です。

line_width(枠線太さ)

[line_width]は数値型のプロパティで、円周の線の太さを指定します。 省略すると線の太さは1になります。 また、0を指定すると円周の線を無くすことができます。

line_style(枠線スタイル)

[line_style]は文字列型のプロパティで、円周の線のスタイルを指定します。 指定可能な値はsolid(実線),dot(点線),dash(破線),dashdot(破線と点線)のいずれかです。 省略すると実線になります。 [line_pattern(枠線パターン)]が指定されていると、この要素は無効になります。

line_pattern(枠線パターン)

[line_pattern]は文字列型のプロパティで、円周の点線パターンを指定します。 パターンは偶数個の数値をカンマ区切りで指定します。 例えば、4,3,2,1と指定したならば、 4ptの線,3ptの空白,2ptの線,1ptの空白というパターンとなります。

このプロパティが設定されていた場合、[line_style(枠線スタイル)]は無効になります。

このプロパティは、Excel(XLS/XLSX)形式では無効です。

color(枠線色)

[color]は文字列型のプロパティで、円周の線の色を指定します。

fill_color(塗りつぶし色)

[fill_color]は文字列型のプロパティで、円の内部を塗りつぶす色を指定します。 省略すると塗りつぶしは行われません。

barcode(バーコード)

[barcode]はバーコードを表示するための要素です。

exp(式)

[exp]は文字列型の要素で、 バーコードとして表示する値を取得するための式を指定します。

formatter(書式)

[formatter]には値の表示形式を定義するオブジェクトを指定します。 [exp(式)]の値をフォーマットした結果の文字列がバーコード化されます。 主にゼロ埋めなどを行うために利用します。

barcode_type(バーコード種類)

[barcode_type]は文字列型のプロパティで、バーコードの種類を指定します。

指定可能な値はean13, ean8, code39, codabar, itf, code128, gs1_128, yubin, qrcodeのいずれかです。 省略するとean13になります。

gs1_128を利用する場合、アプリケーション識別子(AI)はカッコで囲みます。 このカッコはバーコードの内容には含まれませんが、ラベルには含まれます。 また、可変長項目の終わりを示すFNC1を入れる場合は'{1}'と指定します。 先頭のFNC1は指定しなくても自動的に付加されます。

  # データの例
  (01)14512345678903(17)061030(30)300{1}(10)001234

without_text(文字を非表示)

[without_text]はブール型のプロパティで、 trueを指定するとバーコード下の文字列が表示されなくなります。

generate_checksum(チェックサム生成)

[generate_checksum]はブール型のプロパティで、 チェックサムを生成して付加するかを指定します。 barcode_typeがcodabarまたはcode39の場合のみ有効です。 code39ならばモジュラス43、codabarならばモジュラス16で計算されます。

codabar_startstop_code(CODABARスタートストップ文字)

[codabar_startstop_code]は文字列型のプロパティで、 [barcode_type(バーコード種類)]がcodabarのときに付加されるスタート/ストップ文字を指定します。 指定可能な値は"A","B","C","D"です。 省略すると"A"となります。

codabar_startstop_show(CODABARスタートストップ文字表示)

[codabar_startstop_show]は文字列型のプロパティで、 [barcode_type(バーコード種類)]がcodabarのときに、スタート/ストップ文字をバーコード下のラベル文字列に含めるかを指定します。

gs1_conveni(GS1_128コンビニバーコード)

[gs1_conveni]はブール型のプロパティで、 [barcode_type(バーコード種類)]がgs1_128のときに、コンビニ料金代理収納バーコードかを指定します。

コンビニ料金代理収納バーコードを出力する場合は、 データの先頭が'(91)'から始まり、それ以降の部分は以下の内容になります。

内容 桁数
国コード下1桁+メーカーコード5桁 6
自由使用欄 21
再発行区分(再発行回数) 1
支払期限日(YYMMDD) 6
印紙フラグ(0:貼らない 1:貼る) 1
支払金額(円) 6
チェックディジット(モジュラス10)
※省略すると自動計算されます
1
  #データの例
  (91)91234512345678901234567890101307030003150

qr_charset(QRCODE文字セット)

[qr_charset]は文字列型のプロパティで、 [barcode_type(バーコード種類)]がqrcodeの場合に利用される文字セットを指定します。 デフォルト値は"shift_jis"です。

qr_correction_level(QRCODE誤り訂正レベル)

[qr_correction_level]は文字列型のプロパティで、 [barcode_type(バーコード種類)]がqrcodeの場合に利用される誤り訂正レベルを指定します。 指定可能な値は"L(誤り訂正率7%)","M(15%)","Q(25%)","H(30%)"で、デフォルト値は"M"です。

image(画像)

[image]は画像を表示するための要素です。

表示する画像を指定する方法は2つあります。 1つは[image(画像)]プロパティを使う方法で、静的な画像のみを表示できます。

もう1つはイメージローダを使うという方法で、動的に生成した画像を表示できます。 イメージローダの詳しい説明は「レンダラの仕様」にあります。

image(画像)

[image(画像)]は文字列型のプロパティで、表示する画像のデータをBase64エンコードして指定します。 イメージローダから画像が得られた場合、このプロパティは無視されます。

このプロパティ値はカスタマイザで編集することができません。 仮に編集したとしてもその内容は無視されます。 動的な画像を表示する場合はイメージローダを利用してください。

key(キー)

[key]は文字列型のプロパティで、利用するイメージローダを指定するためのキーを指定します。

exp(式)

[exp]は文字列型のプロパティで、イメージローダに渡されるパラメータの値を得るための式を指定します。

fit(サイズ調整)

[fit]はブール型のプロパティで、Trueを指定すると、 画像のサイズが要素のサイズよりも小さい場合に拡大して表示します。

このプロパティは、Excel(XLS/XLSX)形式では無効です。 Excel形式では画像は常に要素全体のサイズに合わせて表示されます。

halign(水平揃え)

[halign]は文字列型のプロパティで、水平方向のアライメントを指定します。

leftを指定すると左寄せ、rightを指定すると右寄せ、centerを指定すると中央寄せになります。 省略すると左寄せになります。

このプロパティは、Excel(XLS/XLSX)形式では無効です。 Excel形式では画像は常に要素全体のサイズに合わせて表示されます。

valign(垂直揃え)

[valign]は文字列型のプロパティで、垂直方向のアライメントを指定します。

topを指定すると上寄せ、bottomを指定すると下寄せ、centerを指定すると中央寄せになります。 省略すると上寄せになります。

このプロパティは、Excel(XLS/XLSX)形式では無効です。 Excel形式では画像は常に要素全体のサイズに合わせて表示されます。

subpage(サブページ)

[subpage]はページ内に他の帳票のページを表示するための要素です。 表示するページはあらかじめAddSubPageメソッドで帳票に設定しておく必要があります。

key(キー)

[key]は文字列型のプロパティで、AddSubPageメソッドに与えたキーを指定します。

exp(式)

[exp]は文字列型のプロパティで、 表示するページのインデックスを得るための式を指定します。