데이터포인트 선택(Selection)

선택을 켜면 사용자가 데이터포인트를 클릭해 고를 수 있다. 선택 상태는 포인터가 벗어나도 남고, 포인터를 올렸을 때의 강조 효과(hover)와 따로 동작한다. bar · circlebar · pie 시리즈와 pictogram 모듈의 pictorialbar 시리즈에서 쓸 수 있다.

v1.5.2부터 selection 설정과 chart.selectAll · unselectAll API를 쓸 수 있다. 그 전 버전의 설정은 아래 '이전 옵션' 절을 참조한다.

선택 켜기

시리즈의 selection을 true로 지정한다.

const config = {
    series: [
        { type: 'bar', name: '매출', selection: true, data: [['1월', 182], ['2월', 175], ['3월', 198]] },
        { type: 'bar', name: '비용', selection: true, data: [['1월', 120], ['2월', 131], ['3월', 126]] },
    ],
};

위 config를 RealChart.createChart에 전달해 차트를 만든다. 차트 생성 방법은 개발 가이드를 참조한다.

Try Selection (opens in a new tab)

기본 조작

• 클릭하면 기존 선택을 해제하고 하나만 선택한다. 단독 선택된 포인트를 다시 클릭하면 해제된다.
• Shift · Ctrl(Windows) · Cmd(macOS) 같은 보조 키(modifier)를 누른 채 클릭하면 기존 선택을 유지하면서 해당 포인트의 선택 상태를 반대로 바꾼다(toggle).
• 터치에서 짧게 누르기(tap)는 클릭과 같고, 길게 누르면 보조 키 + 클릭과 같다.
• plot 영역의 빈 곳이나 제목 · 축 라벨을 클릭하거나 tap하면 전체 선택이 해제된다. 선택을 쓰지 않는 시리즈의 포인트를 누르면 해제되지 않는다.

가장 마지막에 선택한 포인트는 focus 포인트가 되어 다른 선택 포인트와 구별해 표시된다. 선택은 시리즈별이 아니라 차트 전체에서 관리되므로 여러 시리즈의 포인트를 함께 선택할 수 있다(보조 키 + 클릭, 길게 누르기, selectAll). focus 포인트는 차트에 하나다.

시리즈의 onPointClick이 true를 리턴하면 기본 동작이 취소되어 선택도 바뀌지 않는다. 툴팁이 고정된 포인트를 다시 tap할 때, 포인트 라벨을 누르거나 끌고 놓을 때(줌 드래그 등)의 규칙은 selection.visible을, 툴팁이 언제 닫히는지는 tooltip.followTouch를 참조한다.

상태별 스타일

선택 상태마다 스타일을 지정할 수 있다.

const config = {
    title: '월별 매출',
    series: {
        type: 'bar',
        name: '매출',
        selection: {
            visible: true,
            style: { stroke: '#334155', strokeWidth: 1.5 },
            unselectedStyle: { opacity: 0.3 },
            focus: {
                style: { stroke: '#4F46E5', strokeWidth: 2.5 },
            },
        },
        data: [['1월', 182], ['2월', 175], ['3월', 198]],
    },
};

위 설정으로 1월을 선택한 뒤 보조 키 + 클릭으로 3월을 추가 선택한 화면이다. 3월이 focus가 되고 선택되지 않은 2월은 흐리게 표시된다. focus 포인트의 그림자는 기본 표시이고, 지정한 스타일셋은 테두리만 바꾼다.

• 범례나 줌으로 선택된 포인트가 모두 화면에서 사라져도 선택 상태는 유지되지만, 나머지 포인트의 흐리기는 풀린다. 선택된 포인트가 다시 보이면 흐리기도 다시 적용된다.
• 흐리기를 끄려면 unselectedStyle: { opacity: 1 }을 지정한다.
• focus 표시를 끄려면 focus: false를 지정한다. focus 포인트도 선택된 포인트와 같은 모양이 된다.
• 스타일셋으로 지정하면 기본 표시 위에 지정한 속성만 덮어쓰고, class 이름으로 지정하면 그 상태의 기본 표시 대신 지정한 class가 모양을 정한다. 두 형식을 섞을 때와 hover와의 우선순위는 selection 설명을 참조한다.

API로 선택하기

클릭하지 않고 코드로 선택을 바꿀 때는 chart.selectAll과 chart.unselectAll을 쓴다. 데이터포인트 객체를 찾을 필요 없이 x값으로 고른다.

chart.selectAll('1월');                                  // 모든 시리즈에서 x가 '1월'인 포인트
chart.selectAll(['1월', '3월']);                         // 모든 시리즈의 1월 · 3월
chart.selectAll({ 매출: ['1월', '3월'] });               // 매출 시리즈의 1월 · 3월
chart.selectAll({ 매출: ['1월', '3월'], 비용: '2월' });   // 시리즈마다 다른 x
 
chart.unselectAll('1월');                                // 모든 시리즈의 '1월' 해제
chart.unselectAll();                                     // 전체 해제

대상은 x값 하나, x값 배열, 또는 시리즈 name을 키로 한 객체로 지정한다. 시리즈를 정하지 않으면 선택을 쓰는 모든 시리즈에서 고른다. x값이 문자열이면 x축이 해석하는 값(category 이름, 날짜 문자열 등)으로, 숫자이면 포인트의 x축 값(xValue)으로 찾는다. 그래서 문자열 category에서는 숫자 1로 두 번째 category를 고를 수 있고, 이름이 '11'인 category는 문자열 '11'로 지정한다. time 축 · pie 등 자세한 규칙은 SelectX를 참조한다.

selectAll은 기존 선택에 더하고, 마지막으로 고른 포인트가 focus가 된다. 선택을 바꾸려면 unselectAll()로 먼저 비운다. 화면에 그려진 포인트만 고르므로 숨긴 시리즈·그룹·포인트, 값이 없는 포인트, x축 확대 범위 밖의 포인트는 건너뛴다. unselectAll은 인자를 주지 않았을 때만 전체를 해제하고, null · undefined를 넘기면 아무것도 하지 않는다.

호출 시점

포인트는 렌더링을 준비할 때 만들어지므로, 그 전에 호출하면 고를 포인트가 없어 아무것도 선택되지 않는다. 첫 화면에서 고르려면 createChart의 callback 안에서 호출하고, data를 바꾼 뒤에는 chart.render() 다음에 호출한다.

RealChart.createChart(document, 'realchart', config, true, ({ chart }) => {
    chart.selectAll('1월');
});

클릭으로 선택하지 않게 하기

API로만 선택하려면 general.clickable을 false로 둔다. 차트의 클릭 기능이 모두 꺼지므로(범례 · onPointClick · 어노테이션 등, 옵션 설명 참조) 줌을 함께 쓰면 Reset Zoom 버튼도 눌리지 않는다는 점에 주의한다. 시리즈의 interactive를 false로 두어도 그 시리즈는 클릭으로 선택되지 않지만, hover와 툴팁도 함께 꺼진다.

데이터포인트 객체로 다루기

포인트 객체를 이미 갖고 있으면 chart.selection의 select · add · toggle · unselect · clear를 쓴다. 현재 선택은 selectedPoints, focus 포인트는 focusedPoint로 읽는다. 시리즈에서 x가 같은 포인트를 모두 얻으려면 series.getPointsAt을 쓴다.

선택 이벤트

선택이 바뀔 때 다른 처리를 하려면 general.onSelectionChanged와 general.onFocusChanged를 지정한다. 앞의 것은 포인트가 새로 선택되거나 해제될 때, 뒤의 것은 focus 포인트가 바뀔 때 호출된다. 마우스 · 터치로 바꾸든 API로 바꾸든 같은 이벤트가 온다.

const config = {
    general: {
        onSelectionChanged: (args) => {
            // 새로 선택되거나 선택이 해제된 포인트가 있는 시리즈마다 한 번 호출된다.
            console.log(args.series.name, args.selectedPoints.map(p => p.x));
        },
        onFocusChanged: (args) => {
            // 선택이 모두 해제되면 point는 null이다.
            console.log(args.point ? args.point.x : '선택 없음');
        },
    },
};

selectAll · unselectAll로 여러 포인트를 한 번에 바꿔도 onSelectionChanged는 바뀐 시리즈마다 한 번, onFocusChanged는 focus가 바뀔 때만 한 번 호출된다. 자세한 호출 조건은 chart.selectAll 설명을 참조한다.

사용자가 고르지 않아도 선택이 정리될 수 있다. data를 새로 지정하거나 선택된 포인트를 지우거나(removePoint 등) 선택을 끄면, 다음 렌더링에서 남은 선택이 정리되고 이때도 onSelectionChanged가 호출된다. updatePoint처럼 값만 바꾸면 선택은 그대로다.

이전 옵션

v1.5.1의 selectable · selectStyle · focusStyle은 v1.5.2부터 selection.visible · selection.style · selection.focus.style로도 지정할 수 있다. 두 방식을 모두 지원하며, 둘 다 지정하면 selection이 우선한다. 이전 옵션에 준 class는 v1.5.1처럼 기본 표시 위에 더해진다. 같은 class를 selection으로 옮기면 기본 표시 대신 그 class가 모양을 정하므로 모양이 달라질 수 있다. 이전 옵션은 v1.6.0부터 deprecated되지만 v1.6.0에서도 그대로 동작한다. 새로 작성하는 설정에는 selection을 쓴다.

설정

시리즈의 selection으로 설정한다.

See Also

• 툴팁(Tooltip)과 Hovering
• 시리즈 selection
• Selection API