[]
DEMOS DOC DESIGNER API
DOWNLOAD
(Showing Draft Content)

테마

SpreadJS 디자이너 컴포넌트는 사용자 인터페이스(UI) 맞춤화와 적응성을 향상시키기 위해 네 가지 개별 테마 옵션을 지원하는 고급 테마 시스템을 도입합니다. 여기에는 세 가지 사전 설정 테마—Light, Dark, Classic—와 유연한 사용자 정의 테마 시스템이 포함됩니다.

  • Light 및 Dark 테마는 현대 디스플레이 환경에 맞춰 설계되었으며, 각각의 환경에서 고대비 및 가독성을 최적화한 시각적 스타일을 제공합니다.

  • Classic 테마는 친숙하고 중립적인 미적 감각을 제공하며, 전통적인 스프레드시트 인터페이스를 원하는 사용자에게 적합합니다.

  • 사용자 정의 테마 시스템을 통해 개발자는 디자이너 컴포넌트의 외관을 조정할 수 있으며, 색상, 테두리 반경, 그림자 등을 특정 애플리케이션 브랜드나 독특한 사용자 선호에 맞게 조정할 수 있습니다.

이 다양한 테마 생태계를 통해 SpreadJS 디자이너 컴포넌트는 다양한 사용자 환경에 원활하게 통합되며, 기본 제공 편의성과 개인화된 UI 디자인을 위한 광범위한 유연성을 균형 있게 제공합니다.

디자이너 컴포넌트 테마 CSS 파일 포함

SpreadJS 디자이너 컴포넌트의 다양한 테마를 적용하려면, 주로 프로젝트에 적절한 CSS 파일을 포함하는 것이 필요합니다. 특정 테마를 적용하려면 개발자가 해당 CSS 파일을 프로젝트 내에 명시적으로 연결해야 합니다.

예를 들어, HTML 구조의 <head> 섹션에 <link> 태그를 추가하고 href 속성이 올바른 CSS 파일 경로를 가리키도록 합니다. 일반적인 예시는 다음과 같습니다.

<link rel="styleSheet" href="css/gc.spread.sheets.designer.light.x.x.x.min.css" />

편의를 위해, 다운로드한 ZIP 번들에 미리 패키지된 테마 CSS 파일이 제공되며, 경로는 \SpreadJS.Release.xxxx\Designer\Designer Component\css입니다. 이 디렉터리에는 필요한 모든 사전 설정 테마 파일이 포함되어 있어 원하는 스타일에 쉽게 접근하고 참조할 수 있습니다.

원하면 모듈 로더를 사용하여 테마를 가져올 수도 있습니다.

참고:

한 번에 하나의 디자이너 컴포넌트 테마 CSS 파일만 참조해야 합니다.

사전 정의 테마

사전 정의 테마는 색상 구성, 대비 수준, 스타일 세부 사항(탭 평면도, 테두리 반경, 그림자 부드러움, 아이콘 최적화, 상태별 색상 등)의 차이에 따라 각각 고유한 시각적 정체성을 제공합니다.

이러한 차이는 전체 UI 조화뿐만 아니라 리본 바, 다이얼로그 창, 패널과 같은 주요 구성 요소의 외관에도 영향을 미쳐, 각 테마가 특정 미적 선호와 일치하도록 보장합니다.

사용 가능한 테마는 다음과 같습니다.

이름

CSS 파일

스크린샷 (전체 화면, 다이얼로그 창, 패널)

Light (기본)

gc.spread.sheets.designer.light.x.x.x.min.css

image

image

image

Dark

gc.spread.sheets.designer.dark.x.x.x.min.css

image

image

image

Classic

gc.spread.sheets.designer.x.x.x.min.css

image

image

image

참고:

18.2.0 버전 이전에는 SpreadJS 디자이너 컴포넌트가 Classic 사전 정의 테마만 유일한 UI 스타일 옵션으로 제공되었습니다.

사용자 정의 테마 시스템

SpreadJS 디자이너 컴포넌트 용 사용자 정의 테마를 만들 때는 먼저 Light 또는 Dark 사전 정의 테마 중 하나를 기반으로 설정하는 것이 필수입니다. 이러한 새 테마가 사용자 정의의 기반 역할을 합니다.

기반 테마를 선택한 후, API 호출, CSS 오버라이드, JavaScript 수정을 통해 UI의 시각적 속성(색상, 테두리 반경, 그림자 등)을 애플리케이션 고유 브랜드나 사용자 경험 목표에 맞게 추가로 조정할 수 있습니다.

API를 통한 사용자 정의

동적으로 사용자 정의 테마를 적용하려면 setTheme 메서드를 사용할 수 있습니다. 이 방법은 기본 테마 구조를 유지하면서 런타임 수정이 가능합니다.

setTheme() 메서드는 Partial<GC.Spread.Sheets.Designer.ITheme> 객체를 받아 지정된 속성만 기존 값 위에 덮어쓰도록 합니다. 예를 들어:

GC.Spread.Sheets.Designer.setTheme({
    colorBackground: "#F0F4F8",       // 모든 표준 구성 요소의 배경
    colorForeground: "#2D3436",       // 모든 일반 텍스트 색상
    borderRadiusM: "6px",             // 중간 테두리 반경
    shadow8: "rgba(142, 148, 156, 0.1) 0px 2px 4px, rgba(142, 148, 156, 0.06) 0px 1px 2px"  // 그림자 효과
});

참고:

구성 가능한 테마 속성 목록(색상, 테두리 반경, 그림자 포함)은 이 가이드 후반부의 "테마 속성 참조" 섹션에서 자세히 설명됩니다.

상태 관리

  • 테마 재설정: setTheme()에 null을 전달하여 활성 사전 설정(Light/Dark) 기본값으로 되돌릴 수 있습니다.

    Designer.setTheme(null); // 시스템 사전 설정으로 되돌리기

  • 현재 구성 확인: getTheme()를 사용하여 전체 테마 상태(상속된 사전 설정 값 포함)를 확인할 수 있습니다.

    let currentTheme = GC.Spread.Sheets.Designer.getTheme();
console.log(currentTheme.colorBackground); // "#F0F4F8"

CSS 또는 JS를 통한 사용자 정의

SpreadJS 디자이너 컴포넌트는 CSS 변수(토큰) 및 JavaScript DOM 조작을 통해 동적 테마 사용자 정의를 지원합니다. 세 가지 주요 접근 방식이 있습니다.

1. 정적 테마 오버라이드 (CSS)

전역 CSS에서 테마 토큰을 직접 정의하여 기본값을 덮어씁니다.

:root {
  --sjs-color-background: #F0F4F8;       // 모든 표준 구성 요소의 배경
  --sjs-color-foreground: #2D3436;       // 모든 일반 텍스트 색상
  --sjs-border-radius-m: 6px;            // 중간 테두리 반경
  --sjs-shadow-8: rgba(142, 148, 156, 0.1) 0px 2px 4px, rgba(142, 148, 156, 0.06) 0px 1px 2px;  // 그림자 효과
}

적합한 경우: 런타임 변경이 필요 없는 정적 애플리케이션에서 영구 테마 적용.

2. 동적 런타임 업데이트 (JavaScript DOM)

문서 루트 요소를 대상으로 테마 토큰을 런타임에 수정합니다.

document.documentElement.style.setProperty(GC.Spread.Sheets.Designer.ThemeTokens.colorBackground, '#F0F4F8'); 
document.documentElement.style.setProperty(GC.Spread.Sheets.Designer.ThemeTokens.colorForeground, '#2D3436'); 
document.documentElement.style.setProperty(GC.Spread.Sheets.Designer.ThemeTokens.borderRadiusM, '6px'); 
document.documentElement.style.setProperty(GC.Spread.Sheets.Designer.ThemeTokens.shadow8, 'rgba(142, 148, 156, 0.1) 0px 2px 4px, rgba(142, 148, 156, 0.06) 0px 1px 2px');

장점: 페이지 리로드 없이 테마 전환 가능. 사용자 주도 테마 선호에 적합.

3. 프로그래밍 방식 규칙 삽입

JavaScript로 CSS 규칙을 동적으로 생성하여 복잡한 테마 시나리오 적용.

export function createCSSRule (selector: string, theme: GC.Spread.Sheets.Designer.ITheme | undefined): string {
    if (theme) {
        const cssVarsAsString = (Object.keys(theme) as (keyof typeof theme)[]).reduce((cssVarRule, cssVar) => {
            return `${cssVarRule}${GC.Spread.Sheets.Designer.ThemeTokens[cssVar]}: ${theme[cssVar]}; `;
        }, '');
        return `${selector} { ${cssVarsAsString} }`;
    }
    return `${selector} {}`;
}
let customThemeRule = createCSSRule(":root", {
  colorBackground: "#F0F4F8",
  colorForeground: "#2D3436",
  borderRadiusM: "6px",
  shadow8: "rgba(142, 148, 156, 0.1) 0px 2px 4px, rgba(142, 148, 156, 0.06) 0px 1px 2px",
});
let customStyleElement = document.createElement("style");
customStyleElement.sheet?.insertRule(customThemeRule);
document.head.appendChild(customStyleElement);

사용 사례: 복잡한 변수 종속성을 가진 구성 요소나 배치 테마 적용.

참고:

구성 가능한 테마 토큰 목록(색상, 테두리 반경, 그림자 포함)은 이 가이드 후반부의 "테마 속성 참조" 섹션에서 자세히 설명됩니다.

테마 속성 참조

SpreadJS는 개발자가 테마를 세밀하게 제어할 수 있도록 두 가지 핵심 API—GC.Spread.Sheets.Designer.ITheme 및 GC.Spread.Sheets.Designer.ThemeTokens—를 제공합니다.

색상, 테두리 반경, 그림자 등을 조정할 때, 이 API의 속성과 토큰을 이해하는 것이 디자이너 컴포넌트 외관을 사용자 요구에 맞게 맞추는 핵심입니다.

아래 표는 ITheme의 전체 속성 목록과 해당 ThemeTokens 변수, UI 요소에 대한 실질적 영향(배경 색상부터 상호작용 상태까지)을 자세히 설명합니다.


속성

토큰

설명

1

colorForeground

--sjs-color-foreground

일반 글꼴 색상, 모든 일반 텍스트에 사용됩니다.

2

colorForegroundDisabled

--sjs-color-foreground-disabled

구성 요소가 비활성화 되었을 때 일반 텍스트 색상입니다.

3

colorBackground

--sjs-color-background

일반 배경 색상, 모든 표준 구성 요소의 배경에 사용됩니다.

4

colorBackgroundHover

--sjs-color-background-hover

표준 구성 요소에 마우스를 올렸을 때의 배경 색상입니다.

5

colorBackgroundSelected

--sjs-color-background-selected

표준 구성 요소가 선택되었을 때의 배경 색상입니다.

6

colorBackgroundDisabled

--sjs-color-background-disable

표준 구성 요소가 비활성화 되었을 때의 배경 색상입니다.

7

colorBackground2

--sjs-color-background-2

디자이너에서 가장 하위 컨테이너의 배경 색상입니다.

8

colorBackground2Hover

--sjs-color-background-2-hover

하위 컨테이너 구성 요소에 마우스를 올렸을 때의 배경 색상입니다.

9

colorBackground2Selected

--sjs-color-background-2-selected

하위 컨테이너 구성 요소가 선택되었을 때의 배경 색상입니다.

10

colorBrandForeground

--sjs-color-brand-foreground

브랜드 배경 위에 표시되는 텍스트 색상입니다.

11

colorBrandBackground

--sjs-color-brand-background

브랜드를 나타내는 색상으로, 제품의 색상 식별자 역할을 합니다. 돋보이거나 브랜드 스타일을 보여줘야 하는 구성 요소의 배경색으로 사용됩니다.

12

colorBrandBackgroundHover

--sjs-color-brand-background-hover

브랜드 배경 색상에 마우스를 올렸을 때의 배경 색상입니다.

13

colorBrandBackgroundSelected

--sjs-color-brand-background-selected

브랜드 배경 색상이 선택되었을 때의 배경 색상입니다.

14

colorStroke

--sjs-color-stroke

테두리 색상입니다.

15

colorStrokeHover

--sjs-color-stroke-hover

구성 요소에 마우스를 올렸을 때 테두리 색상입니다.

16

colorStrokeSelected

--sjs-color-stroke-selected

구성 요소가 선택되었을 때 테두리 색상입니다.

17

colorStrokeDisabled

--sjs-color-stroke-disabled

구성 요소가 비활성화 되었을 때 테두리 색상입니다.

18

borderRadiusM

--sjs-border-radius-m

중간 테두리 반경입니다.

19

borderRadiusL

--sjs-border-radius-l

큰 테두리 반경입니다.

20

borderRadiusXL

--sjs-border-radius-xl

매우 큰 테두리 반경입니다.

21

shadow4

--sjs-shadow-4

블러 반경 4px 그림자입니다.

22

shadow8

--sjs-shadow-8

블러 반경 8px 그림자입니다.