워크시트 배경 이미지

SpreadJS는 워크시트에 배경 이미지를 설정하는 기능을 지원합니다. 이를 통해 시각적 효과를 향상하고, 데이터 시각화(예: 지도 또는 안내선 오버레이)를 지원하며, 템플릿 스타일을 통일하여 전문성과 사용자 경험을 모두 높일 수 있습니다. 보고서 및 대시보드와 같은 시나리오에 적합합니다.

코드 사용

Worksheet 클래스의 backgroundImage 메서드는 워크시트의 배경 이미지를 설정합니다. 첫 번째 인수로 이미지 원본 문자열을 전달합니다. 이미지의 반복 여부와 워크시트 콘텐츠의 아래 또는 위에 그릴지 여부를 제어하는 옵션 개체를 전달할 수도 있습니다.

이미지 원본은 다음 중 하나일 수 있습니다:

• 이미지 URL

  • 웹에 있는 이미지를 가리키는 경로입니다.

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

  • 외부 경로를 사용하는 경우 애플리케이션에서 리소스에 액세스할 수 있도록 서버에 적절한 CORS 헤더가 구성되어 있는지 확인하세요.

• Base64로 인코딩된 이미지 데이터

  • 이미지를 Base64 형식으로 인코딩하여 데이터 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/pujnxfci/mescuis-logo-horiz.svg", {
    layout: "repeat",
    paintOrder: "over-content"
});

배경 이미지 크기

배경 이미지는 항상 원래 크기로 렌더링되며 늘어나거나 크기가 조정되지 않습니다. 즉, 워크시트의 실제 크기와 관계없이 배경 이미지는 원래 너비와 높이를 유지하며 워크시트에 맞게 자동으로 크기가 조정되지 않습니다.

예를 들어 배경 이미지가 500x300픽셀인 경우 워크시트가 이보다 크더라도 배경 이미지는 늘어나거나 축소되지 않습니다.

let workbook = new GC.Spread.Sheets.Workbook("ss");
let worksheet = workbook.getActiveSheet();
worksheet.backgroundImage("https://cdn.mescius.io/umb/media/pujnxfci/mescuis-logo-horiz.svg");

배경 이미지 반복

layout 옵션을 사용하여 이미지의 반복 여부를 제어합니다.

• "repeat" - 워크시트 영역을 채울 때까지 이미지를 가로 및 세로로 반복합니다. 기본 동작입니다.

• "none" - 워크시트의 왼쪽 위 모서리에 이미지를 한 번 그립니다.

let workbook = new GC.Spread.Sheets.Workbook("ss");
let worksheet = workbook.getActiveSheet();
worksheet.backgroundImage("https://cdn.mescius.io/umb/media/pujnxfci/mescuis-logo-horiz.svg", {
    layout: "repeat"
});

배경 이미지는 워크시트의 실제 크기에 따라 전체 워크시트 영역을 채울 때까지 x축(가로 방향)과 y축(세로 방향) 모두에서 반복됩니다.

예를 들어 워크시트가 1900x900픽셀이고 배경 이미지가 500x300픽셀인 경우 배경 이미지는 가로로 4번, 세로로 3번 반복됩니다. 워크시트 크기를 벗어나는 이미지 부분은 자동으로 잘리므로 워크시트 배경 전체를 채웁니다.

배경 이미지 자르기

배경 이미지가 x축 또는 y축 방향으로 워크시트의 표시 영역을 벗어나는 경우 배경 이미지가 워크시트의 실제 표시 영역을 초과하지 않도록 초과 부분이 자동으로 잘립니다. 즉, 배경 이미지는 워크시트의 실제 크기 내에서만 표시되며 이 범위를 벗어나는 부분은 표시되지 않습니다.

예를 들어 워크시트가 1900x900픽셀이고 배경 이미지가 2000x1200픽셀인 경우 가로로 초과하는 100픽셀과 세로로 초과하는 300픽셀은 표시되지 않습니다. 워크시트 크기에 해당하는 부분만 표시됩니다.

틀 고정 및 스크롤

• 틀 고정 없이 스크롤:

• 틀 고정 상태에서 스크롤:

• 오른쪽에서 왼쪽

배경 이미지 그리기 순서

기본적으로 워크시트 배경 이미지는 워크시트 콘텐츠 아래에 그려집니다.

배경 이미지를 워크시트 콘텐츠 위에 그리려면 paintOrder를 "over-content"로 설정합니다. 이는 기밀 표시나 회사 브랜딩과 같이 보고서에서 워터마크 스타일 이미지를 사용할 때 유용합니다.

worksheet.backgroundImage("./image/background.png", {
    paintOrder: "over-content"
});

배경 이미지가 콘텐츠 위에 그려져도 텍스트, 숫자, 수식 결과, 테두리, 셀 스타일 및 병합된 셀과 같은 워크시트 콘텐츠는 계속 편집하고 선택할 수 있습니다.

인쇄, PDF 내보내기 및 Excel 내보내기

워크시트 배경 이미지는 출력 형식에 따라 다르게 동작합니다.

• paintOrder가 "normal"인 경우 워크시트 배경 이미지는 인쇄하거나 PDF로 내보낼 때 포함되지 않습니다.

• paintOrder가 "over-content"인 경우 워크시트 배경 이미지는 인쇄 및 PDF 내보내기에 포함되며 워크시트 콘텐츠 위에 렌더링됩니다.

• Excel로 내보낼 때는 Excel에서 워크시트 배경 이미지를 콘텐츠 위에 그리는 기능을 지원하지 않으므로 paintOrder 설정이 무시됩니다. 배경 이미지는 일반 워크시트 배경 이미지로 내보내집니다.

• Excel로 내보낼 때 배경 이미지 레이아웃 설정은 유지됩니다.

리포트 시트에서 배경 이미지를 워터마크로 사용

paintOrder를 "over-content"로 설정한 워크시트 배경 이미지를 사용하여 리포트 시트 콘텐츠 위에 워터마크 스타일 이미지를 표시할 수 있습니다.

const spread = new GC.Spread.Sheets.Workbook('ss', { sheetCount: 1 });
const reportSheet = spread.addSheetTab(0, 'report1', GC.Spread.Sheets.SheetType.reportSheet);
const templateSheet = reportSheet.getTemplate();

templateSheet.backgroundImage('./image/background.jpg', {
    paintOrder: 'over-content'
});

reportSheet.renderMode('Preview');

이 방법은 "기밀"과 같은 워터마크를 생성된 보고서 콘텐츠 위에 표시해야 하는 경우에 유용합니다.

디자이너에서 워크시트 배경 이미지 설정

디자이너에서 페이지 레이아웃 탭을 사용하여 워크시트 배경 이미지를 설정하거나 삭제할 수 있습니다. 배경 그룹에서는 이미지의 반복 여부와 워크시트 콘텐츠 위에 그릴지 여부를 제어하는 옵션도 제공합니다.

• 반복 - 워크시트 전체에 배경 이미지를 반복합니다.

• 콘텐츠 위에 표시 - 워크시트 콘텐츠 위에 배경 이미지를 그립니다.

• 배경 삭제 - 워크시트 배경 이미지를 제거합니다.

//V19 SP2 이전
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);

//V19 SP2 이후에는 background 노드가 변경되었습니다.
var config = GC.Spread.Sheets.Designer.DefaultConfig;
var pageLayout = config.ribbon.filter((item)=>{ return item.id === 'pageLayout'})[0];
var background = pageLayout.buttonGroups[2];
background.commandGroup.children[0].commands = background.commandGroup.children[0].commands.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;
});
background.commandGroup.children.splice(1,1);

designer.setConfig(config);