가이드
시리즈(Series)
Map Series
데이터 연결

데이터 연결

맵 시리즈는 데이터를 지도의 지역(area)에 연결해서 표시한다. 이 페이지에서는 데이터를 등록하는 방법과 데이터-지역 연결 규칙을 다룬다.

data로 등록하기

{
    data: [
        { id: '11', value: 10 }, // 서울
        { id: '31', value: 20 }, // 경기도
    ]
}
  • data 옵션으로 맵 시리즈에서 사용할 데이터를 등록한다.
  • 데이터와 지역의 아이디가 같은 경우 연결된다.
  • 기본 설정으로 이름이 "id"인 속성을 아이디로 간주한다.

지역의 아이디

"features": [
    {
        "id": "11",
        "type": "Feature",
        "geometry": {
            "type": "Polygon",
            "coordinates": [/*...*/]
        },
        "properties": {
            "rm-id": "11",
            "name": "서울특별시",
        },
    },
    /*... 지역 개수만큼 feature 객체가 있습니다.*/
]
  • 지역은 지도 데이터(config.map.url 또는 config.map.source)의 feature 하나에 해당한다.
  • 지역의 아이디는 feature의 "rm-id" 또는 "id" 속성이다.
  • RealMap이 기본 제공하는 지도의 지역 아이디는 지역 아이디(Region ID) 페이지에서 확인할 수 있다.

dataUrl — 원격 데이터 사용하기

const config = {
    series: [
        {
            dataUrl: '/assets/data/kr-sigun-population-density.json',
        },
    ],
};
 
const chart = await RealMap.createChartAsync(document, 'realmap', config);
  • dataUrl에 URL을 지정하면 GET 요청으로 데이터를 내려받아 시리즈의 data로 사용한다.
  • createChartAsync로 맵차트를 생성할 때만 동작한다. 동기 함수인 createChart로 생성하면 콘솔에 경고가 표시된다.
  • data가 함께 설정된 경우 dataUrl은 무시된다.
  • 데이터 항목의 형태와 필드 지정 방법은 데이터 가이드를 참고한다.

mapKeys — 데이터에 id 속성이 없을 때

데이터의 어떤 속성으로 지역과 연결할지 지정하는 옵션이다.

{
    // 첫번째가 지도의 속성, 두번째가 데이터의 속성.
    // 지도의 "iso-a3" 값과 데이터의 "countryCode" 값이 같은 지역을 연결한다.
    mapKeys: ['iso-a3', 'countryCode'],
    data: [
        { countryCode: 'KOR', value: 10 },
        { countryCode: 'USA', value: 20 },
    ]
}
  • 두 값을 배열로 지정하면 첫번째는 지도 소스 "properties"의 속성명, 두번째는 데이터의 속성명이다.
  • 문자열 하나로 지정하면 양쪽 모두 같은 속성명으로 연결한다. 예를 들어 mapKeys: 'name'은 지도의 지역 이름과 데이터의 name 속성으로 연결한다.

useMapData — 데이터를 연결하지 않고 쓰기

{
    series: [
        {
            useMapData: true,
            tooltipText: '${name}',
        },
    ],
}

useMapData를 true로 지정하면 지도 소스를 데이터처럼 사용해서, 지도의 모든 지역에 대해 데이터포인트를 자동 생성한다. 생성된 데이터포인트는 지역의 id와 name만 갖고 value는 없다.

실제 데이터를 연결하는 옵션이 아니라는 점에 주의한다.

  • data나 dataUrl로 지정한 데이터는 무시된다.
  • 값이 없으므로 컬러스케일로 채색되지 않는다. 툴팁에 ${value}를 쓰면 NaN으로 표시되므로 넣지 않는다.

켜면 모든 지역이 데이터가 연결된 것처럼 동작한다.

  • 모든 지역에서 툴팁과 hover 효과가 동작하고, onPointClick도 모든 지역에서 호출된다.
  • 데이터가 연결되지 않은 지역이 없어지므로 nullStyle이 적용되는 지역도 없다.
  • 범례 표시에는 영향을 주지 않는다.

데이터 없이 배경 지도를 표시하면서 전 지역에 이름 툴팁·라벨을 보여줄 때 사용한다. 일단 전 지역에 데이터포인트를 만들어 두고 updatePoint API로 값을 나중에 주입하는 패턴에도 쓸 수 있다.

See Also

Map Series색상