Pro エディション

Chart — 詳細リファレンス

概要

このページは、NextPDF Pro Chart モジュールの契約レベルのリファレンスです。サーフェスは NextPDF\Pro\Chart にある 5 つの公開クラス、すなわち BarChart・LineChart・PieChart の各レンダラー、ChartBox 配置矩形、そして ChartColor 値オブジェクトです。各レンダラーは描画プリミティブです。静的ファクトリーがそれを生成し、フルエントな with*() 呼び出しがそれを構成し、render(ChartBox $box): string が供給された矩形に対する PDF コンテンツストリーム演算子を返します。出力はベクターのみで決定的です。同一の入力と構成は同一のバイト列を生成します。退化した入力は例外をスローするのではなく空の文字列を返すため、チャートが周囲のページを壊すことは決してありません。タスク指向のビューはケーパビリティページにあります。

提供状況とライセンス

このケーパビリティは NextPDF Pro（nextpdf/pro）で提供され、Pro ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントのないデプロイメントは、ケーパビリティのクラスをロードしません。エディションを比較してライセンスを取得。

Chart レンダラーは、chart.* ケーパビリティファミリーの下でケーパビリティライセンスされます。ケーパビリティのライセンスがない場合、Chart レンダラーは利用できません。

公開 API サーフェス

composer require nextpdf/pro:^3

シンボル	パラメーター	デフォルトの挙動	戻り値	スロー/失敗条件	注記
`BarChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	値は float にキャスト	`self`	スローしない	唯一の生成経路。コンストラクターは private
`BarChart::withBarColor()`	`ChartColor $color`	棒の塗り。デフォルトはパレットのエントリー 0	`self`	スローしない	フルエント。レシーバーを変更
`BarChart::withAxisColor()`	`ChartColor $color`	軸のストローク。デフォルト `#333333`	`self`	スローしない	—
`BarChart::withBarGap()`	`float $gap`	スロット幅に対する割合としての間隔。デフォルト `0.2`	`self`	スローしない	`0.0`–`0.9` にクランプ。範囲外の入力は拒否ではなくクランプ
`BarChart::withFontSize()`	`float $size`	ラベルのフォントサイズ（ポイント単位）。デフォルト `7.0`	`self`	スローしない	—
`BarChart::render()`	`ChartBox $box`	軸、棒、カテゴリーラベル、5 つの値目盛り	`string` 演算子	スローしない。空データは `''` を返す	非正の最大値は `1.0` に対してスケーリング
`LineChart::create()`	`list<string> $labels`	系列のないチャート	`self`	スローしない	コンストラクターは private
`LineChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	名前のない系列を 1 つ追加	`self`	スローしない	単一系列の簡便メソッド
`LineChart::addSeries()`	`string $name`, `list<int\|float> $values`, `?ChartColor $color = null`	`null` の色は系列インデックスによってパレットから自動割り当て	`self`	スローしない	系列名は凡例用に予約
`LineChart::withAxisColor()`	`ChartColor $color`	軸のストローク。デフォルト `#333333`	`self`	スローしない	—
`LineChart::withLineWidth()`	`float $width`	系列のストローク幅。デフォルト `1.5`	`self`	スローしない	—
`LineChart::withFontSize()`	`float $size`	ラベルのフォントサイズ。デフォルト `7.0`	`self`	スローしない	—
`LineChart::withDots()`	`bool $show`, `float $radius = 2.5`	データポイントのマーカー。デフォルトで有効	`self`	スローしない	マーカーはベジェ近似の円として描画
`LineChart::withGrid()`	`bool $show`	水平の四分位グリッド。デフォルトで有効	`self`	スローしない	—
`LineChart::render()`	`ChartBox $box`	グリッド、軸、系列ごとに 1 本の経路、ラベル	`string` 演算子	スローしない。系列がなければ `''` を返す	2 点未満の系列は経路を描画しない
`PieChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	値の合計から比率を計算	`self`	スローしない	コンストラクターは private
`PieChart::withColors()`	`list<ChartColor> $colors`	スライスごとに 1 色、順番どおり	`self`	スローしない	欠けたエントリーはパレットにフォールバック
`PieChart::withStrokeColor()`	`ChartColor $color`	スライスの輪郭。デフォルトは白	`self`	スローしない	—
`PieChart::withFontSize()`	`float $size`	ラベルのフォントサイズ。デフォルト `7.0`	`self`	スローしない	—
`PieChart::withPercentages()`	`bool $show`	パーセンテージラベル。デフォルトで有効	`self`	スローしない	ラベルは 15 度を超えて広がるスライスにのみ描画
`PieChart::withLegend()`	`bool $show`	右側の凡例。デフォルトで有効	`self`	スローしない	凡例はボックス幅を 80 ポイント予約
`PieChart::render()`	`ChartBox $box`	扇形、オプションのラベル、オプションの凡例	`string` 演算子	スローしない。空データまたはゼロ以下の合計は `''` を返す	円弧は最大 90 度のベジェセグメントに分割
`ChartBox::__construct()`	`float $x`, `float $y`, `float $width`, `float $height`	PDF の左下原点、ポイント単位	—	スローしない	`final readonly`。寸法は検証されない
`ChartBox::fromUserSpace()`	`float $x`, `float $y`, `float $width`, `float $height`, `float $pageHeight`	左上原点の矩形を PDF 座標に反転	`self`	スローしない	—
`ChartBox::right()`	なし	`x + width`	`float`	スローしない	プロパティではなくメソッド
`ChartBox::top()`	なし	`y + height`	`float`	スローしない	プロパティではなくメソッド
`ChartBox::inset()`	`float $left`, `float $bottom`, `float $right`, `float $top`	指定のインセットで縮小したサブボックス	`self`	スローしない	過大なインセットは負の寸法を生成。検証されない
`ChartColor::__construct()`	`float $r`, `float $g`, `float $b`, 各 `0.0`–`1.0`	—	—	スローしない	`final readonly`。成分はクランプされない
`ChartColor::rgb()`	`int $r`, `int $g`, `int $b`, 各 `0`–`255`	成分を `0.0`–`1.0` にスケーリング	`self`	スローしない	—
`ChartColor::hex()`	`string $hex`	`#` 接頭辞付きまたは素の 6 桁 16 進数を受け付ける	`self`	スローしない	末尾の欠けた桁はゼロとしてデコード
`ChartColor::palette()`	`int $index`	組み込みの 12 色パレット	`self`	負のインデックスで `TypeError`	非負のインデックスは 12 を法として循環
`ChartColor::strokeOperator()`	なし	ストローク色演算子（`RG`）、小数 3 桁	`string`	スローしない	プロパティではなくメソッド
`ChartColor::fillOperator()`	なし	塗り色演算子（`rg`）、小数 3 桁	`string`	スローしない	プロパティではなくメソッド

エントリーポイントのシグネチャ

public static function fromData(array $labels, array $values): self
public function withBarColor(ChartColor $color): self
public function withAxisColor(ChartColor $color): self
public function withBarGap(float $gap): self
public function withFontSize(float $size): self
public function render(ChartBox $box): string

public static function create(array $labels): self
public static function fromData(array $labels, array $values): self
public function addSeries(string $name, array $values, ?ChartColor $color = null): self
public function withAxisColor(ChartColor $color): self
public function withLineWidth(float $width): self
public function withFontSize(float $size): self
public function withDots(bool $show, float $radius = 2.5): self
public function withGrid(bool $show): self
public function render(ChartBox $box): string

public static function fromData(array $labels, array $values): self
public function withColors(array $colors): self
public function withStrokeColor(ChartColor $color): self
public function withFontSize(float $size): self
public function withPercentages(bool $show): self
public function withLegend(bool $show): self
public function render(ChartBox $box): string

public function __construct(
    public float $x,
    public float $y,
    public float $width,
    public float $height,
)

public static function fromUserSpace(
    float $x,
    float $y,
    float $width,
    float $height,
    float $pageHeight,
): self

public function right(): float
public function top(): float
public function inset(float $left, float $bottom, float $right, float $top): self

public static function rgb(int $r, int $g, int $b): self
public static function hex(string $hex): self
public static function palette(int $index): self
public function strokeOperator(): string
public function fillOperator(): string

挙動契約

共通のレンダラー形状

3 つのレンダラーはすべて 1 つのライフサイクルに従います。静的ファクトリー、フルエントな構成、1 回の render() 呼び出しです。構成メソッドはレシーバーを変更してそれを返します。レンダラーは不変の値オブジェクトではありません。render() は構成を変更せずに読み取るため、構成済みの 1 つのレンダラーを複数のボックスにレンダリングできます。すべてのレンダリングは、その出力を save/restore のグラフィックスステートペアで包むため、チャートの状態がページに漏れることは決してありません。座標は小数 2 桁、色成分は小数 3 桁で出力され、これにより出力はバイト安定に保たれます。テキストは、構成されたサイズで /ChartFont フォントリソース名を通じてレンダリングされます。呼び出し元は、対象ページのリソース辞書にその名前でフォントを登録します。ラベル文字列は、文字列オペランドに入る前にバックスラッシュと括弧をエスケープします。レンダラーは、リフロー、クリッピング、コンテナのネゴシエーションを一切行いません。配置は呼び出し元が所有します。

スケーリングとレイアウト

棒グラフと折れ線グラフは、ボックス内に固定のプロットインセットを予約します。左 40 ポイント、下 20、右 10、上 10 です。残りのプロット領域は、系列の最大値に対して値を線形にスケーリングします。ゼロ以下の最大値は代わりに 1.0 に対してスケーリングされるため、すべてゼロのデータはゼロ除算ではなく平坦な内容で軸をレンダリングします。両者とも X 軸と Y 軸を 0.5 ポイント幅で、5 つの値目盛りを四分位位置に描画します。棒グラフは、1,000 および 1,000,000 を超える目盛り値を K および M の接尾辞で整形します。折れ線グラフはそのままの数値を表示します。

棒グラフ

各値はプロット幅にわたって等しいスロットを占めます。棒は、構成された間隔の割合を差し引いたスロットを塗り、スロット内で中央に配置されます。カテゴリーラベルはプロット領域の 12 ポイント下に描画されます。

折れ線グラフ

グリッドは、有効な場合、軸と系列の下に薄い灰色（0.85 0.85 0.85 RG）で 4 本の水平な四分位線を描画します。各系列は、その点を通る 1 本の折れ線を、プロット幅全体にわたって描画します。オプションのマーカーは、各データポイントに 4 セグメントのベジェ円として描画されます。系列の色は、挿入順に連続するパレットエントリーをデフォルトとします。

円グラフ

スライスはデータ順にレイアウトされ、正の X 軸から始まり反時計回りに広がります。各扇形の経路は閉じ、塗りとストロークを組み合わせて（h B）描画されます。円弧は最大 90 度のベジェセグメントに分割されます。パーセンテージラベルは整数パーセントに丸められ、15 度を超えて広がるスライスにのみ描画されます。凡例は、有効な場合、右側にボックス幅を 80 ポイント予約し、エントリーごとに 8 ポイントのスウォッチを 12 ポイントの行高で描画します。半径は、残りの幅とボックス高さのうち小さい方の半分から、10 ポイントのマージンを引いた値です。

配置と色の値オブジェクト

ChartBox は、左下原点を持つ PDF ユーザー単位（ポイント）の不変の矩形です。ChartBox::fromUserSpace() は、供給されたページ高さに対して反転することで、左上原点の矩形を変換します。inset() は新しいより小さなボックスを返します。right() と top() はアクセサーメソッドです。ChartColor は自己完結型で、Core の色クラスには依存しません。その 12 エントリーのパレットは、呼び出し元が色を指定しない場合に系列とスライスの色を割り当てます。

サポートマトリックス（エビデンスに基づく）

チャートタイプまたは機能が Verified を獲得するのは、pro/tests/** のフィクスチャがそれを行使する場合のみです。チャートを統べる外部標準はないため、エビデンスはユニットレベルの挙動カバレッジです。

チャートタイプ / 機能	ステータス	エビデンス（テストパス）	確度	注記
棒グラフ — レンダリング、軸、棒の矩形、間隔のクランプ、空/すべてゼロのデータ、K/M 値の整形	Verified	`pro/tests/Unit/Chart/BarChartTest.php`; `BarChartArithmeticCoverageTest.php`; `BarChartBoundaryCoverageTest.php`	high	グラフィックスステートのラップ、軸線、棒の高さの比率、目盛り数、整形の境界を表明。
折れ線グラフ — 単一および複数系列、線の経路、軸、ドット、グリッド、単一点	Verified	`pro/tests/Unit/Chart/LineChartTest.php`; `LineChartCoverageTest.php`; `LineChartArithmeticCoverageTest.php`; `LineChartTypeCastCoverageTest.php`	high	複数系列、単一点の線なし、空系列、グリッドとドットの経路をカバー。
円グラフ — 扇形、ベジェ分割、パーセンテージ、凡例、ゼロ/負の合計	Verified	`pro/tests/Unit/Chart/PieChartTest.php`; `PieChartArithmeticCoverageTest.php`; `PieChartBoundaryCoverageTest.php`	high	扇形の経路、広がりごとのセグメント数、15 度のラベル閾値、凡例のジオメトリ、空文字列の挙動をカバー。
`ChartBox` — 座標変換（ユーザー空間から PDF へ）、ページ上端/下端、ゼロ寸法、インセット	Verified	`pro/tests/Unit/Chart/ChartBoxTest.php`	high	ページ上端、下端、ゼロ寸法の端での、左上原点から左下原点への変換。
`ChartColor` — RGB スケーリング、16 進数の解析、パレット、ストローク/塗り演算子	Verified	`pro/tests/Unit/Chart/ChartColorTest.php`	high	0–255 から 0–1 のスケーリング、`#` 接頭辞付きおよび素の 16 進数、大文字小文字混在、12 エントリー後のパレット循環。
レンダラー横断の回帰堅牢化	Verified	`pro/tests/Unit/Chart/ChartCoverageTest.php`	high	3 つのレンダラーにわたる共有の回帰スイートと、値整形の算術。
棒/折れ線/円以外のチャートタイプ（面、散布図、積み上げ、ドーナツなど）	Not supported	—	high	レンダラーは出荷されていません。モジュールのサーフェスはちょうど棒、折れ線、円です。誠実に述べると、これは「あらゆるチャートタイプ」ではありません。

誠実なカウント：Verified 6 行、Claimed 0、Not supported 1（棒、折れ線、円以外のあらゆるチャートタイプ）。

エッジケースと失敗モード

どのレンダラーもデータに対して例外をスローしません。退化した入力は空の文字列に縮退します。空の棒または折れ線データ、空の系列リスト、ゼロ以下の円グラフ合計はいずれも '' を返します。
2 点未満の折れ線系列は、経路もマーカーも描画しません。軸とラベルは依然としてレンダリングされます。
負の棒の値は拒否されません。棒の矩形は X 軸の下に伸びます。
ラベル数と値の数は相互検証されません。呼び出し元が一致する長さのリストを供給します。
ゼロまたは負の寸法を持つ ChartBox は受け付けられ、退化した出力を生成します。呼び出し元がボックスのサイズを指定する必要があります。
レンダラーはクリッピングを行いません。サイズが大きすぎるチャート、そのプロット下のカテゴリーラベル、または長い凡例は、意図したページ領域からあふれる可能性があります。
チャートフォントリソース名でフォントを欠くページは、未定義のリソースを参照するテキスト演算子を残します。その場合のビューアーの挙動は未定義です。
ChartColor::hex() は検証を一切行いません。6 桁未満の入力は、欠けた成分をゼロとしてデコードします。ChartColor::palette() は負のインデックスで TypeError により失敗します。PHP の負の剰余がパレットキーを解決しないためです。
モジュールは暗号処理を一切行いません。FIPS モードにチャート固有の挙動はありません。

適合性

Chart モジュールは PDF コンテンツストリーム演算子を出力します。その出力を統べる外部のチャート、シンボロジー、または暗号標準はないため、唯一の適合性サーフェスは出力される演算子ストリームです。

主張	標準	節
出力されるグラフィックスはコンテンツストリーム演算子モデルに従う。出力は保存・復元されたグラフィックスステート内にネストする。	ISO 32000-2	§8.1
棒、線、扇形、マーカーは経路オブジェクトである。構築は `m` または `re` で始まり、経路描画演算子で終わる。	ISO 32000-2	§8.5.2
ラベルはテキストオブジェクトとしてレンダリングされる。位置は `BT` の後に確立され、グリフは `Tj` テキスト表示演算子で描画される。	ISO 32000-2	§9.2.2, §9.4.3

すべての節はパラフレーズされています。このページは規範的なテキストを一切再現しません。これらはケーパビリティの記述であり、認証ではありません。NextPDF はいかなる認証も保持せず、いかなる認証も付与しません。ストリームの正しいレンダリングは、それを包含するドキュメントが整形式であることにも依存します。これはドキュメント作成者の責任です。

開発ノート

5 つのクラスはすべて @since 1.9.0 を持ち、nextpdf/pro 3.1.0 で最新です。
モジュールは自己完結型です。レンダラーは ChartBox と ChartColor のみに依存し、Core との結合はありません。
決定的な出力により、チャートを含むドキュメントは再現可能、diff 安定、そして署名やアーカイブに対して安全に保たれます。
チャートをホストするページごとに、チャートフォントリソース名でフォントを 1 回登録します。
構成済みのレンダラーをボックス間で自由に再利用します。render() は状態の変更を一切行いません。
テストエビデンスは pro/tests/Unit/Chart/ 配下にあります。サポートマトリックスは各 Verified 行をそのスイートにアンカーします。

公開範囲

このページは、外部から観測可能な挙動と、サポートされる公開 API サーフェスのみを文書化します。内部の名前空間パス、ヘルパークラス、メカニズムの表、ランブックのファイル名、チケット接頭辞は対象外です。