라이브러리 로드

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

기본 라이브러리 로드

몇 가지 예외를 제외하고는 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에서 다음 한두 달 안에 출시할 새로운 차트 유형이나 기능을 테스트하려는 경우입니다. (Google은 포럼을 통해 향후 출시를 발표하며, 차트 변경사항이 허용되는지 확인할 수 있도록 발표될 때 시도해 보는 것이 좋습니다.)

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

또한 이 예에서는 웹페이지에 drawChart라는 자바스크립트 함수가 정의되어 있다고 가정합니다. 함수의 이름은 원하는 대로 지정할 수 있지만 전역적으로 고유해야 하며 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
차트에 포함될 수 있는 텍스트를 맞춤설정하는 데 사용할 언어의 코드입니다. 자세한 내용은 언어를 참고하세요.
callback
패키지가 로드된 후 호출되는 함수입니다. 또는 위 예와 같이 google.charts.setOnLoadCallback를 호출하여 이 함수를 지정할 수 있습니다. 자세한 내용은 콜백을 참고하세요. 
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
mapsApiKey
(v45) 이 설정을 사용하면 Geochart 및 지도 차트와 함께 사용할 수 있는 키를 지정할 수 있습니다. 기본 동작을 사용하는 대신 이 작업을 수행하면 사용자 서비스가 가끔 제한될 수 있습니다. '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();
      });

프로미스를 통한 콜백

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

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

Promise 사용의 한 가지 이점은 더 많은 .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>

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