# ActiveReportJS 디자이너 테마
## Content
## 소개
ActiveReportsJS는 `리포트 디자이너` 구성 요소를 위한 유연한 테마 옵션을 제공하여 애플리케이션의 디자인에 맞게 손쉽게 커스터마이징할 수 있습니다. 테마 기능은 다음을 포함합니다:
* **내장 색상 테마** – 디자이너의 외형을 조정하는 사전 정의된 테마입니다.
* **테마 선택기** – 사용자가 사용 가능한 테마를 전환할 수 있도록 뷰어 툴바에 내장된 컨트롤입니다.
* **커스터마이징을 위한 API** – 커스텀 테마를 생성하고, 프로그래밍 방식으로 디자이너 테마를 설정하며, 테마 선택기를 구성할 수 있는 API 세트입니다.
이러한 기능을 통해 리포트 디자이너를 다양한 UI 스타일에 통합하면서 일관되고 개인화된 사용자 경험을 제공할 수 있습니다.
## 초기 설정
Report Designer에서 테마를 활성화하려면 애플리케이션에 필요한 스타일시트를 포함해야 합니다. 다음 CSS 파일은 ActiveReportsJS의 [다운로드 패키지](https://developer.mescius.com/activereportsjs/download), [CDN 배포](/activereportsjs/docs/v6.1/#report-viewer-ui-themes), 그리고 [@mescius/activereportsjs](https://www.npmjs.com/package/@mescius/activereportsjs) npm 패키지를 통해 제공됩니다:
* **`ar-js-ui.css`** – `Report Viewer`와 `Report Designer` 컴포넌트에서 공유되는 공통 스타일.
* **`ar-js-designer.css`** – 디자이너 전용 스타일로, 여러 개의 사전 정의된 테마를 포함합니다:
* `System` – 사용자의 시스템 테마 설정(라이트 또는 다크 모드)에 자동으로 적응.
* `Default` – 표준 가독성과 사용성을 위해 설계된 깔끔하고 현대적인 라이트 테마.
* `DefaultDark` – 저조도 환경에서 눈의 피로를 줄여주는 Default 테마의 다크 버전.
* `DarkOled` – OLED 디스플레이에서 대비를 극대화하고 전력을 절약하도록 설계된 깊은 검정색 OLED 친화적 테마.
* `HighContrast` – 가시성과 접근성을 향상시키기 위한 밝은 고대비 테마.
* `HighContrastDark` – 다크 모드에서 높은 가독성을 필요로 하는 사용자를 위한 고대비 다크 테마.
* `ActiveReports` – 친숙한 UI 스타일을 제공하는 클래식 ActiveReports 테마.
* `ActiveReportsDark` – 더 부드럽고 눈에 친화적인 인터페이스를 제공하는 ActiveReports 테마의 다크 버전.
CDN을 사용하는 애플리케이션의 경우, 스타일을 포함하려면 다음 `` 태그를 추가하세요:
```html
```
애플리케이션이 모듈 기반 CSS 가져오기를 지원하는 경우, 코드를 통해 스타일을 직접 포함할 수 있습니다:
```js
import "@mescius/activereportsjs/styles/ar-js-ui.css";
import "@mescius/activereportsjs/styles/ar-js-designer.css";
```
## themeConfig API 사용하기
Report Designer 구성의 `themeConfig` 속성을 사용하여 다음을 수행할 수 있습니다:
* **초기 테마** 설정.
* **테마 선택기** 활성화 또는 비활성화.
* 테마 선택기에서 사용할 수 있는 **테마 정의**.
순수 JavaScript 애플리케이션의 경우, `MESCIUS.ActiveReportsJS.ReportDesigner.Designer` 생성자의 두 번째 인자에서 `themeConfig` 속성을 사용하세요:
```js
var designer = new MESCIUS.ActiveReportsJS.ReportDesigner.Designer("#designer-host", {
themeConfig: {
// Set the initial theme
initialTheme: 'ActiveReports',
themeSelector: {
// Enable or disable the theme selector
isEnabled: true,
// Define available themes in the selector
availableThemes: [`ActiveReports`, `ActiveReportsDark`]
}
}
});
```
React, Angular, Vue, 그리고 Svelte에서는 `onInit` 속성을 사용하여 `DesignerConfig` 객체를 가져오는 함수로 설정할 수 있습니다.
예시: React에서 `themeConfig` 사용하기.
```jsx
import React from "react";
import { Designer} from "@mescius/activereportsjs-react";
function onInit() {
return {
themeConfig: {
initialTheme : 'ActiveReports',
themeSelector: {
isEnabled: true,
availableThemes: ['ActiveReports', 'System', 'Default']
}
};
}
function App() {
return (
);
}
export default App;
```
## 사용자 지정 테마 만들기
미리 정의된 테마를 사용하는 것 외에도 ActiveReportsJS API를 사용하여 사용자 지정 테마를 만들 수 있습니다.
먼저, 다음과 같은 속성을 포함하는 객체를 구성하여 테마 색상을 정의해야 합니다:
| 속성 | 타입 | 설명 |
| -------- | ---- | ----------- |
| **`name`** | `string` | 테마의 고유 이름. |
| **`type`** | `"light"` 또는 `"dark"` | 테마가 라이트인지 다크인지 정의. |
| **`backgroundMain`** | `string` | 뷰어의 기본 배경색. |
| **`backgroundPanels`** | `string` | 뷰어 내부 패널의 배경색. |
| **`primary`** | `string` 또는 `shades` | 메인 강조 색상으로, 단일 색상이나 색상 세트. |
| **`secondary`** | `string` 또는 `shades` *(선택 사항)* | 추가 UI 요소를 위한 보조 강조 색상. |
| **`neutral`** | `string` 또는 `shades` *(선택 사항)* | UI 대비를 균형 있게 유지하기 위한 중립 색상. |
| **`error`** | `string` 또는 `shades` *(선택 사항)* | 오류 메시지나 표시기에 사용되는 색상. |
| **`warning`** | `string` 또는 `shades` *(선택 사항)* | 경고나 알림에 사용되는 색상. |
| **`fontFamily`** | `string` *(선택 사항)* | 뷰어 전반에 사용될 글꼴 지정. |
`primary`, `secondary`, `neutral`, `error`, 그리고 `warning` 속성은 두 가지 방법으로 정의할 수 있습니다:
1. **단일 색상 (string)** – 단일 HEX, RGB 또는 명명된 색상. 예시:
```js
primary: "#0084ff"
```
2. **그라데이션 색상 (object)** – 다양한 UI 요소에 사용할 여러 색상 음영을 정의합니다.
```js
primary: {
veryLight: "#d1e8ff",
light: "#a3d4ff",
lighter: "#75bfff",
lightMedium: "#47abff",
medium: "#1a97ff",
base: "#0084ff",
darkMedium: "#0072db",
darker: "#005fb7",
dark: "#004c93",
veryDark: "#00396f"
}
```
다음은 사용자 지정 테마를 정의하는 전체 예시입니다.
```js
const myCustomTheme = {
name: "CustomBlue",
type: "light", // "light" 또는 "dark"
backgroundMain: "#f0f4f8", // 기본 배경색
backgroundPanels: "#d9e2ec", // 패널 배경색
primary: {
veryLight: "#d1e8ff",
light: "#a3d4ff",
lighter: "#75bfff",
lightMedium: "#47abff",
medium: "#1a97ff",
base: "#0084ff", // 기본 강조 색상
darkMedium: "#0072db",
darker: "#005fb7",
dark: "#004c93",
veryDark: "#00396f"
},
secondary: "#ffcc00", // 단일 색상 또는 음영
neutral: {
base: "#6b7280",
light: "#d1d5db",
dark: "#374151"
},
error: "#e63946", // 오류 색상
warning: "#ff9f1c", // 경고 색상
fontFamily: "Arial, sans-serif" // 사용자 지정 글꼴
};
```
그런 다음, 사용자 지정 테마 객체를 `theme` 속성 값으로 사용하거나 `availableThemes` 배열의 항목으로 사용할 수 있습니다. 또한, `themeConfig` 객체의 `initialTheme` 속성에 사용자 지정 테마 이름을 사용할 수도 있습니다.