sy-visual-map

Visual Map

값에 따른 색상·크기와 선택 범위를 제어합니다.

sy-visual-map

연속 색상 범례 또는 구간별 필터를 차트와 연결하세요.

대상이 지원하는 dimension을 선택하세요. 이 예제는 Heatmap의 value와 연결합니다.

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

입력	데이터 설명
`for`	대상 차트의 id입니다.
`dimension`	값을 읽을 데이터 차원입니다.
`type`	continuous 또는 piecewise입니다.
`min`	max와 함께 값 범위를 지정합니다.

Components에서 실행하기
옵션 변경과 프레임워크별 코드
공통 설치와 연결

전체 적용 예제

html

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

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

  // Pro: 앱 시작 시 발급받은 인증서로 registerLicense를 완료하세요.
  // 홈페이지 미리보기의 인증서는 고객 앱에서 사용하지 않습니다.
  const specs = [
    {
      "tag": "sy-heatmap",
      "id": "chart-target",
      "props": {
        "data": [
          {
            "x": 0,
            "y": 0,
            "value": 10
          },
          {
            "x": 1,
            "y": 0,
            "value": 27
          },
          {
            "x": 2,
            "y": 0,
            "value": 44
          },
          {
            "x": 3,
            "y": 0,
            "value": 61
          },
          {
            "x": 4,
            "y": 0,
            "value": 78
          },
          {
            "x": 5,
            "y": 0,
            "value": 95
          },
          {
            "x": 0,
            "y": 1,
            "value": 22
          },
          {
            "x": 1,
            "y": 1,
            "value": 39
          },
          {
            "x": 2,
            "y": 1,
            "value": 56
          },
          {
            "x": 3,
            "y": 1,
            "value": 73
          },
          {
            "x": 4,
            "y": 1,
            "value": 90
          },
          {
            "x": 5,
            "y": 1,
            "value": 17
          },
          {
            "x": 0,
            "y": 2,
            "value": 34
          },
          {
            "x": 1,
            "y": 2,
            "value": 51
          },
          {
            "x": 2,
            "y": 2,
            "value": 68
          },
          {
            "x": 3,
            "y": 2,
            "value": 85
          },
          {
            "x": 4,
            "y": 2,
            "value": 12
          },
          {
            "x": 5,
            "y": 2,
            "value": 29
          },
          {
            "x": 0,
            "y": 3,
            "value": 46
          },
          {
            "x": 1,
            "y": 3,
            "value": 63
          },
          {
            "x": 2,
            "y": 3,
            "value": 80
          },
          {
            "x": 3,
            "y": 3,
            "value": 97
          },
          {
            "x": 4,
            "y": 3,
            "value": 24
          },
          {
            "x": 5,
            "y": 3,
            "value": 41
          },
          {
            "x": 0,
            "y": 4,
            "value": 58
          },
          {
            "x": 1,
            "y": 4,
            "value": 75
          },
          {
            "x": 2,
            "y": 4,
            "value": 92
          },
          {
            "x": 3,
            "y": 4,
            "value": 19
          },
          {
            "x": 4,
            "y": 4,
            "value": 36
          },
          {
            "x": 5,
            "y": 4,
            "value": 53
          }
        ],
        "height": 280,
        "width": 640
      }
    },
    {
      "id": "example-chart",
      "tag": "sy-visual-map",
      "props": {
        "for": "chart-target",
        "type": "continuous",
        "dimension": "value",
        "min": 0,
        "max": 100,
        "calculable": true,
        "color": ["#eee6ff", "#8263d9", "#34265d"],
        "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', 'visual-map 예제 차트');
    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>

Properties

type

continuous 또는 piecewise입니다.

항목	값
JavaScript 프로퍼티	`type`
HTML attribute	`type`
타입	`VisualMapType`
기본값	`'continuous'`
허용값	`continuous`, `piecewise`

VisualMapType
타입 정의

min

max와 함께 값 범위를 지정합니다.

항목	값
JavaScript 프로퍼티	`min`
HTML attribute	`min`
타입	`number`
기본값	`undefined`

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

max

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

항목	값
JavaScript 프로퍼티	`max`
HTML attribute	`max`
타입	`number`
기본값	`undefined`

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

for

대상 차트의 id입니다.

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

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

target

the chart element to colour (the script-set alternative to for).

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

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

VisualMapTargetElement
타입 정의

dimension

값을 읽을 데이터 차원입니다.

항목	값
JavaScript 프로퍼티	`dimension`
HTML attribute	객체·배열·콜백은 JavaScript 프로퍼티로 전달
타입	`VisualMapDimension`
기본값	`undefined`
타입에 포함된 리터럴	`x`, `y`, `value`, `z`, `index`

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

VisualMapDimension
타입 정의

sizeRange

visualMap → size: the mark radius (px) at the low / high end of the map ("4,16" as an attribute); the legend shows size ticks.

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

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

sizeDimension

the dimension the size reads (default: dimension).

항목	값
JavaScript 프로퍼티	`sizeDimension`
HTML attribute	객체·배열·콜백은 JavaScript 프로퍼티로 전달
타입	`VisualMapDimension`
기본값	`undefined`
타입에 포함된 리터럴	`x`, `y`, `value`, `z`, `index`

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

VisualMapDimension
타입 정의

outOfRangeSize

the radius of out-of-range values (default: the low end of sizeRange).

항목	값
JavaScript 프로퍼티	`outOfRangeSize`
HTML attribute	`out-of-range-size`
타입	`number`
기본값	`undefined`

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

pieces

Piecewise: explicit pieces ([{ min, max, label, color }] or [{ value }]; a JSON string as an attribute). Wins over categories / splitNumber.

항목	값
JavaScript 프로퍼티	`pieces`
HTML attribute	객체·배열·콜백은 JavaScript 프로퍼티로 전달
타입	`ReadonlyArray<VisualMapPieceInput> \| string`
기본값	`undefined`

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

VisualMapPieceInput
타입 정의

splitNumber

Piecewise: equal intervals over [min, max] when no pieces / categories are given (default 5).

항목	값
JavaScript 프로퍼티	`splitNumber`
HTML attribute	`split-number`
타입	`number`
기본값	`5`

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

selectedMode

Piecewise: 'multiple' toggles pieces independently, 'single' keeps one piece selected.

항목	값
JavaScript 프로퍼티	`selectedMode`
HTML attribute	`selected-mode`
타입	`VisualMapSelectedMode`
기본값	`'multiple'`
허용값	`multiple`, `single`

VisualMapSelectedMode
타입 정의

selected

Piecewise: the initial / controlled selection (null = every piece); changing it reports selectionChanged with source 'api'.

항목	값
JavaScript 프로퍼티	`selected`
HTML attribute	객체·배열·콜백은 JavaScript 프로퍼티로 전달
타입	`ReadonlyArray<boolean> \| null`
기본값	`undefined`

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

itemWidth

Piecewise: the swatch size of a piece (ECharts itemWidth / itemHeight).

항목	값
JavaScript 프로퍼티	`itemWidth`
HTML attribute	`item-width`
타입	`number`
기본값	`20`

itemHeight

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

항목	값
JavaScript 프로퍼티	`itemHeight`
HTML attribute	`item-height`
타입	`number`
기본값	`14`

color

The ramp: a scheme name (viridis, blues, rdbu, …), a comma list (#eff6ff,#1d4ed8), a colour array, or [t, colour] stops.

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

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

VisualMapColorInput
타입 정의

outOfRangeColor

The colour of values outside the selected range (and of non-finite values).

항목	값
JavaScript 프로퍼티	`outOfRangeColor`
HTML attribute	`out-of-range-color`
타입	`string`
기본값	`'#d1d5db'`

orientation

'horizontal' runs min → max left to right, 'vertical' bottom to top.

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

DataZoomOrientation
타입 정의

width

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

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

height

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

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

calculable

Show the two range handles: the selected range can be dragged, keyed and set from script.

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

range

The selected range (null / unset = the whole domain); changing it reports rangeChange with source 'api'.

항목	값
JavaScript 프로퍼티	`range`
HTML attribute	객체·배열·콜백은 JavaScript 프로퍼티로 전달
타입	`VisualMapRange \| readonly [number, number] \| null`
기본값	`undefined`

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

VisualMapRange
타입 정의

precision

Fixed decimals for the labels (unset = up to two, trimmed).

항목	값
JavaScript 프로퍼티	`precision`
HTML attribute	`precision`
타입	`number`
기본값	`undefined`

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

format

Label formatter (a property — functions cannot be attributes).

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

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

text

End captions instead of the numbers: "High,Low" (max end first — ECharts text).

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

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

showLabels

Show the end labels, and the handle labels while a range is selected.

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

stepFraction

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

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

minRangePx

The narrowest selectable range, in track pixels (default 8).

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

realtime

Report the frames of a drag (live: true); off = only the release reports.

항목	값
JavaScript 프로퍼티	`realtime`
HTML attribute	`realtime`
타입	`boolean`
기본값	`true`

disabled

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

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

Events

rangeChange

Every range the control shows: a handle drag / key ('control', with live frames), setRange or the range prop ('api').

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

javascript

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

VisualMapRangeChangeEventDetail
타입 정의

selectionChanged

a piecewise map's selection changed (a piece toggled: 'control'; setSelected / the selected prop: 'api').

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

javascript

chart.addEventListener('selectionChanged', event => {
  console.log(event.detail); // VisualMapSelectionChangeEventDetail
});

VisualMapSelectionChangeEventDetail
타입 정의

Methods

refresh

Re-read the bound chart's extent (while min / max are unset) and push the binding; the control also does this on the chart's rendered.

typescript

refresh(): Promise<void>

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

setRange

Select a range from script (null = the whole domain); reports rangeChange with source 'api' when it changed.

typescript

setRange(range: VisualMapRange | readonly [number, number] | null): Promise<VisualMapRange | null>

인수	타입	필수 여부
`range`	`VisualMapRange \| readonly [number, number] \| null`	필수

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

VisualMapRange
타입 정의

getRange

The resolved range.

typescript

getRange(): Promise<VisualMapRange | null>

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

VisualMapRange
타입 정의

setSelected

piecewise: select pieces from script (null = every piece); reports selectionChanged with source 'api'.

typescript

setSelected(selected: ReadonlyArray<boolean> | null): Promise<boolean[] | null>

인수	타입	필수 여부
`selected`	`ReadonlyArray<boolean> \| null`	필수

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

getSelected

piecewise: the per-piece selection (null = every piece).

typescript

getSelected(): Promise<boolean[] | null>

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

togglePiece

piecewise: toggle one piece the way a click does (reports source 'api').

typescript

togglePiece(index: number): Promise<boolean[] | null>

인수	타입	필수 여부
`index`	`number`	필수

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

getSpec

The resolved spec plus the selection: continuous → domain, stops, space, out-of-range colour, calculable, precision + range; piecewise → the pieces + selected.

typescript

getSpec(): Promise<VisualMapSnapshot>

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

VisualMapSnapshot
타입 정의

colorAt

The colour of a value on this map: the ramp / piece colour inside the selection, outOfRangeColor outside it.

typescript

colorAt(value: number | string): Promise<string>

인수	타입	필수 여부
`value`	`number \| string`	필수

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