ワークシートの背景画像

SpreadJSはワークシートの背景画像設定をサポートしており、視覚的な魅力を高めたり、データ可視化を補助（例えば地図やガイドを重ねる）したり、専門性とユーザー体験のバランスが取れた統一されたテンプレートスタイルを作成したりするのに役立ちます。この機能はレポートやダッシュボードなどのシナリオに最適です。

コードの使用

WorksheetクラスのbackgroundImage関数を使用して、ワークシートに背景画像を設定できます。パラメータには画像ソースの文字列を指定します。

画像URL（外部パス）
- Web上に存在する画像ファイルへのパスを指定します。
- 例: "https://example.com/path/to/image.jpg"
- 外部パスを使用する場合、アプリケーションがリソースにアクセスできるよう、サーバーが適切なCORSヘッダーを設定している必要があります。
Base64エンコード画像データ
- 画像をBase64形式でエンコードしたデータです。Data URLとしてHTMLやCSSに直接埋め込むことができます。
- 例: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
相対パス画像
- APIと画像リソースが同一サーバー上にある場合、相対パスを使用して画像を参照できます。
- 例: "/images/background.png"

let workbook = new GC.Spread.Sheets.Workbook("ss");
let worksheet = workbook.getActiveSheet();
worksheet.backgroundImage("https://cdn.mescius.io/umb/media/5lnfh0kr/2023-mescius-home-jumbotron-graphic.png")

背景画像のレイアウトについて

背景画像は常に元のサイズで表示され、伸縮や拡大縮小されることはありません。つまり、ワークシートの実際のサイズに関わらず、背景画像は元の幅と高さを維持し、ワークシートに合わせて自動的にサイズ変更されることはありません。

例えば、500×300ピクセルの背景画像がある場合、ワークシートのサイズがこれより大きくても、背景画像は引き伸ばされたり縮小されたりすることはありません。

背景画像の繰り返し表示について

背景画像はワークシートの実際サイズに応じて、x軸（水平方向）とy軸（垂直方向）の両方で繰り返し表示され、ワークシート領域全体を埋め尽くすように配置されます。

例えば、ワークシートのサイズが1900x900ピクセルで、背景画像が500x300ピクセルの場合、背景画像は水平方向に4回、垂直方向に3回繰り返されます。

背景画像のクリッピング

ワークシートの表示領域を背景画像が超えないようにするため、X軸またはY軸のいずれかでワークシートの表示領域を超える場合、はみ出た部分は自動的に切り取られます。つまり、背景画像はワークシートの実際の寸法内でのみ表示され、この範囲を超える部分は表示されません。

例えば、ワークシートのサイズが1900×900ピクセルで、背景画像が2000×1200ピクセルの場合、横方向に100ピクセル、縦方向に300ピクセルが超過しますが、これらの部分は表示されません。ワークシートの寸法に一致する部分のみが表示されます。

固定領域とスクロール

固定領域なしでのスクロール
固定領域ありでのスクロール
右から左へ（RTL）

背景画像のレイヤー

ワークシートの背景画像は、ワークブックの上層に位置しますが、ワークシート内のすべてのオブジェクトの下層に配置されます。具体的には、以下のオブジェクトの下に表示されます：

セルの背景色
セルの罫線
図形（シェイプ）
グラフ
ワークシートに追加されたその他のオブジェクト

つまり、セルにどのようなコンテンツやオブジェクトを追加しても、それらは常に背景画像の上に表示されます。背景画像は最下層の装飾として機能するため、ユーザーがセルの内容を閲覧・編集したり、他のワークシート要素を操作したりする際の妨げになることはありません。

背景画像とExcelインポート

Excelは無制限の行/列を表示可能ですが、SpreadJSには行数と列数の制限があるため、従来はデータのないExcelワークシートをインポートすると、通常はA1セルのみが表示されていました。しかし、背景画像のサポート導入後、空のExcelワークシートに背景画像が含まれている場合、SpreadJSにインポートする際には、背景画像を完全に表示するために、ユーザーがワークシートの行数と列数を明示的に設定する必要があります。

type=note
ワークシート背景画像の印刷/PDF出力に関する仕様

デザイナーでのワークシート背景画像設定方法

デザイナーのページレイアウトタブからワークシートの背景画像を設定または削除できます。

type=note
デフォルトでは、デザイナの背景画像操作ボタンは、ワークシートごとに背景画像を設定するコマンドに関連付けられています。SpreadJSの以前のバージョンのように、ブック全体に背景画像を適用する機能に戻したい場合は、デザイナの初期化時に以下のスクリプトを実行します。
var config = GC.Spread.Sheets.Designer.DefaultConfig;
var pageLayout = config.ribbon.filter((item)=>{ return item.id === 'pageLayout'})[0];
var pageSetup = pageLayout.buttonGroups.filter((item)=>{return item.thumbnailClass==='ribbon-thumbnail-page-setup'})[0]
var pageSetupCmdGroup = pageSetup.commandGroup.children[0].children;
pageSetup.commandGroup.children[0].children = pageSetupCmdGroup.map(function(ele){
    if(ele === 'worksheetBackground'){
        return GC.Spread.Sheets.Designer.CommandNames.Background;
    }else if(ele === 'deleteWorksheetBackground'){
        return GC.Spread.Sheets.Designer.CommandNames.DeleteBackground;
    }
    return ele;
});
designer.setConfig(config);