문서

월별 매출 예제로 차트와 테마를 고르고 데이터를 바꿔보세요. 완성된 예제는 복사하거나 내려받아 내 웹사이트에 넣을 수 있습니다.

값을 바꾸며 첫 차트를 만들어보세요

  1. 1차트 고르기

    선·막대·영역 차트를 바꿔 보며 월별 매출에 어울리는 모습을 고르세요.

  2. 2데이터 바꾸기

    아래 표의 월과 매출을 바꾸면 차트에 바로 반영됩니다.

  3. 3웹사이트에 넣기

    완성된 HTML 예제를 복사하거나 내려받아 내 웹페이지에서 열어보세요.

월별 매출

불러오는 중

숫자를 바꿔보세요

값을 바꾸면 차트에 바로 반영됩니다. 입력한 예제 데이터는 브라우저 안에서만 사용됩니다.

월매출

이 차트를 웹사이트에 넣으세요

지금 선택한 차트와 테마, 수정한 데이터가 예제에 함께 담깁니다.

  1. 전체 예제를 index.html로 저장하고 인터넷에 연결된 브라우저에서 여세요. script 태그가 CDN에서 Graflume을 불러오므로 설치나 빌드가 필요 없습니다.
  2. script URL과 integrity 값을 유지하고 높이가 있는 차트 영역을 만든 뒤 스크립트가 로드되면 Graflume.line()을 호출하세요. rows를 내 데이터로 바꾸면 됩니다.
지금 보이는 차트의 코드 보기
<!doctype html>
<html lang="ko">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>월별 매출</title>
<h1>월별 매출</h1>
<div id="chart" style="height:420px"></div>
<script src="https://cdn.jsdelivr.net/gh/statground/graflume@62f60cf404570525acd417804ce1963bd5f6297f/cdn/graflume.global.js" integrity="sha384-Fm60RAfjqwY5ex7JeGn+wJs0uS/HdaEwUABLOcW0oyKm9yH2xtPQWMNUly9GexkZ" crossorigin="anonymous"></script>
<script>
const rows = [
  {
    "month": "1월",
    "sales": 42
  },
  {
    "month": "2월",
    "sales": 51
  },
  {
    "month": "3월",
    "sales": 49
  },
  {
    "month": "4월",
    "sales": 63
  },
  {
    "month": "5월",
    "sales": 71
  },
  {
    "month": "6월",
    "sales": 68
  }
];
Graflume.line('#chart', rows, {
  x: { field: 'month', type: 'ordinal' },
  y: { field: 'sales', type: 'quantitative' },
  theme: 'editorial',
  mark: { point: true }
});
</script>
</html>

완성한 차트, 그대로 저장하고 바로 다시 열기

선명한 SVG로 저장하고, 다시 열어도 값 확인·범례·확대 기능을 이어서 사용하세요. 예제로 직접 체험한 뒤 SVG를 보고서나 발표 자료에 담아 보세요.

월별 매출 예제

차트를 열어 값을 살펴본 뒤, 저장하고 다시 열어 보세요.

내 웹사이트에 적용하기
// After creating a chart with JSON-compatible data and settings:
const saved = JSON.stringify(chart.toSnapshot());
// Your app may store saved in IndexedDB or its own account storage.
chart.destroy();
const reopened = Graflume.restore('#chart', JSON.parse(saved));
const svg = reopened.toSVG();
// Data or setting changes can still update the reopened chart:
// reopened.setData(nextRows);
매뉴얼 내 데이터와 목적에 맞게 차트를 다듬으세요 데이터를 준비하고 차트를 고르는 방법부터, 모양을 다듬고 문제를 해결하는 순서까지 안내합니다.

내 데이터를 읽기 쉬운 차트로 만드는 방법

위의 월별 매출 예제를 기준으로 설명합니다. 무엇을 바꾸면 되는지, 어떤 차트를 골라야 하는지, 결과가 예상과 다를 때 어디를 확인할지 살펴보세요.

위의 예제로 돌아가기

1. 데이터의 이름과 값을 이해하세요

한 행에는 한 달의 이름과 매출이 들어갑니다. 데이터의 항목 이름이 차트에 표시할 값을 연결합니다.

month: 가로축에 표시할 이름

첫 번째 달의 이름은 1월입니다. 독자가 읽을 순서대로 월을 나열하세요.

sales: 세로축에 나타낼 숫자

첫 번째 매출은 42입니다. 값에는 숫자를 넣고, 원이나 만원 같은 단위는 제목이나 설명에 적으세요.

내 데이터의 항목 이름을 쓸 때

코드에서 항목 이름을 바꿨다면 x와 y의 field에도 같은 이름을 적어야 합니다. 위의 실행 예제에서는 월과 매출 칸만 수정하면 됩니다.

이 여섯 행을 코드로 보면

위의 실행 예제와 같은 데이터입니다. 전체 HTML에서는 이 데이터를 rows라는 이름에 담습니다.

[
  {"month":"1월","sales":42},
  {"month":"2월","sales":51},
  {"month":"3월","sales":49},
  {"month":"4월","sales":63},
  {"month":"5월","sales":71},
  {"month":"6월","sales":68}
]

2. 무엇을 보여줄지에 맞춰 차트를 고르세요

위의 예제에서 같은 데이터를 선·막대·영역 차트로 바꿔볼 수 있습니다. 다른 목적의 차트는 아래 예제를 열어보세요.

엑셀처럼 한 화면에서 편집하려면 → 스프레드시트 작업공간

수식 입력줄, 채우기와 복사·붙여넣기, 범위 선택, 실행 취소·다시 실행, 필터·정렬, 찾기·바꾸기, 값 검증, 조건부 서식, 메모, 링크와 표 도구를 사용할 수 있습니다. 열 머리글에서 변수명을 바로 바꿀 수 있고, 빈 이름이나 앞뒤 공백을 제외하면 다른 열과 중복되는 이름은 적용되지 않습니다. 호스트는 자체 파일 메뉴와 패널을 붙일 수 있으며, 탭을 오가도 도구 아이콘이 첫 화면부터 바로 표시됩니다. 선택 기능이 아직 없는 버전에서는 기존 Graflume 데이터 표가 그대로 열립니다.

3. 분위기를 고르고 축을 확인하세요

테마를 먼저 고른 다음, 차트를 처음 보는 사람도 숫자의 뜻을 알 수 있는지 확인하세요.

테마를 바꿔 비교하기

테마 선택으로 차트의 색과 분위기를 바꿀 수 있습니다. 테마 갤러리에서는 같은 예제가 어떻게 달라지는지 비교할 수 있습니다.

가로축과 세로축 읽기

예제의 가로축은 월, 세로축은 매출입니다. 단위와 숫자 표시 방식, 축이 보여주는 범위를 확인하세요.

글자가 놓일 공간 확인하기

긴 항목 이름에는 여유 공간이 필요합니다. 웹페이지에 넣기 전에 넓은 화면과 좁은 화면에서 모두 읽어보세요.

4. 값을 살펴보고 결과를 가져가세요

위의 실행 예제에서 내 데이터를 시험해보세요. 개별 차트 예제에서는 값을 살펴보는 도구도 사용할 수 있습니다.

자세한 값 확인하기

차트의 점이나 막대에 마우스를 올려 작은 설명 상자를 읽어보세요. 터치 화면에서는 항목을 눌러보세요. 정확한 수치는 개별 차트 예제의 데이터 표에서도 확인할 수 있습니다.

한 번에 하나씩 바꿔보기

위의 예제에서 값, 차트 종류, 테마를 하나씩 바꿔보세요. 처음 여섯 달과 비교하고 싶으면 예제 데이터로 되돌릴 수 있습니다.

웹사이트에는 HTML, 문서에는 이미지

웹사이트에서 움직이는 차트를 쓰려면 실행 예제의 전체 HTML을 복사하거나 내려받으세요. 개별 차트 예제의 PNG 내보내기는 정적인 이미지가 필요할 때 사용합니다.

5. 예상과 다를 때 확인하세요

지금 보이는 문제를 펼쳐 확인하세요.

실행 예제가 나타나지 않아요

인터넷 연결과 JavaScript 사용 여부를 확인한 뒤 다시 시도 버튼을 눌러보세요. 내려받은 HTML도 Graflume을 불러오려면 인터넷에 연결되어 있어야 합니다.

숫자를 바꿨는데 차트가 그대로예요

모든 행에 월 이름과 유효한 숫자가 있는지 확인하세요. 잘못된 값이 있으면 마지막으로 정상 표시된 차트를 유지합니다.

내 웹사이트에서는 모양이 달라요

내려받은 전체 HTML을 먼저 열어보고 데이터, 차트 종류, 테마가 같은지 확인하세요. 차트를 담는 영역의 높이도 유지해야 합니다. 예제는 420픽셀을 사용합니다.

비교 결과가 이상해 보여요

단위와 행의 순서부터 확인하세요. 빠진 값과 실제로 측정한 0은 의미가 다릅니다. 빠진 자료를 어떻게 다룰지 정한 뒤 차트를 그리세요.

자주 나오는 말 네 가지

API 용어를 먼저 외우지 않아도 예제를 사용할 수 있습니다.

축
차트의 위치가 어떤 이름이나 숫자를 뜻하는지 알려주는 기준입니다.
범례
색이나 모양이 어떤 항목을 나타내는지 설명하는 안내입니다.
툴팁
점이나 막대를 가리키거나 선택했을 때 세부 값을 보여주는 작은 설명 상자입니다.
테마
색, 글꼴, 차트의 모양을 함께 정해 둔 스타일입니다.
브라우저 API 차트를 코드로 제어하고 싶을 때 데이터 바꾸기·클릭 처리·이미지 저장 등 원하는 동작을 찾으면 사용 방법과 코드를 함께 볼 수 있습니다.

원하는 동작에 맞는 API 찾기

API는 코드에서 차트에 요청하는 동작입니다. 차트를 만든 뒤 데이터를 바꾸거나, 클릭한 값을 읽거나, 이미지를 저장할 때 사용합니다.

처음이라면 사용 안내부터 보기
시작 예제: 그대로 열 수 있는 HTML

HTML 파일로 저장해 인터넷에 연결된 브라우저에서 여세요. 다른 동작을 시험할 때는 마지막 </script> 바로 앞에 해당 코드를 넣으세요. 차트 생성 예제는 기존 const chart = … 부분을 교체합니다.

<!doctype html>
<html lang="ko">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Graflume</title>
</head>
<body>
  <div id="chart" style="width:100%;height:420px"></div>
  <script src="https://cdn.jsdelivr.net/gh/statground/graflume@62f60cf404570525acd417804ce1963bd5f6297f/cdn/graflume.global.js" integrity="sha384-Fm60RAfjqwY5ex7JeGn+wJs0uS/HdaEwUABLOcW0oyKm9yH2xtPQWMNUly9GexkZ" crossorigin="anonymous"></script>
  <script>
const chart = Graflume.line('#chart', [
  { month: "1월", sales: 42 },
  { month: "2월", sales: 51 },
  { month: "3월", sales: 49 }
], {
  x: { field: 'month', type: 'ordinal' },
  y: { field: 'sales', type: 'quantitative' },
  theme: 'editorial',
  mark: { point: true }
});
  </script>
</body>
</html>

차트 만들기

영역과 데이터를 연결해 첫 차트를 만듭니다.

선 차트를 간단히 만들기Graflume.line(target, rows, options)

시간에 따른 값의 변화를 보여주는 선 차트를 만듭니다.

입력
target: CSS 선택자 또는 HTML 요소. rows: 행 객체 배열. options: x·y 필드와 테마 등의 설정.
돌려주는 값
Chart

사용할 때 알아둘 점: 영역이 DOM에 있고 높이가 있어야 합니다. 막대·영역 차트는 같은 형식의 bar()·area()를 사용합니다. point 옵션은 선 차트 예제에만 넣으세요.

예제 코드

시작 예제의 const chart = … 문을 이 코드로 교체하세요.

const chart = Graflume.line('#chart', [
  { month: "1월", sales: 42 },
  { month: "2월", sales: 51 },
  { month: "3월", sales: 49 }
], {
  x: { field: 'month', type: 'ordinal' },
  y: { field: 'sales', type: 'quantitative' },
  theme: 'editorial',
  mark: { point: true }
});
차트 설정 전체로 만들기Graflume.create(target, spec, options?)

차트 종류와 데이터를 하나의 설정 객체로 전달합니다.

입력
target: 차트 영역. spec: data·mark·x·y 등의 전체 설정. options: 선택적인 생성 설정.
돌려주는 값
Chart

사용할 때 알아둘 점: line()과 create()는 같은 시작 차트를 만드는 두 가지 방법입니다. 같은 영역에 두 차트를 겹쳐 생성하지 마세요.

예제 코드

시작 예제의 const chart = … 문을 이 코드로 교체하세요.

const chart = Graflume.create('#chart', {
  data: [
    { month: "1월", sales: 42 },
    { month: "2월", sales: 51 },
    { month: "3월", sales: 49 }
  ],
  mark: { type: 'line', point: true },
  x: { field: 'month', type: 'ordinal' },
  y: { field: 'sales', type: 'quantitative' },
  theme: 'editorial'
});
화면에 그리기 전에 설정 확인하기Graflume.compile(spec, options?)

설정을 검사하고 차트의 그리기 결과인 scene 등을 돌려줍니다.

입력
spec: 전체 차트 설정. options: 선택적인 컴파일 설정.
돌려주는 값
scene, spec, theme 등을 포함한 CompileResult.

사용할 때 알아둘 점: HTML 영역에 차트를 생성하지 않습니다. 잘못된 설정은 예외를 발생시킵니다.

예제 코드

시작 예제의 차트를 만든 뒤 실행하세요.

const result = Graflume.compile(chart.getSpec());
console.log(result.scene.width, result.scene.height);

데이터 바꾸기

차트 설정을 유지하면서 새 값을 표시합니다.

현재 데이터를 새 행으로 교체하기chart.setData(rows, layerId?)

기존 행 전체를 전달한 데이터로 바꿉니다.

입력
rows: 새 행 배열. layerId: 여러 레이어가 있는 차트에서 갱신할 레이어 ID.
돌려주는 값
같은 chart 객체를 돌려줍니다.

사용할 때 알아둘 점: 행을 덧붙이는 메서드가 아닙니다. 이 예제는 Jan–Mar를 Apr–Jun으로 교체합니다. x·y에 지정한 필드 이름을 유지하세요.

예제 코드

시작 예제의 차트를 만든 뒤 실행하세요.

chart.setData([
  { month: "4월", sales: 63 },
  { month: "5월", sales: 71 },
  { month: "6월", sales: 68 }
]);

테마와 축 설명 바꾸기

현재 설정을 복사한 뒤 바꿀 항목을 지정합니다.

데이터를 유지하고 테마 바꾸기chart.setSpec(spec)

현재 차트 설정을 새 설정으로 교체합니다.

입력
spec: data·mark·x·y 등을 포함하는 전체 차트 설정.
돌려주는 값
같은 chart 객체를 돌려줍니다.

사용할 때 알아둘 점: 부분 설정만 전달하면 기존 설정이 사라집니다. getSpec() 결과를 직접 수정하지 말고, 예제처럼 복사한 객체를 전달하세요.

예제 코드

시작 예제의 차트를 만든 뒤 실행하세요.

chart.setSpec({
  ...chart.getSpec(),
  theme: 'graflume-dark'
});
세로축 제목과 숫자 표시 바꾸기chart.getSpec() → chart.setSpec(spec)

세로축 제목과 숫자 표시 형식을 설정합니다.

입력
현재 설정에 축 제목과 숫자 형식을 지정한 새 객체.
돌려주는 값
getSpec()은 현재 ChartSpec, setSpec()은 같은 chart 객체를 돌려줍니다.

사용할 때 알아둘 점: 예제는 단일 세로축 차트입니다. 이미 다른 axes 설정이 있다면 유지할 항목도 새 axes 객체에 복사하세요.

예제 코드

시작 예제의 차트를 만든 뒤 실행하세요.

chart.setData([
  { month: "1월", sales: 42000 },
  { month: "2월", sales: 51000 },
  { month: "3월", sales: 49000 }
]);
chart.setSpec({
  ...chart.getSpec(),
  locale: "ko",
  axes: {
    y: {
      title: "매출",
      format: { type: 'number', fractionDigits: 0, useGrouping: true }
    }
  },
  interaction: {
    ...chart.getSpec().interaction,
    tooltip: { fields: [
      { field: 'month', label: "월" },
      { field: 'sales', label: "매출", format: 'integer' }
    ] }
  }
});

화면 크기 바꾸기

영역의 크기가 달라졌을 때 다시 맞춥니다.

원본 값과 축 이름을 구분하기axes.x.labels.values

데이터의 고유 값은 유지하면서 화면에 표시할 이름만 바꿉니다. 이름이 같아도 서로 다른 실행이나 항목을 합치지 않습니다.

입력
값을 키로, 표시할 이름을 문자열로 넣은 객체.
돌려주는 값
같은 chart 객체를 돌려줍니다.

사용할 때 알아둘 점: 등록하지 않은 값은 기존 형식으로 표시합니다. 툴팁은 별도로 설정합니다. 날짜나 ID 자체에 숫자 구분자를 넣지 마세요.

예제 코드

시작 예제의 차트를 만든 뒤 실행하세요.

const spec = chart.getSpec();
chart.setSpec({
  ...spec,
  axes: {
    ...spec.axes,
    x: { labels: { values: { "1월": "1월", "2월": "2월", "3월": "3월" } } }
  }
});
현재 영역 크기로 다시 맞추기chart.resize(width?, height?)

인자를 생략하면 현재 영역의 크기를 다시 읽습니다.

입력
width·height: 선택적인 픽셀 크기. 생략하면 자동 크기로 돌아갑니다.
돌려주는 값
같은 chart 객체를 돌려줍니다.

사용할 때 알아둘 점: 숨겨진 탭이나 접힌 영역을 표시한 뒤 호출하세요. 0 크기의 영역은 원하는 차트 크기를 제공하지 못합니다.

예제 코드

시작 예제의 차트를 만든 뒤 실행하세요.

const container = document.querySelector('#chart');
container.style.height = '480px';
chart.resize();

클릭한 값 사용하기

사용자가 고른 데이터로 내 화면의 동작을 연결합니다.

차트 클릭에 반응하기chart.on('click', listener)

차트를 클릭할 때 listener 함수를 실행합니다.

입력
'click': 이벤트 이름. listener: hit 등을 받는 함수.
돌려주는 값
이 listener의 등록을 해제하는 함수. 예제에서는 stopListening에 저장합니다.

사용할 때 알아둘 점: 빈 곳을 클릭하면 hit가 없을 수 있습니다. 연결을 끝낼 때만 stopListening()을 호출하세요. chart.off('click', listener)로 같은 함수의 등록을 해제할 수도 있습니다.

예제 코드

시작 예제의 차트를 만든 뒤 실행하세요.

const stopListening = chart.on('click', ({ hit }) => {
  if (!hit) return;
  console.log(hit.datum);
});

차트를 이미지로 저장하기

화면에 그린 차트를 PNG 파일로 가져갑니다.

PNG 다운로드 시작하기chart.toDataURL(type?, quality?)

차트 이미지를 담은 데이터 URL을 만듭니다.

입력
type: 'image/png' 등의 MIME. quality: 해당 이미지 형식이 지원할 때 사용하는 선택 값.
돌려주는 값
이미지 데이터 URL 문자열. 다운로드 자체를 실행하지는 않습니다.

사용할 때 알아둘 점: 차트가 그려진 뒤 저장 버튼의 클릭 처리에서 사용하세요. 이미지 내보내기를 지원하지 않는 렌더러는 예외를 발생시킵니다.

예제 코드

시작 예제의 차트를 만든 뒤 실행하세요.

const saveButton = document.createElement('button');
saveButton.type = 'button';
saveButton.textContent = "PNG 저장";
saveButton.addEventListener('click', () => {
  const link = document.createElement('a');
  link.href = chart.toDataURL('image/png');
  link.download = 'monthly-sales.png';
  document.body.appendChild(link);
  link.click();
  link.remove();
});
document.body.appendChild(saveButton);

차트 사용을 끝내기

화면에서 차트를 제거할 때 연결된 자원을 정리합니다.

차트 인스턴스 정리하기chart.destroy()

그리기 자원, 이벤트, 크기 관찰 등의 연결을 정리합니다.

입력
입력 없음.
돌려주는 값
undefined

사용할 때 알아둘 점: 차트를 만들자마자 실행하지 마세요. 페이지나 컴포넌트에서 차트를 제거할 때 호출하며, 정리한 chart로 다시 데이터를 갱신할 수 없습니다.

예제 코드

시작 예제를 확인한 뒤, 차트를 화면에서 제거하는 시점에만 실행하세요.

chart.destroy();

완성한 차트, 그대로 저장하고 바로 다시 열기

선명한 SVG로 저장하고, 다시 열어도 값 확인·범례·확대 기능을 이어서 사용하세요. 예제로 직접 체험한 뒤 SVG를 보고서나 발표 자료에 담아 보세요.

저장한 차트 다시 열기chart.toSnapshot() → Graflume.restore(target, snapshot, options?)

완성한 SVG와 차트 상태를 저장해 재계산 없이 첫 화면을 복원합니다.

입력
target: 차트 영역. snapshot: JSON으로 저장한 toSnapshot() 결과.
돌려주는 값
Chart

사용할 때 알아둘 점: 앱이 저장 위치와 계정별 접근을 관리합니다. 함수가 포함된 설정은 저장할 수 없습니다. 원본 데이터도 포함되므로 공개 이미지와 구분해서 보관하세요. 데이터·범례·설정을 바꾸면 필요한 계산은 다시 실행합니다.

예제 코드

시작 예제의 차트를 만든 뒤 실행하세요.

// JSON으로 저장할 수 있는 데이터와 설정으로 차트를 만든 다음:
const saved = JSON.stringify(chart.toSnapshot());
// 앱에서 saved를 IndexedDB나 계정별 저장소에 보관할 수 있습니다.
chart.destroy();
const reopened = Graflume.restore('#chart', JSON.parse(saved));
const svg = reopened.toSVG();
// 다시 연 차트에서도 데이터나 설정을 바꿀 수 있습니다:
// reopened.setData(nextRows);
선명한 SVG 얻기chart.toSVG()

보고서나 발표에 쓸 벡터 이미지 문자열을 얻습니다.

입력
입력 없음.
돌려주는 값
SVG 문자열.

사용할 때 알아둘 점: SVG 이미지 자체는 차트의 조작 상태를 복원하지 않습니다. 다시 조작할 차트는 toSnapshot()으로 저장하세요. 외부 지도의 이미지 타일은 지원하지 않습니다.

예제 코드

시작 예제의 차트를 만든 뒤 실행하세요.

const svg = chart.toSVG();
const file = new Blob([svg], { type: 'image/svg+xml' });
R 등에서 만든 SVG 열기Graflume.fromSVG(target, source, options?)

벡터 도형을 가져와 값 확인과 확대 기능을 연결합니다.

입력
source: SVG 문자열. options.title: 차트 설명.
돌려주는 값
Chart

사용할 때 알아둘 점: 스크립트·외부 이미지·복잡한 클리핑 등 지원하지 않는 요소는 거부합니다. SVG에 없는 원본 데이터나 통계 계산을 복원하지 않습니다.

예제 코드

시작 예제의 const chart = … 문을 교체하세요.

const chart = Graflume.fromSVG('#chart',
  '<svg xmlns="http://www.w3.org/2000/svg" width="300" height="180">' +
  '<circle cx="130" cy="80" r="25" fill="#2563eb" data-id="study-7"/>' +
  '</svg>', { title: "연구 결과" });