# 사용자 정의

## Content

## 공통

ActiveReportsJS API를 사용하면 보고서 뷰어의 도구 모음과 사이드바의 기본 사용자 인터페이스를 완벽하게 사용자 지정할 수 있습니다. 이 페이지에서는 이러한 구성 요소를 특정 애플리케이션 요구 사항에 맞게 조정하는 몇 가지 방법을 설명합니다.

## 도구 모음 사용자정의

ActiveReportsJS 보고서 뷰어는 뷰어 상태 또는 장치 유형에 따라 자동으로 전환되는 세 가지 기본 도구 모음 레이아웃을 제공합니다.

| 레이아웃 | 설명 |
| ---- | --- |
| 기본 | 표준 보기에서 사용되는 기본 도구 모음 레이아웃 |
| 전체 화면 | 보고서 뷰어가 전체 화면 모드일 때 표시됩니다. |
| 모바일 | 좁은 화면(모바일 기기)에서 활성화됩니다. |

### 기본 도구 모음 항목

도구 모음은 기본 항목과 그룹으로 구성됩니다. [getDefaultToolbarItems 메서드](/activereportsjs/api/interfaces/ReportViewer.Toolbar#getdefaulttoolbaritems)를 사용하여 항목 컬렉션을 가져올 수 있습니다.

| 내부 ID | 설명 |
| ----- | --- |
| $navigation | **그룹:** 탐색 컨트롤 (첫 페이지로 이동, 이전 페이지로 이동, 페이지 번호/전체 페이지 수, 다음 페이지로 이동, 마지막 페이지로 이동) |
| $history | **그룹:** 탐색 기록 (상위 보고서, 이전, 다음) |
| $zoom | **그룹:** **그룹:** 확대/축소 제어(축소, 배율, 확대) |
| $split | 구분 기호 |
| $refresh | 보고서 새로 고침 |
| $mousemode | 선택 모드와 이동 모드 간 전환 |
| $fullscreen | 전체 화면 모드 설정/해제 |
| $print | 보고서 인쇄 버튼 |
| $singlepagemode | 단일 페이지 모드로 전환 |
| $continuouspagemode | 연속 페이지 모드로 전환 |
| $galleymode | 갤리 페이지 모드로 전환 |
| $theme | 테마 선택 드롭다운 |

### 세부적인 사용자 정의 (하위 항목)

보다 세밀한 제어를 위해 `$navigation`, `$history`, `$zoom` 그룹 내의 개별 항목에 접근하여 조작할 수 있습니다. 이러한 하위 항목은 기본 항목과 마찬가지로 [updateLayout](/activereportsjs/api/interfaces/ReportViewer.Toolbar#updatelayout), [updateItem](/activereportsjs/api/interfaces/ReportViewer.Toolbar#updateitem) 및 [removeItem](/activereportsjs/api/interfaces/ReportViewer.Toolbar#removeItem) 메서드에서 사용할 수 있습니다. [getDefaultToolbarItems 메서드](/activereportsjs/api/interfaces/ReportViewer.Toolbar#getdefaulttoolbaritems)는 그룹 이름(예: `$navigation`)을 매개변수로 전달하면 하위 항목 목록을 반환합니다.

* **$navigation 하위 항목:** `$navigation-firstPage`, `$navigation-prevPage`, `$navigation-pageNumber`, `$navigation-nextPage`, `$navigation-lastPage`
* **$history 하위 항목:** `$history-backToParent`, `$history-goBack`, `$history-goForward`
* **$zoom 하위 항목:** `$zoom-zoomOut`, `$zoom-zoomLevel`, `$zoom-zoomIn`

[updateLayout 메서드](/activereportsjs/api/interfaces/ReportViewer.Toolbar#updatelayout)를 사용하여 각 레이아웃 모드에 표시되는 항목을 재정의할 수 있습니다. 다음 React 예제는 모바일 사용자를 위한 간소화된 환경을 제공하기 위해 특정 탐색 하위 항목을 사용하는 것을 포함하여 세 가지 레이아웃 모드 모두에 대한 도구 모음을 재정의하는 방법을 보여줍니다.

```js
import { Viewer } from "@mescius/activereportsjs-react";

const ViewerApp: React.FC = () => {
  const viewerRef = React.useRef < Viewer > null;

  React.useEffect(() => {
    const viewerInstance = viewerRef.current?.Viewer;
    viewerInstance?.toolbar.updateLayout({
      default: ["$zoom", "$split", "$fullscreen", "$split", "$print"],
      fullscreen: ["$fullscreen", "$split", "$print"],
      mobile: ["$navigation-prevPage", "$navigation-pageNumber", "$navigation-nextPage"],
    });
  }, []);
  return (
    <div id="viewer-host">
      <Viewer
        ref={viewerRef}
        report={{ Uri: "/reports/Customers.rdlx-json" }}
      />
    </div>
  );
};
```

React, Angular, Vue 및 순수 JavaScript 애플리케이션의 전체 예제를 [온라인 데모](https://demo.mescius.co.kr/activereportsjs/demos/features/viewer-customization-toolbar)에서 확인할 수 있습니다.

### 도구 모음 항목 추가, 제거 및 업데이트

[addItem 메서드](/activereportsjs/api/interfaces/ReportViewer.Toolbar#additem)를 사용하여 도구 모음 항목 컬렉션에 새로운 버튼을 추가하거나 드롭다운을 추가할 수 있습니다.

>type=info
> 기본적으로 새 항목은 도구 모음의 끝에 추가됩니다. `updateLayout` 메서드를 호출하여 새 요소의 위치를 정의할 수 있습니다.

[removeItem](/activereportsjs/api/interfaces/ReportViewer.Toolbar#removeitem) 메서드를 사용하여 항목을 제거할 수 있습니다. 이 메서드는 하위 항목(예: `$navigation-lastPage`)과 `$refresh` 또는 `$mousemode`와 같은 표준 항목을 포함하여 모든 내부 ID를 허용합니다.
기존 항목의 동작이나 모양을 수정하려면 [updateItem](/activereportsjs/api/interfaces/ReportViewer.Toolbar#updateitem)을 사용하세요. 이 기능은 사용자 정의 항목과 모든 기본 제공 항목/하위 항목에 적용됩니다.

>type=info
> 그룹 내 항목이 업데이트되면 그룹 전체를 사용할 때 해당 변경 사항이 유지됩니다. 예를 들어, `$navigation-firstPage`를 업데이트하면 레이아웃에 `$navigation`만 추가하더라도 해당 변경 사항이 반영됩니다.

아래 예시는 특정 탐색 버튼의 툴팁과 '인쇄' 버튼의 동작을 업데이트합니다.

```js
import { Viewer } from "@mescius/activereportsjs-react";

const ViewerApp: React.FC = () => {
  const viewerRef = React.useRef < Viewer > null;

  React.useEffect(() => {
    const viewerInstance = viewerRef.current?.Viewer;
    viewerInstance?.toolbar.updateItem("$navigation-firstPage", { 
      title: "Open Page 1️⃣" 
    });
    viewerInstance?.toolbar.updateItem("$print", {
      action: function () {
        ga("send", {
          hitType: "event",
          eventCategory: "action",
          eventAction: "print",
          eventLabel: "report",
        });
        viewerInstance.print();
      },
    });
  }, []);
  return (
    <div id="viewer-host">
      <Viewer
        ref={viewerRef}
        report={{ Uri: "/reports/Customers.rdlx-json" }}
      />
    </div>
  );
};
```

## 패널 레이아웃 구성

[React](/activereportsjs/docs/DeveloperGuide/ActiveReportsJSViewer/Integration/React-Component), [Angular](/activereportsjs/docs/DeveloperGuide/ActiveReportsJSViewer/Integration/Angular-Component), [Vue](/activereportsjs/docs/DeveloperGuide/ActiveReportsJSViewer/Integration/Vue-Component) 래퍼와 [Report Viewer]에 전달되는 `options` 객체에서 사용할 수 있는 **`PanelsLayout`** 속성입니다. [Viewer 생성자](/activereportsjs/api/classes/ReportViewer.Viewer#constructor)는 **검색**, **내보내기**, **문서 맵** 및 **매개변수** 패널의 위치를 제어합니다.
기본적으로 이러한 패널과 해당 도구모음 버튼은 뷰어 인터페이스의 **왼쪽**에 나타납니다. **오른쪽**으로 이동하려면 `PanelsLayout` 속성을 `sidebar`로 설정하십시오. 이 설정은 패널과 열려 있는 버튼을 모두 오른쪽으로 이동합니다.

### 매개변수 패널 위치 구성

`ParameterPanelLocation` 속성을 사용하여 **매개변수 패널**의 위치를 제어할 수 있습니다. 이 속성은 [React](/activereportsjs/docs/DeveloperGuide/ActiveReportsJSViewer/Integration/React-Component), [Angular](/activereportsjs/docs/DeveloperGuide/ActiveReportsJSViewer/Integration/Angular-Component) 및 [Vue](/activereportsjs/docs/DeveloperGuide/ActiveReportsJSViewer/Integration/Vue-Component) 래퍼에서 사용할 수 있습니다. 순수 자바스크립트 애플리케이션에서는 [Viewer 생성자]에 전달되는 `option` 객체를 통해 설정할 수 있습니다.

* **`auto`** – 보고서에서 [사용자 정의 매개변수 보기](/activereportsjs/docs/ReportAuthorGuide/Report-Parameters/매개변수-보기)를 사용하는 경우 매개변수 패널이 뷰어의 **상단**에 나타납니다. 그렇지 않으면 **왼쪽**에 나타납니다.
* **`default`** – 매개변수 패널은 위에서 설명한 `PanelsLayout` 설정에 따라 뷰어의 **왼쪽** 또는 **오른쪽**에 표시됩니다.
* **`top`** – 매개변수 패널이 뷰어의 **상단**에 고정됩니다.
* **`bottom`** – 매개변수 패널이 뷰어의 **하단**에 고정됩니다.

## 도구 모음 및 사이드바 교체

**Viewer** 컴포넌트의 `toolbarVisible` 및 `sidebarVisible` 속성을 사용하여 기본 도구 모음과 사이드바를 숨길 수 있습니다. 이러한 속성은 [React](/activereportsjs/docs/DeveloperGuide/ActiveReportsJSViewer/Integration/React-Component), [Angular](/activereportsjs/docs/DeveloperGuide/ActiveReportsJSViewer/Integration/Angular-Component) 및 [Vue](/activereportsjs/docs/DeveloperGuide/ActiveReportsJSViewer/Integration/Vue-Component) 래퍼에서 사용할 수 있습니다.
이 접근 방식은 내장된 뷰어 인터페이스를 [공개 API](/activereportsjs/api/classes/ReportViewer.Viewer)를 통해 뷰어 함수를 호출하는 **사용자 정의 UI**로 대체하려는 경우에 유용합니다.

## 관련 항목

* [라이브 데모](/activereportsjs/demos/features/viewer-customization-toolbar)
* [사용자 인터페이스](/activereportsjs/docs/DeveloperGuide/ActiveReportsJSViewer/Interface-Elements)
* [Angular 컴포넌트](/activereportsjs/docs/DeveloperGuide/ActiveReportsJSViewer/Integration/Angular-Component)
* [React 컴포넌트](/activereportsjs/docs/DeveloperGuide/ActiveReportsJSViewer/Integration/React-Component)
* [Vue 컴포넌트](/activereportsjs/docs/DeveloperGuide/ActiveReportsJSViewer/Integration/Vue-Component)
* [순수 JavaScript 통합](/activereportsjs/docs/DeveloperGuide/ActiveReportsJSViewer/Integration/VanillaJS)