라이브러리 로드

이 페이지에서는 Google 차트 라이브러리를 로드하는 방법을 보여줍니다.

기본 라이브러리 로드

몇 가지 예외를 제외하고 Google 차트가 포함된 모든 웹페이지는 웹페이지의 <head>에 다음 줄을 포함해야 합니다.

<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
  ...
</script>

이 예의 첫 번째 줄은 로더 자체를 로드합니다. 그릴 차트의 수와 관계없이 로더는 한 번만 로드할 수 있습니다. 로더를 로드한 후 google.charts.load 함수를 한 번 이상 호출하여 특정 차트 유형의 패키지를 로드할 수 있습니다.

google.charts.load의 첫 번째 인수는 문자열 형식의 버전 이름 또는 번호입니다. 'current'를 지정하면 Google 차트의 최신 공식 버전이 로드됩니다. 다음 출시 후보를 사용해 보려면 대신 'upcoming'를 사용하세요. 일반적으로 두 버전 간에 차이가 거의 없으며 새 버전이 진행 중인 경우를 제외하고는 완전히 동일합니다. upcoming를 사용하는 일반적인 이유는 Google에서 앞으로 1~2개월 이내에 출시할 예정인 새로운 차트 유형이나 기능을 테스트하기 위해서입니다. 포럼에서 예정된 출시를 공지하며, 공지 시 차트 변경사항을 수용할 수 있는지 확인하기 위해 사용해 보시기 바랍니다.

위의 예에서는 corechart(막대, 열, 선, 영역, 계단식 영역, 풍선, 원형, 도넛, 콤보, 양초, 히스토그램, 분산형)을 표시한다고 가정합니다. 다른 차트 유형을 사용하거나 추가하려면 위의 corechart에 적절한 패키지 이름을 대체하거나 추가합니다 (예: {packages: ['corechart', 'table', 'sankey']}. 패키지 이름은 각 차트의 문서 페이지에 있는 '로드 중' 섹션에서 확인할 수 있습니다.

또한 이 예에서는 웹페이지 어딘가에 drawChart라는 JavaScript 함수가 정의되어 있다고 가정합니다. 이 함수의 이름은 원하는 대로 지정할 수 있지만 google.charts.setOnLoadCallback 호출에서 참조하기 전에 전역적으로 고유하고 정의되어 있는지 확인해야 합니다.

참고: 이전 버전의 Google 차트에서는 위와 다른 코드를 사용하여 라이브러리를 로드했습니다. 새 코드를 사용하도록 기존 차트를 업데이트하려면 라이브러리 로더 코드 업데이트를 참고하세요.

다음은 기본 로드 기법을 사용하여 원형 차트를 그리는 전체 예입니다.

<head>
  <script src="https://www.gstatic.com/charts/loader.js"></script>
  <script>
    google.charts.load('current', {packages: ['corechart']});
    google.charts.setOnLoadCallback(drawChart);

    function drawChart() {
      // Define the chart to be drawn.
      var data = new google.visualization.DataTable();
      data.addColumn('string', 'Element');
      data.addColumn('number', 'Percentage');
      data.addRows([
        ['Nitrogen', 0.78],
        ['Oxygen', 0.21],
        ['Other', 0.01]
      ]);

      // Instantiate and draw the chart.
      var chart = new google.visualization.PieChart(document.getElementById('myPieChart'));
      chart.draw(data, null);
    }
  </script>
</head>
<body>
  <!-- Identify where the chart should be drawn. -->
  <div id="myPieChart"/>
</body>

세부정보 로드 중

먼저 로더 자체를 로드해야 합니다. 이는 src="https://www.gstatic.com/charts/loader.js"를 사용하여 별도의 script 태그에서 실행됩니다. 이 태그는 문서의 head 또는 body에 있거나 문서가 로드되는 동안 또는 로드가 완료된 후에 문서에 동적으로 삽입될 수 있습니다. 

<script src="https://www.gstatic.com/charts/loader.js"></script>

로더가 로드된 후에는 언제든지 google.charts.load를 호출할 수 있습니다. 호출 위치는 문서의 head 또는 body의 script 태그에 있을 수 있으며, 문서가 아직 로드되는 동안 또는 로드가 완료된 후 언제든지 호출할 수 있습니다.

버전 45부터 추가 패키지를 로드하기 위해 google.charts.load를 두 번 이상 호출할 수 있지만, 그렇게 하지 않는 것이 더 안전합니다. 매번 동일한 버전 번호와 언어 설정을 제공해야 합니다.

이제 이전 JSAPI autoload URL 매개변수를 사용할 수 있지만 이 매개변수의 값은 엄격한 JSON 형식 및 URL 인코딩을 사용해야 합니다. JavaScript에서는 다음 코드 encodeURIComponent(JSON.stringify(jsonObject))를 사용하여 jsonObject를 인코딩할 수 있습니다.

제한사항

v45 이전 버전을 사용하는 경우 Google 차트를 로드하는 방법에 몇 가지 사소하지만 중요한 제한사항이 있습니다.

  1. google.charts.load는 한 번만 호출할 수 있습니다. 하지만 필요한 모든 패키지를 한 번의 호출에 나열할 수 있으므로 별도로 호출할 필요가 없습니다.
  2. ChartWrapper를 사용한다면 ChartWrapper를 사용해 패키지를 자동으로 로드하는 대신 필요한 모든 패키지를 명시적으로 로드해야 합니다.
  3. Geochart 및 지도 차트의 경우 이전 라이브러리 로더와 새 라이브러리 로더를 모두 로드해야 합니다. 이 방법은 v45 이전 버전에만 해당하며 이후 버전에서는 이 작업을 수행하면 안 됩니다. 
    <script src="https://www.gstatic.com/charts/loader.js"></script>
<script src="https://www.google.com/jsapi"></script>

버전 이름 또는 번호 로드

google.charts.load 호출의 첫 번째 인수는 버전 이름 또는 번호입니다. 현재는 두 가지 특수 버전 이름과 여러 개의 고정된 버전이 있습니다.

현재
새 버전을 출시할 때마다 변경되는 최신 공식 버전에 관한 것입니다. 이 버전은 테스트가 완료되고 버그가 없는 것이 이상적이지만, 작동하는 것으로 확인되면 대신 특정 동결된 버전을 지정하는 것이 좋습니다.
예정
다음 버전이 아직 테스트 중이고 공식 현재 버전이 되기 전에 사용합니다. 이 버전이 공식 버전이 되기 전에 해결해야 할 문제가 있는지 가능한 한 빨리 알 수 있도록 이 버전을 정기적으로 테스트하시기 바랍니다.

Google 차트의 새 버전이 출시되면 완전히 새로운 차트 유형과 같이 큰 변화가 있을 수 있습니다. 기존 차트의 모양이나 동작을 개선하는 등 다른 변경사항은 작습니다.

많은 Google 차트 제작자가 원하는 대로 될 때까지 차트의 디자인과 분위기를 미세 조정합니다. 향후 어떤 개선사항이 적용되든 차트가 변경되지 않는다는 점을 알면 더 편안하게 느낄 수 있는 크리에이터도 있을 것입니다. 이러한 사용자를 위해서는 고정된 Google 차트가 지원됩니다.

고정 차트 버전은 숫자로 식별되며 공식 출시에 설명되어 있습니다. 동결된 버전을 로드하려면 google.charts.load 호출에서 current 또는 upcoming를 동결된 버전 번호로 바꿉니다.

<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
    google.charts.load('43', {packages: ['corechart']});
    google.charts.setOnLoadCallback(drawChart);
    ...
</script>

동결된 버전은 보안 문제가 있는 동결된 버전은 지원 중단될 수 있지만 무기한 사용할 수 있을 것으로 예상됩니다. Google에서는 일반적으로 최신 버전으로 업그레이드하라는 도움이 되지 않는 경우를 제외하고는 고정된 버전을 지원하지 않습니다.

설정 로드

google.charts.load 호출의 두 번째 매개변수는 설정을 지정하기 위한 객체입니다. 설정에 지원되는 속성은 다음과 같습니다.

packages
0개 이상의 패키지 배열입니다. 로드되는 각 패키지에는 기능 집합(일반적으로 차트 유형)을 지원하는 데 필요한 코드가 있습니다. 로드해야 하는 패키지는 각 차트 유형의 문서에 나와 있습니다. ChartWrapper를 사용하여 필요한 항목을 자동으로 로드하면 패키지를 지정하지 않아도 됩니다.
language
차트의 일부가 될 수 있는 텍스트를 맞춤설정해야 하는 언어 또는 언어의 코드입니다. 자세한 내용은 언어를 참고하세요.
콜백
패키지가 로드된 후 호출되는 함수입니다. 또는 위 예와 같이 google.charts.setOnLoadCallback를 호출하여 이 함수를 지정할 수 있습니다. 자세한 내용은 콜백을 참고하세요. 
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
mapsApiKey
(v45) 이 설정을 사용하면 Geochart 및 Map Chart와 함께 사용할 키를 지정할 수 있습니다. 기본 동작을 사용하는 대신 이 작업을 수행하면 때때로 사용자에 대한 서비스가 제한될 수 있습니다. 'Google Maps JavaScript API' 서비스를 사용하기 위해 자체 키를 설정하는 방법은 키/인증 가져오기를 참고하세요. 코드는 다음과 같습니다. 
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
safeMode
(v47) true로 설정하면 사용자 제공 데이터에서 HTML을 생성하는 모든 차트와 도움말이 안전하지 않은 요소와 속성을 제거하여 데이터를 정리합니다. 또는 (v49 이상) 동일한 로드 설정을 허용하지만 항상 '현재' 버전을 로드하는 바로가기를 사용하여 라이브러리를 안전 모드로 로드할 수 있습니다. 
  google.charts.safeLoad({ packages: ['corechart'] });

언어

언어 객체는 국가 또는 언어의 텍스트를 맞춤설정하는 데 사용되며 통화, 날짜, 숫자와 같은 값의 형식에 영향을 미칩니다.

기본적으로 Google 차트는 'en' 언어로 로드됩니다. 로드 설정에서 언어를 명시적으로 지정하여 이 기본값을 재정의할 수 있습니다.

특정 언어에 맞게 형식이 지정된 차트를 로드하려면 다음과 같이 language 설정을 사용하세요. 

  // Load Google Charts for the Japanese locale.
  google.charts.load('current', {'packages':['corechart'], 'language': 'ja'});

실제 예시를 보려면 이 링크를 클릭하세요.

콜백

google.charts.load에서 로드한 패키지를 사용하려면 로드가 완료될 때까지 기다려야 합니다. 문서 로드가 완료될 때까지 기다리는 것만으로는 충분하지 않습니다. 이 로드가 완료되기까지 다소 시간이 걸릴 수 있으므로 콜백 함수를 등록해야 합니다. 다음 세 가지 방법으로 할 수 있습니다. google.charts.load 호출에서 callback 설정을 지정하거나 함수를 인수로 전달하여 setOnLoadCallback를 호출하거나 google.charts.load 호출에서 반환되는 프로미스를 사용합니다.

이러한 모든 방법에서는 함수를 호출하는 대신 함수 정의를 제공해야 합니다. 제공하는 함수 정의는 이름이 지정된 함수 (이름만 지정하면 됨)이거나 익명 함수일 수 있습니다. 패키지 로드가 완료되면 이 콜백 함수가 인수 없이 호출됩니다. 로더는 콜백을 호출하기 전에 문서 로드가 완료될 때까지 기다립니다.

차트를 두 개 이상 그리려면 setOnLoadCallback를 사용하여 두 개 이상의 콜백 함수를 등록하거나 하나의 함수로 결합하면 됩니다. 한 페이지에 여러 차트를 그리는 방법을 자세히 알아보세요. 

  google.charts.setOnLoadCallback(drawChart1);
  google.charts.setOnLoadCallback(drawChart2);
  // OR
  google.charts.setOnLoadCallback(
    function() { // Anonymous function that calls drawChart1 and drawChart2
         drawChart1();
         drawChart2();
      });

Promise를 통한 콜백

콜백을 등록하는 또 다른 방법은 google.charts.load 호출에서 반환된 Promise를 사용하는 것입니다. 다음과 같은 코드로 then() 메서드 호출을 추가하면 됩니다. 

  google.charts.load('upcoming', {packages: ['corechart']}).then(drawChart);

프로미스를 사용할 때의 이점 중 하나는 더 많은 .then(anotherFunction) 호출을 체인으로 연결하여 더 많은 차트를 쉽게 그릴 수 있다는 것입니다. Promise를 사용하면 콜백이 해당 콜백에 필요한 특정 패키지에 연결되기도 합니다. 이는 google.charts.load()를 다시 호출하여 더 많은 패키지를 로드하려는 경우에 중요합니다.

라이브러리 로더 코드 업데이트

이전 버전의 Google 차트는 다른 코드를 사용하여 라이브러리를 로드했습니다. 아래 표는 이전 라이브러리 로더 코드와 새 코드를 보여줍니다.

이전 라이브러리 로더 코드 
<script type="text/javascript" src="https://www.google.com/jsapi"></script>
<script type="text/javascript">
  google.load("visualization", "1", {packages:["corechart"]});
  google.setOnLoadCallback(drawChart);
</script>
새 라이브러리 로더 코드 
<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
</script>

기존 차트를 업데이트하려면 이전 라이브러리 로더 코드를 새 코드로 대체하면 됩니다. 그러나 위에서 설명한 라이브러리 로드에 관한 제한사항에 유의하세요.