# Data Zoom

대상 차트의 표시 범위를 슬라이더로 바꿉니다.

Canonical: https://chart.syidax.com/ko/docs/components/data-zoom/

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

## sy-data-zoom

넓은 데이터 범위에서 관심 구간을 선택하게 하세요.

독립 데이터 차트가 아닙니다. 대상 차트와 같은 문서에 두고 for에 고유 id를 지정하세요.

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

| 입력 | 데이터 설명 |
| --- | --- |
| `for` | 연결할 대상 차트의 id입니다. |
| `showLabels` | 양끝의 범위 레이블 표시 여부입니다. |
| `axis` | 대상의 어떤 축을 제어할지 지정합니다. |

- [Components에서 실행하기](https://chart.syidax.com/charts/data-zoom) — 옵션 변경과 프레임워크별 코드
- [공통 설치와 연결](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-data-zoom.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-data-zoom",
      "props": {
        "for": "chart-target",
        "showLabels": true,
        "width": 640,
        "height": 36
      }
    }
  ];
  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', 'data-zoom 예제 차트');
    return element;
  });
  container.replaceChildren(...elements);
  const chart = elements.at(-1);
  const onEvent = event => {
    console.log('rangeChange', event.detail);
  };
  chart.addEventListener('rangeChange', onEvent);
  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();
    chart.removeEventListener('rangeChange', onEvent);
    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 프로퍼티로 전달 |
| 타입 | `DataZoomTargetElement \| null` |
| 기본값 | `undefined` |

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

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

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

### orientation

'horizontal' drives the x window, 'vertical' the y window.

| 항목 | 값 |
| --- | --- |
| 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

대상의 어떤 축을 제어할지 지정합니다.

| 항목 | 값 |
| --- | --- |
| 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` |
| 기본값 | `28` |

<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

양끝의 범위 레이블 표시 여부입니다.

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

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

### format

Label formatter (default: up to two decimals).

| 항목 | 값 |
| --- | --- |
| JavaScript 프로퍼티 | `format` |
| HTML attribute | 객체·배열·콜백은 JavaScript 프로퍼티로 전달 |
| 타입 | `(value: number) => string` |
| 기본값 | `undefined` |

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

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

### disabled

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

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

<a id="events"></a>

## Events

<a id="event-rangeChange"></a>

### rangeChange

Every window the slider shows: gestures / keys ('slider'), the chart moving on its own ('chart'), `setWindow` ('api').

이벤트 이름: `rangeChange`. 대소문자를 구분합니다. payload는 `CustomEvent<DataZoomRangeChangeEventDetail>`의 `detail`에서 읽습니다.

```javascript
chart.addEventListener('rangeChange', event => {
  console.log(event.detail); // DataZoomRangeChangeEventDetail
});
```

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

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

## Methods

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

### refresh

Re-read the target's extent and window (the slider also does this on the target's `rendered` and `zoomChange`).

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

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

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

### setWindow

Set the window from script (`null` = the full extent); the chart follows with `zoomChange.source = 'api'`.

```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) — 타입 정의