# Navigator

전체 데이터의 축약된 흐름 위에서 범위를 고릅니다.

Canonical: https://chart.syidax.com/ko/docs/components/navigator/

<a id="overview"></a>

## sy-navigator

확대된 화면과 전체 맥락을 함께 제공하세요.

Navigator의 for는 같은 문서의 대상 차트를 가리킵니다. 샘플링된 미리보기는 원시 데이터와 구분하세요.

기본 차트 등급: Community. 추가 렌더러·커스텀 브랜딩 등 기능의 권한은 별도입니다.

| 입력 | 데이터 설명 |
| --- | --- |
| `for` | 대상 차트의 id입니다. |
| `sampling` | minmax 또는 lttb로 데이터를 축약합니다. |
| `series` | 미리보기에 사용할 시리즈입니다. |

- [Components에서 실행하기](https://chart.syidax.com/charts/navigator) — 옵션 변경과 프레임워크별 코드
- [공통 설치와 연결](https://chart.syidax.com/ko/docs/getting-started.md)

<a id="example"></a>

## 전체 적용 예제

```html
<div id="chart-container" style="width: 100%; min-width: 0;"></div>

<script type="module">
  import { defineCustomElement as define0 } from '@syidax/advanced/components/sy-line-chart.js';
  import { defineCustomElement as define1 } from '@syidax/advanced/components/sy-navigator.js';
  define0();
  define1();

  const specs = [
    {
      "tag": "sy-line-chart",
      "id": "chart-target",
      "props": {
        "engine": "standard",
        "series": [
          {
            "name": "Organic",
            "color": "#8263d9",
            "values": [24, 29, 27, 38, 43, 40, 52, 58, 53, 68, 76, 84]
          },
          {
            "name": "Direct",
            "color": "#239c91",
            "values": [15, 19, 17, 24, 22, 29, 32, 30, 39, 42, 40, 51]
          },
          {
            "name": "Referral",
            "color": "#e99954",
            "values": [8, 11, 9, 15, 13, 19, 17, 23, 22, 28, 25, 33]
          }
        ],
        "xAxis": {
          "kind": "category",
          "categories": ["1월", "2월", "3월", "4월", "5월", "6월", "7월", "8월", "9월", "10월", "11월", "12월"]
        },
        "yAxis": {
          "kind": "linear",
          "min": 0
        },
        "zoom": {
          "enabled": true
        },
        "height": 280,
        "width": 640
      }
    },
    {
      "id": "example-chart",
      "tag": "sy-navigator",
      "props": {
        "for": "chart-target",
        "sampling": "minmax",
        "width": 640,
        "height": 64
      }
    }
  ];
  const container = document.querySelector('#chart-container');
  const elements = specs.map(({ tag, id, props }) => {
    const element = document.createElement(tag);
    element.id = id;
    Object.assign(element, props);
    element.setAttribute('aria-label', 'navigator 예제 차트');
    return element;
  });
  container.replaceChildren(...elements);
  const chart = elements.at(-1);
  const observer = new ResizeObserver(([entry]) => {
    const width = Math.max(160, Math.floor(entry.contentRect.width));
    elements.forEach(element => { element.width = width; });
  });
  observer.observe(container);

  // SPA에서는 화면이 해제될 때 이 함수를 호출하세요.
  function disposeChart() {
    observer.disconnect();
    container.replaceChildren();
  }
</script>
```

<a id="props"></a>

## Properties

<a id="property-for"></a>

### for

대상 차트의 id입니다.

| 항목 | 값 |
| --- | --- |
| JavaScript 프로퍼티 | `for` |
| HTML attribute | `for` |
| 타입 | `string` |
| 기본값 | `undefined` |

undefined는 이 속성을 명시하지 않은 상태입니다. 실제 표시 값은 차트 종류와 다른 설정에 따라 결정될 수 있습니다.

<a id="property-target"></a>

### target

The chart element to drive (the script-set alternative to `for`).

| 항목 | 값 |
| --- | --- |
| JavaScript 프로퍼티 | `target` |
| HTML attribute | 객체·배열·콜백은 JavaScript 프로퍼티로 전달 |
| 타입 | `NavigatorTargetElement \| null` |
| 기본값 | `undefined` |

undefined는 이 속성을 명시하지 않은 상태입니다. 실제 표시 값은 차트 종류와 다른 설정에 따라 결정될 수 있습니다.

- [NavigatorTargetElement](https://chart.syidax.com/ko/docs/types/NavigatorTargetElement.md) — 타입 정의

<a id="property-orientation"></a>

### orientation

'horizontal' drives the x window (preview along x), 'vertical' the y window (preview along y).

| 항목 | 값 |
| --- | --- |
| JavaScript 프로퍼티 | `orientation` |
| HTML attribute | `orientation` |
| 타입 | `DataZoomOrientation` |
| 기본값 | `'horizontal'` |
| 허용값 | `vertical`, `horizontal` |

- [DataZoomOrientation](https://chart.syidax.com/ko/docs/types/DataZoomOrientation.md) — 타입 정의

<a id="property-axis"></a>

### axis

Which axis of the target (id or slot index); default: the primary axis of the orientation.

| 항목 | 값 |
| --- | --- |
| JavaScript 프로퍼티 | `axis` |
| HTML attribute | 객체·배열·콜백은 JavaScript 프로퍼티로 전달 |
| 타입 | `CartesianAxisId` |
| 기본값 | `undefined` |

undefined는 이 속성을 명시하지 않은 상태입니다. 실제 표시 값은 차트 종류와 다른 설정에 따라 결정될 수 있습니다.

- [CartesianAxisId](https://chart.syidax.com/ko/docs/types/CartesianAxisId.md) — 타입 정의

<a id="property-width"></a>

### width

차트의 너비를 px 단위로 지정합니다. 컨테이너 너비가 변하는 앱에서는 ResizeObserver에서 width를 갱신하세요.

| 항목 | 값 |
| --- | --- |
| JavaScript 프로퍼티 | `width` |
| HTML attribute | `width` |
| 타입 | `number` |
| 기본값 | `640` |

<a id="property-height"></a>

### height

차트의 높이를 px 단위로 지정합니다. 축, 제목과 범례가 차지하는 공간을 함께 고려하세요.

| 항목 | 값 |
| --- | --- |
| JavaScript 프로퍼티 | `height` |
| HTML attribute | `height` |
| 타입 | `number` |
| 기본값 | `60` |

<a id="property-minRangePx"></a>

### minRangePx

The narrowest window, in track pixels (default 8).

| 항목 | 값 |
| --- | --- |
| JavaScript 프로퍼티 | `minRangePx` |
| HTML attribute | `min-range-px` |
| 타입 | `number` |
| 기본값 | `8` |

<a id="property-stepFraction"></a>

### stepFraction

Fraction of the window one arrow key moves (default 0.1).

| 항목 | 값 |
| --- | --- |
| JavaScript 프로퍼티 | `stepFraction` |
| HTML attribute | `step-fraction` |
| 타입 | `number` |
| 기본값 | `0.1` |

<a id="property-showLabels"></a>

### showLabels

Show the window's min / max next to the handles while zoomed.

| 항목 | 값 |
| --- | --- |
| JavaScript 프로퍼티 | `showLabels` |
| HTML attribute | `show-labels` |
| 타입 | `boolean` |
| 기본값 | `true` |

<a id="property-disabled"></a>

### disabled

HTML attribute 또는 JavaScript 프로퍼티로 설정합니다. 타입: boolean.

| 항목 | 값 |
| --- | --- |
| JavaScript 프로퍼티 | `disabled` |
| HTML attribute | `disabled` |
| 타입 | `boolean` |
| 기본값 | `false` |

<a id="property-series"></a>

### series

미리보기에 사용할 시리즈입니다.

| 항목 | 값 |
| --- | --- |
| JavaScript 프로퍼티 | `series` |
| HTML attribute | 객체·배열·콜백은 JavaScript 프로퍼티로 전달 |
| 타입 | `number \| string` |
| 기본값 | `undefined` |

undefined는 이 속성을 명시하지 않은 상태입니다. 실제 표시 값은 차트 종류와 다른 설정에 따라 결정될 수 있습니다.

<a id="property-sampling"></a>

### sampling

minmax 또는 lttb로 데이터를 축약합니다.

| 항목 | 값 |
| --- | --- |
| JavaScript 프로퍼티 | `sampling` |
| HTML attribute | `sampling` |
| 타입 | `NavigatorSampling` |
| 기본값 | `'minmax'` |
| 허용값 | `minmax`, `lttb` |

- [NavigatorSampling](https://chart.syidax.com/ko/docs/types/NavigatorSampling.md) — 타입 정의

<a id="methods"></a>

## Methods

<a id="method-refresh"></a>

### refresh

Re-read the chart's extent, data and window (also done on the chart's `rendered`).

```typescript
refresh(): Promise<void>
```

반환 타입: `Promise<void>`. 요소 등록이 끝난 뒤 메서드를 호출하고 Promise 결과를 await로 기다리세요.

<a id="method-setWindow"></a>

### setWindow

Set the window from script (`null` = the full extent) through the inner slider.

```typescript
setWindow(window: CartesianZoomWindow | readonly [number, number] | null): Promise<CartesianZoomWindow | null>
```

| 인수 | 타입 | 필수 여부 |
| --- | --- | --- |
| `window` | `CartesianZoomWindow \| readonly [number, number] \| null` | 필수 |

반환 타입: `Promise<CartesianZoomWindow | null>`. 요소 등록이 끝난 뒤 메서드를 호출하고 Promise 결과를 await로 기다리세요.

- [CartesianZoomWindow](https://chart.syidax.com/ko/docs/types/CartesianZoomWindow.md) — 타입 정의

<a id="method-getWindow"></a>

### getWindow

비동기 메서드입니다. 아래 인수 타입과 반환 타입을 확인하세요.

```typescript
getWindow(): Promise<CartesianZoomWindow | null>
```

반환 타입: `Promise<CartesianZoomWindow | null>`. 요소 등록이 끝난 뒤 메서드를 호출하고 Promise 결과를 await로 기다리세요.

- [CartesianZoomWindow](https://chart.syidax.com/ko/docs/types/CartesianZoomWindow.md) — 타입 정의

<a id="method-getExtent"></a>

### getExtent

비동기 메서드입니다. 아래 인수 타입과 반환 타입을 확인하세요.

```typescript
getExtent(): Promise<ZoomExtent | null>
```

반환 타입: `Promise<ZoomExtent | null>`. 요소 등록이 끝난 뒤 메서드를 호출하고 Promise 결과를 await로 기다리세요.

- [ZoomExtent](https://chart.syidax.com/ko/docs/types/ZoomExtent.md) — 타입 정의