데이터(Data)

시리즈의 data(또는 dataUrl로 불러온 배열)의 각 항목은 데이터포인트 객체로 만들어진다. 이 문서는 그 항목에 어떤 속성을 넣을 수 있는지를 정리한다.

시리즈 옵션(radius, color 같은 표시 설정)은 차트 Configuration을 참고한다. 여기서 다루는 것은 데이터 항목 쪽이다.

데이터 항목의 네 가지 형태

const config = {
    series: [{
        type: 'point',
        data: [
            { id: '11', name: '서울', value: 42, coord: [126.98, 37.57] },  // 객체
            '21',                                                          // 문자열 = id
            ['31', 15],                                                    // 배열 (fields 필요)
            null                                                           // 빈 데이터포인트
        ]
    }]
}

• 객체 — 가장 일반적인 형태. 아래의 속성들을 지정한다.
• 문자열 — id로만 해석된다. 값 없이 지역만 표시할 때 쓴다.
• 배열 — fields 옵션으로 각 위치의 이름을 지정해야 한다. 아래 배열 형태 참고.
• null 또는 빈 배열 — 데이터포인트는 만들어지지만 표시되지 않는다(isNull).

데이터가 중첩된 JSON 안에 있으면 dataPath로 배열 위치를 지정한다.

{
    dataUrl: '/data/stats.json',
    dataPath: 'result.rows'      // { result: { rows: [ ... ] } }
}

공통 속성

모든 시리즈에서 읽는 속성이다.

className도 읽히지만 렌더된 요소에는 반영되지 않는다. 콜백 함수의 인자로만 전달되므로, CSS로 스타일을 주려면 시리즈의 style이나 콜백을 쓴다.

좌표를 지정하는 방법

위에서부터 순서대로 확인해서, 먼저 맞는 것 하나가 채택된다.

data: [
    { id: 'a', coord: [126.98, 37.57] },   // 1. coord 배열 [경도, 위도]
    { id: 'b', lon: 129.08, lat: 35.18 },  // 2. lon / lat
    { id: 'c', x: 126.85, y: 35.16 },      // 3. x / y
    { id: '11' }                           // 4. 지도 area의 중심 좌표
]

데이터의 필드명이 다르면 lonField / latField로 알려준다.

{
    type: 'point',
    lonField: 'dec_long_va',
    latField: 'dec_lat_va',
    dataUrl: '/data/stations.json'
}

넷 다 없으면 id가 지도 area의 id와 같은 경우 그 area의 중심 좌표가 쓰인다. 이때 맞춰야 하는 것은 area의 id이지 이름이 아니다.

{ id: '11' }          // 지도 area id → 서울 중심 좌표
{ id: '서울특별시' }    // area 이름 → 연결되지 않는다

어느 것도 해당하지 않으면 좌표가 [0, 0]이 된다. 데이터포인트가 사라지는 것이 아니라 서아프리카 앞바다에 그려지므로, 세계지도에서는 엉뚱한 위치에 표시되고 지역 지도에서는 화면 밖으로 나가 보이지 않는다. 세계지도 서아프리카 앞바다에 점이 뭉쳐 있다면 좌표 지정을 확인한다.

필드명이 다를 때

데이터의 필드명을 바꿀 수 없을 때, 시리즈 옵션으로 어느 필드를 읽을지 지정한다.

{
    type: 'map',
    idField: 'b-code',        // 데이터의 "b-code"를 id로 쓴다
    valueField: 'laborForce',
    dataUrl: '/data/sido-labor-force.json'
}

맵 시리즈에서 지도 쪽 속성까지 바꿔야 하면 mapKeys를 쓴다. [지도 속성, 데이터 속성] 순서다.

{
    type: 'map',
    mapKeys: ['name', 'sido'],   // 지도의 name ↔ 데이터의 sido
    dataUrl: '/data/sido-police-coverage.json'
}

value — 숫자인가 배열인가

시리즈에 따라 다르다. 틀려도 에러가 나지 않고 그려지지만 않으므로 주의한다.

{ type: 'pie',   data: [{ id: '11', value: [24.7, 12.3, 22.2, 40.7] }] }
{ type: 'point', data: [{ id: '11', value: 42 }] }

값이 여러 필드에 나뉘어 있으면 valueFields로 모은다.

{
    type: 'pie',
    valueFields: ['원자력', '석탄', '가스', '신재생'],
    dataUrl: '/data/energy.json'
}

배열을 받는 시리즈에 숫자 하나를 주면 항목이 하나인 배열로 취급된다. 반대로 숫자를 받는 시리즈에 배열을 주면 값이 배열인 채로 남아 정상적으로 표시되지 않는다.

시리즈별 추가 속성

라우트 시리즈는 좌표를 coord(단수)가 아니라 coords(쌍)로 지정한다.

{
    type: 'route',
    data: [
        { name: '서울-부산', coords: [[126.98, 37.57], [129.08, 35.18]], curveFactor: 0.3 }
    ]
}

배열 형태와 fields

데이터가 객체가 아니라 값의 배열이면, fields로 각 위치의 이름을 지정한다.

{
    type: 'map',
    fields: ['id', 'value'],
    data: [
        ['11', 15709],
        ['21', 4318]
    ]
}

좌표는 coord로 받는다. 이때 해당 위치의 값은 [경도, 위도] 배열이어야 한다.

{
    type: 'point',
    fields: ['id', 'coord'],
    data: [
        ['서울', [126.98, 37.57]],
        ['부산', [129.08, 35.18]]
    ]
}

fields를 지정하지 않으면 배열 항목의 값을 읽지 못한다. 객체 형태를 쓰거나 fields를 함께 지정한다.

fields에 lon이나 lat을 넣으면 안 된다. 두 속성은 coord에서 계산되는 읽기 전용이라 대입하는 순간 Cannot set property lon of #<...> which has only a getter 예외가 발생하고, 그 예외가 데이터를 읽는 도중에 터져 시리즈뿐 아니라 차트 전체가 빈 화면이 된다. createChartAsync는 그래도 정상적으로 resolve하므로 try/catch로는 잡히지 않는다 — 콘솔에 uncaught 에러로만 남는다. 배열 형태에서 좌표는 위 예시처럼 coord 한 칸으로 받는다.

fields: ['id', 'coord', 'value']   // 정상
fields: ['id', 'lon', 'lat']       // 차트가 백지가 된다

index.d.ts의 fields 옵션 JSDoc이 예시로 드는 ['id', 'lon', 'lat', 'name', 'color']가 바로 이 조합이다. 타입 정의를 참고하더라도 이 예시만은 따라 쓰면 안 된다.

x/y는 예외가 나지는 않지만 배열 형태에서는 좌표로 해석되지 않는다. fields에 쓸 수 있는 이름은 id, name, value, coord, color, className, visible, callout, offset이다. 시리즈별 속성은 읽기 전용이 아닌 것만 된다 — pin의 radius는 되지만 route의 lon1/lat1/lon2/lat2는 lon/lat과 같은 이유로 터진다. 애초에 route 시리즈는 배열 형태를 지원하지 않으므로 객체로 준다.

fields를 지정하면 idField·lonField·latField·valueField는 무시된다. 이 옵션들로 배열 데이터를 읽으려면 값이 함수(v => v[1])나 문자열 인덱스('1')여야 한다. 숫자 인덱스는 동작하지 않는다.

데이터가 연결됐는지 확인하기

id가 지도 area와 맞지 않아도 에러가 나지 않는다. 지도만 그려지고 데이터는 한 건도 붙지 않은 상태가 되는데, 화면만 봐서는 알기 어렵다.

데이터를 처음 붙일 때는 지도 파일의 properties.rm-id 값을 직접 열어 데이터의 id와 대조한다. 전부 어긋나면 아무것도 표시되지 않고, 일부만 어긋나면 그 지역만 값 없이 빈 채로 그려진다.

지역명이 개편된 경우가 대표적이다(데이터의 강원도 ↔ 지도의 강원특별자치도). 이름이 아니라 코드로 연결하고, 코드 체계가 다르면 mapKeys로 맞춘다.

See Also

• 시리즈 개요
• 지도(Map)
• 콜아웃(Callout)
• 차트 Configuration