Worksheet Background Image

SpreadJS supports setting background images for worksheets, which can help you enhance visual aesthetics, aid in data visualization (such as overlaying maps or guidelines), and unify the template style, balancing professionalism and user experience. It is suitable for scenarios such as reports and dashboards.

Using Code

The backgroundImage function of the Worksheet class can be used to set a background Image to the worksheet, the parameter is an image source string:

• Image URL

  • A path pointing to an image located somewhere on the web.

  • Example: "https://example.com/path/to/image.jpg"

  • If using the external path, ensure that the server is configured with appropriate CORS headers to allow your application to access the resource.

• Base64 Encoded Image Data

  • The image is encoded in Base64 format, which can be directly embedded into HTML or CSS as a Data URL.

  • Example: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."

• Relative Path Image

  • If the API and image resources are on the same server, you can use a relative path to reference the image.

  • Example: "/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")

Background Image Layout

The background image is always rendered using its original size and will not be stretched or scaled. This means that regardless of the actual size of the worksheet, the background image will maintain its original width and height and will not automatically resize to fit the worksheet.

For example, if you have a background image that is 500x300 pixels, even if the worksheet is larger than this size, the background image will not be stretched or shrunk.

Background Image Repeat

The background image will be repeated in both the x-axis (horizontal direction) and y-axis (vertical direction) according to the actual size of the worksheet until it fills the entire worksheet area.

For example, if your worksheet is 1900x900 pixels and your background image is 500x300 pixels, the background image will repeat 4 times horizontally and 3 times vertically. Any portion of the image that exceeds the worksheet dimensions will be automatically clipped, thus filling the worksheet background.

Background Image Clip

To ensure that the background image does not exceed the actual display area of the worksheet if the background image extends beyond the display area of the worksheet in either the x-axis or y-axis, the excess portion will be automatically clipped. This means that the background image will only be displayed within the actual dimensions of the worksheet, and any part that extends beyond this range will not be shown.

For example, if your worksheet is 1900x900 pixels and your background image is 2000x1200 pixels, then the 100 pixels exceeding horizontally and the 300 pixels exceeding vertically will not be displayed. Only the portion that matches the worksheet's dimensions will be visible.

Freeze Panes and Scrolling

• Scrolling without freeze panes:

• Scrolling with freeze panes:

• Right to Left

The layer of the Worksheet Background Image

The Worksheet background image is above the workbook but beneath all objects of the worksheet. Specifically, the worksheet background image is under the following objects:

1. Cell background colors

2. Cell borders

3. Shapes

4. Charts

5. Any other objects added to the worksheet

This means that regardless of what content or objects you add to the cells, this content and these objects will appear above the background image. The background image serves as a bottom-layer decoration, ensuring it does not interfere with the user's ability to view and edit cell contents or other worksheet elements.

The background image supports export to Excel and import from Excel.

Since Excel can display an unlimited number of rows and columns, whereas SpreadJS has fixed row and column limits, importing an Excel worksheet with no data into SpreadJS previously resulted in only one cell (typically A1) being displayed. However, after introducing support for background images, if an empty Excel worksheet contains a background image, upon importing it into SpreadJS, Users need to set the number of rows and columns of the worksheet to display the complete background image.

The worksheet background images will be ignored when printing or exporting to PDF.

Setting the Worksheet Background Image in the Designer.

You can set or delete the worksheet background image from the Designer Page Layout Tab

By default, the background image operation button in the Designer is associated with commands for setting the background image on a per-worksheet basis. If users wish to revert to the functionality of applying background images to the entire workbook, they can execute the following script during the initialization of the Designer.

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);