Learning
레슨 8 / 8·15분

D3.js 레퍼런스

D3.js 모듈 구조

D3 v7은 30개 이상의 독립 모듈로 구성되어 있습니다. 필요한 모듈만 개별적으로 설치하여 번들 크기를 줄일 수 있습니다. 아래는 가장 자주 사용되는 핵심 모듈들입니다.

  • d3-selection — DOM 선택 및 조작 (select, selectAll, append, attr, style)
  • d3-scale — 스케일 함수 (scaleLinear, scaleBand, scaleOrdinal 등)
  • d3-axis — 축 생성기 (axisBottom, axisLeft, axisRight, axisTop)
  • d3-shape — 도형 생성기 (line, area, arc, pie, stack)
  • d3-transition — 트랜지션 (transition, duration, ease, delay)
  • d3-array — 배열 유틸리티 (max, min, extent, sum, mean, group)
  • d3-fetch — 데이터 로드 (csv, json, text, xml)
  • d3-force — 포스 레이아웃 (forceSimulation, forceLink, forceManyBody)
  • d3-hierarchy — 계층 구조 (hierarchy, tree, treemap, pack)
  • d3-geo — 지리 (geoPath, geoMercator, geoAlbers)
  • d3-zoom — 줌 및 패닝 (zoom, zoomIdentity)
  • d3-drag — 드래그 인터랙션 (drag)
  • d3-color — 색상 조작 (rgb, hsl, interpolateRgb)
  • d3-interpolate — 보간 (interpolateNumber, interpolateString)
  • d3-time-format — 날짜 형식 (timeFormat, timeParse)

선택(Selection) API 레퍼런스

javascript
// 선택
d3.select('selector')        // 첫 번째 요소 선택
d3.selectAll('selector')     // 모든 요소 선택
selection.select('selector') // 자식 중 첫 번째
selection.selectAll('sel')   // 자식 중 모두
selection.filter(fn)         // 조건에 맞는 요소만
selection.merge(other)       // 두 선택 합치기

// 조작
selection.attr('name', value)     // 속성 설정/읽기
selection.style('name', value)    // CSS 스타일 설정/읽기
selection.classed('name', bool)   // CSS 클래스 추가/제거
selection.property('name', value) // DOM 프로퍼티 설정
selection.text(value)             // 텍스트 콘텐츠
selection.html(value)             // HTML 콘텐츠

// 데이터 바인딩
selection.data(array, keyFn)  // 데이터 바인딩
selection.enter()             // 새 데이터용 가상 선택
selection.exit()              // 제거 대상 선택
selection.join(enter, update, exit) // 한 번에 처리 (v5.8+)
selection.datum(value)        // 단일 데이터 바인딩

// 요소 추가/제거
selection.append('tag')       // 자식 요소 추가
selection.insert('tag', 'before') // 특정 위치에 삽입
selection.remove()            // 요소 제거
selection.clone(deep)         // 요소 복제

// 이벤트
selection.on('event', handler) // 이벤트 리스너
selection.dispatch('event')    // 이벤트 발생

// 기타
selection.each(fn)            // 각 요소에 함수 실행
selection.call(fn)            // 선택 자체를 함수에 전달
selection.empty()             // 선택이 비어있는지
selection.size()              // 선택된 요소 수
selection.node()              // 첫 번째 DOM 노드 반환
selection.nodes()             // 모든 DOM 노드 배열

스케일 API 레퍼런스

javascript
// 연속형 스케일
d3.scaleLinear()      // 선형 매핑
d3.scalePow()         // 거듭제곱 매핑
d3.scaleSqrt()        // 제곱근 매핑 (면적 비례 시)
d3.scaleLog()         // 로그 매핑
d3.scaleTime()        // 시간 데이터용

// 범주형 스케일
d3.scaleBand()        // 막대 차트용 (균등 띠)
d3.scalePoint()       // 점 차트용 (균등 점)
d3.scaleOrdinal()     // 이산 매핑 (색상 등)

// 공통 메서드
scale.domain([min, max])   // 입력 범위
scale.range([min, max])    // 출력 범위
scale.nice()               // 깔끔한 경계값으로 조정
scale.clamp(true)          // 범위 밖 값 제한
scale.invert(value)        // 역변환 (출력 → 입력)
scale.ticks(count)         // 눈금값 배열 생성

// 색상 스케일
d3.scaleSequential(d3.interpolateViridis)
d3.scaleQuantize()    // 연속 → 이산
d3.scaleThreshold()   // 임계값 기반

도형 생성기 레퍼런스

  • d3.line() — 꺾은선 경로 생성 (.x(), .y(), .curve())
  • d3.area() — 영역 경로 생성 (.x(), .y0(), .y1())
  • d3.arc() — 호(파이/도넛 조각) 생성 (.innerRadius(), .outerRadius())
  • d3.pie() — 파이 레이아웃 데이터 변환 (.value(), .sort())
  • d3.stack() — 스택 레이아웃 (.keys(), .order(), .offset())
  • d3.symbol() — 심볼(마커) 생성 (.type(), .size())
  • d3.linkVertical() / d3.linkHorizontal() — 트리 연결선

트랜지션 API 레퍼런스

javascript
// 트랜지션 생성
selection.transition()          // 트랜지션 시작
selection.transition('name')    // 이름 있는 트랜지션

// 설정
.duration(ms)       // 지속 시간
.delay(ms | fn)     // 지연 시간
.ease(easeFn)       // 이징 함수

// 이징 함수 모음
d3.easeLinear        d3.easeCubicInOut
d3.easeQuadIn        d3.easeQuadOut
d3.easeBounceOut     d3.easeElasticOut
d3.easeBackOut       d3.easeCircleInOut
d3.easeExpIn         d3.easeSinInOut

// 콜백
.on('start', fn)    // 시작 시
.on('end', fn)      // 종료 시
.on('interrupt', fn) // 중단 시

// 속성 변화
.attr('name', value)     // 속성 보간
.style('name', value)    // 스타일 보간
.attrTween('name', fn)   // 커스텀 속성 보간
.styleTween('name', fn)  // 커스텀 스타일 보간
.tween('name', fn)       // 범용 커스텀 보간

// 체이닝
.transition()       // 다음 트랜지션 연결 (순차 실행)
.selection()        // 원래 선택으로 돌아가기

유용한 배열 유틸리티

javascript
// 통계
d3.min(array, accessor)     // 최솟값
d3.max(array, accessor)     // 최댓값
d3.extent(array, accessor)  // [최솟값, 최댓값]
d3.sum(array, accessor)     // 합계
d3.mean(array, accessor)    // 평균
d3.median(array, accessor)  // 중앙값
d3.deviation(array)         // 표준편차

// 검색/변환
d3.group(array, keyFn)      // Map으로 그룹화
d3.rollup(array, reduceFn, keyFn)  // 그룹 + 집계
d3.sort(array, comparator)  // 정렬
d3.ascending(a, b)          // 오름차순 비교 함수
d3.descending(a, b)         // 내림차순 비교 함수

// 생성
d3.range(start, stop, step) // 숫자 배열 생성
d3.ticks(start, stop, count) // 균등 눈금 배열
d3.pairs(array)             // 인접 쌍 배열

자주 사용하는 패턴 정리

  • Margin Convention — SVG 안에 g 요소 + translate로 여백 확보
  • data().join() — enter/update/exit를 간결하게 처리 (D3 v5.8+)
  • Reusable Chart Pattern — 함수로 감싸 재사용 가능한 차트 생성
  • Responsive — ResizeObserver로 컨테이너 크기 감지 후 차트 리사이즈
  • Accessor Pattern — function(d) { return d.value; } 형태로 데이터 접근
  • Transition Chaining — .transition().transition()으로 순차 애니메이션
  • Zoom + Pan — d3.zoom()으로 확대/축소/이동 구현
💡

D3.js 공식 문서(d3js.org)와 Observable(observablehq.com)에서 수천 개의 예제를 확인할 수 있습니다. Mike Bostock의 Observable 노트북에서 D3의 모든 기능을 인터랙티브하게 학습할 수 있습니다.