가이드
드릴다운(drilldown)

드릴다운(Drilldown)

드릴다운 패널

현재 드릴다운 된 상태를 표시하고 이동 시킬 수 있는 패널을 제공한다. 기본적으로 드릴다운 된 맵 이력을 표시하고 맵 이름을 클릭하면 해당 맵이 기준이 되는 상태로 되돌린다.

아래처럼 이전 단계로 이동하는 버튼을 대신 표시할 수도 있다.

사용법

  • 아래의 예제에서는 대한민국 시도/시군구 드릴다운을 구현한다.
    초기 상태에서 시도 지도가 표시되고, 시도를 클릭하면 해당 시도의 시군구 지도가 표시된다.
    다시 시도 지도로 돌아가려면 드릴다운 패널에서 시도 이름을 클릭하거나 이전 단계 버튼을 클릭한다.

지도 데이터 설정

{
    map: [
        {
            name: '시도',
            url: 'https://unpkg.com/realmap-collection/kr-sido-low.geo.json',
        },
        {
            name: '시군구',
            url: 'https://unpkg.com/realmap-collection/kr-sigun-low.geo.json',
        },
    ],
}
  • 드릴다운에 필요한 지도 데이터를 모두 map 옵션에 배열로 설정한다.
  • 지도에 고유한 식별자를 부여해야 한다. 이를 위해 name 속성을 사용한다.

클릭 이벤트 설정

{
    general: {
        clickAction: 'drilldown'
    },
}
  • 시도 지도를 클릭했을 때, 드릴다운하도록 설정하려면, general.clickAction 속성을 drilldown 으로 설정한다.

맵 시리즈 설정

{
    series: [
        {
            map: '시도',
            useMapData: true,
            style: {
                stroke: '#4f4f4f',
                fill: '#e7e7e7',
                strokeWidth: 0.5,
            },
            detail: {
                map: '시군구',
                useMapData: true,
                style: {
                    stroke: '#4f4f4f',
                    fill: '#e7e7e7',
                    strokeWidth: 0.5,
                },
                onPointClick: args => {
                    const mapChart = args.chart;
 
                    mapChart.drillup(mapChart.series);
                },
            }
        },
    ]
}
  • 하나의 맵 시리즈를 사용해서 드릴다운을 구현한다.
  • 맵 시리즈에 시도 지도의 데이터를 설정한다. map 속성에 시도 지도의 name을 지정한다.
  • 드릴다운 했을 때 나타나야 하는 시군구 지도를 위해, 맵 시리즈에 detail 속성을 설정한다.
    마찬가지로 map 속성에 시군구 지도의 name을 지정한다.
  • 시군구 지도를 클릭했을 때 다시 시도 지도로 돌아가도록 onPointClick 이벤트 핸들러를 설정한다.
    mapChart.drillup() 메서드를 호출해서 드릴업(Drillup) 한다.

본 예제에서는 useMapData 속성을 사용했는데, 이는 클릭 이벤트가 발생하려면 맵시리즈에 데이터가 바인딩되어야 하기 때문이다. 따라서 useMapData를 사용하지 않아도 된다. data나 dataUrl로 데이터를 바인딩해도 된다.

Drilldown

드릴다운 패널 표시 방식

드릴다운한 뒤 클릭한 지역의 하위 지역만 표시하려면 drilldown.scope를 'selected'로 지정한다.

{
    series: [
        {
            map: '시도',
            useMapData: true,
            drilldown: {
                scope: 'selected'
            },
            detail: {
                map: '시군구',
                useMapData: true,
            }
        },
    ]
}
  • 기본값 'all'은 시군구 지도 전체를 표시한다. 클릭한 시도로 확대되지만 이웃 시도의 시군구도 함께 보인다.
  • 'selected'로 지정하면 클릭한 시도의 시군구만 남는다.
    하위 지역은 시군구 지도의 parentKey(기본값 rm-parent) 속성으로 찾고, 그 속성이 없으면 지역 id의 접두어로 찾는다.
  • 'selected'일 때는 드릴다운 패널에 시리즈 이름 대신 들어간 지역 이름이 표시된다.
  • 하위 지역이 하나도 없는 지역은 드릴다운하지 않는다.
  • chart.drilldown(chart.series)처럼 지역을 지정하지 않고 호출하면 기준이 될 지역이 없으므로 시군구 지도 전체를 표시한다.

확대한 뒤 교체하는 전환

클릭한 지역으로 확대·이동하는 모습을 먼저 보여주고 나서 하위 지도로 바꾸려면 drilldown.transition을 'zoom'으로 지정한다.

{
    series: [
        {
            map: '시도',
            useMapData: true,
            drilldown: {
                transition: 'zoom',
                duration: 500,
                fillRatio: 0.85
            },
            detail: {
                map: '시군구',
                useMapData: true,
            }
        },
    ]
}
  • 기본값 'none'은 하위 지도로 곧바로 바꾼다.
  • 'zoom'으로 지정하면 시도 지도가 클릭한 지역을 향해 확대·이동하고, 그 움직임이 끝난 뒤에 시군구 지도로 바뀐다.
  • duration은 확대·이동에 걸리는 시간(ms)이고, fillRatio는 클릭한 지역이 화면을 채우는 비율이다.

API로 드릴다운·드릴업

chart.drilldown()과 chart.drillup()으로 코드에서 단계를 옮길 수 있다. 지역 클릭이나 드릴다운 패널로 할 수 있는 이동만 받는다.

아래 예시는 시리즈를 이름으로 넘긴다. 시리즈와 detail에 name을 지정해 둔다.

{
    series: [
        {
            name: '시도',
            map: '시도',
            useMapData: true,
            detail: {
                name: '시군구',
                map: '시군구',
                useMapData: true,
            }
        },
    ]
}
// 시도 지도에서 경기도로 드릴다운한다.
chart.drilldown('시도', '31');
 
// 시군구 지도에서 시도 지도로 드릴업한다.
chart.drillup('시군구');
  • drilldown(series, area)는 지금 보이는 맵 시리즈에서 한 단계 아래로만 내려간다. area에는 지금 화면에 있는 지역의 id를 넘긴다.
  • drillup(series)는 넘긴 시리즈의 부모 단계로 올라간다. 지금 보이는 시리즈나 그 위에 펼쳐진 시리즈를 넘길 수 있고, 위 단계 시리즈를 넘기면 드릴다운 패널처럼 여러 단계를 한 번에 올라간다.
  • 시리즈는 이름 말고도 시리즈 객체나 번호로 넘길 수 있다. 번호는 최상위 시리즈의 순서이고, 이름은 detail 시리즈의 이름으로도 찾는다.
  • drilldown()은 첫 인자를 생략할 수 없다. drillup()은 인자를 생략하면 지금 보이는 시리즈에서 한 단계 올라간다.
  • 다른 지역으로 옮기려면 드릴업한 뒤 다시 드릴다운한다.

드릴다운·드릴업 콜백

드릴다운이나 드릴업으로 지도가 바뀐 뒤에 페이지의 다른 요소도 함께 바꾸려면 general.onDrilldown과 general.onDrillup을 지정한다.

{
    general: {
        clickAction: 'drilldown',
        onDrilldown: ({ series, area }) => {
            document.getElementById('stage').textContent = `현재 단계: ${series.name} (${area})`;
        },
        onDrillup: ({ series }) => {
            document.getElementById('stage').textContent = `현재 단계: ${series.name}`;
        }
    },
}
  • 두 콜백은 시리즈를 바꾸고 지도를 처음 그린 다음에 호출된다. series는 새로 표시된 시리즈다.
  • transition이 'zoom'이면 확대·이동이 끝나고 시군구 지도로 바뀐 뒤에 호출된다.
  • 지역 클릭, 드릴다운 패널, chart.drilldown()·chart.drillup() 호출 모두 같은 콜백을 부른다. 드릴다운 패널에서 여러 단계를 한 번에 올라가도 onDrillup은 한 번 호출된다.
  • 하위 지역이 없는 지역을 클릭한 경우처럼 드릴다운·드릴업이 실행되지 않으면 콜백도 호출되지 않는다.
  • area는 두 콜백에서 뜻이 다르다. onDrilldown에서는 드릴다운한 지역의 id이고, onDrillup에서는 도착한 단계가 표시 범위를 좁혀 둔 지역의 id다. scope를 'selected'로 지정해 들어온 단계가 아니면 onDrillup의 area는 없다.

시도 → 시군구 → 읍면동 세 단계에 scope: 'selected'를 지정한 경우, 두 콜백이 받는 값은 다음과 같다.

동작콜백seriesarea
시도에서 경기도로 드릴다운onDrilldown시군구'31' (드릴다운한 경기도)
시군구에서 수원시 장안구로 드릴다운onDrilldown읍면동'31011'
읍면동에서 한 단계 드릴업onDrillup시군구'31' (시군구 단계가 경기도 하위로 좁혀져 있음)
시도까지 드릴업onDrillup시도없음 (최상위 단계는 범위를 좁히지 않음)

전체 Config

{
    title: false,
    credits: {visible: false},
    general: {
        clickAction: 'drilldown'
    },
    drilldownPanel: {
        type: 'button'
    },
    map: [
        {
            name: '시도',
            url: 'https://unpkg.com/realmap-collection/kr-sido-low.geo.json',
        },
        {
            name: '시군구',
            url: 'https://unpkg.com/realmap-collection/kr-sigun-low.geo.json',
        },
    ],
    body: {
        projection: 'mercator',
    },
    series: [
        {
            map: '시도',
            useMapData: true,
            style: {
                stroke: '#4f4f4f',
                fill: '#e7e7e7',
                strokeWidth: 0.5,
            },
            detail: {
                map: '시군구',
                useMapData: true,
                style: {
                    stroke: '#4f4f4f',
                    fill: '#e7e7e7',
                    strokeWidth: 0.5,
                },
                onPointClick: args => {
                    const mapChart = args.chart;
                    
                    mapChart.drillup(mapChart.series);
                },
            }
        },
    ],
}

See Also

콜아웃(Callout)툴팁(Tooltip)과 Hovering