라이브러리 로드

이 페이지에서는 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이라는 자바스크립트 함수가 있다고 가정합니다. 함수의 이름을 원하는 대로 지정할 수 있지만 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 인코딩을 사용해야 합니다. 자바스크립트에서 encodeURIComponent(JSON.stringify(jsonObject)) 코드를 사용하여 jsonObject의 인코딩을 실행할 수 있습니다.

제한사항

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

  1. google.charts.load한 번만 호출할 수 있습니다. 그러나 한 번의 호출로 필요한 모든 패키지를 나열할 수 있으므로 별도로 호출할 필요가 없습니다.
  2. ChartWrapper를 사용하는 경우 ChartWrapper를 사용하여 자동으로 패키지를 로드하는 대신 필요한 모든 패키지를 명시적으로 로드해야 합니다.
  3. GeoChartMap Chart의 경우 이전 라이브러리 로더와 새 라이브러리 로더를 모두 로드해야 합니다. 이는 다시 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 호출의 두 번째 매개변수는 설정을 지정하는 객체입니다. 설정에서 다음 속성이 지원됩니다.

택배
0개 이상의 패키지의 배열입니다. 로드된 각 패키지에는 기능 유형(일반적으로 차트 유형)을 지원하는 데 필요한 코드가 있습니다. 로드해야 하는 패키지는 각 차트 유형의 문서에 나열되어 있습니다. ChartWrapper를 사용하여 필요한 항목을 자동으로 로드하는 경우 패키지를 지정하지 않아도 됩니다.
language
차트의 일부일 수 있는 텍스트를 맞춤설정하기 위한 언어 또는 언어입니다. 자세한 내용은 언어를 참고하세요.
콜백
패키지가 로드된 후 호출할 함수입니다. 또는 위 예와 같이 google.charts.setOnLoadCallback을 호출하여 이 함수를 지정할 수 있습니다. 자세한 내용은 콜백을 참조하세요.
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
지도 API 키
(v45) 이 설정을 통해 지역 차트지도 차트와 함께 사용할 수 있는 키를 지정할 수 있습니다. 기본 동작을 사용하는 대신 이 작업을 수행할 수 있으며 이로 인해 사용자에게 서비스 제한이 가끔 발생할 수 있습니다. 'Google Maps JavaScript API' 서비스를 사용하기 위한 자체 키를 설정하는 방법은 다음을 참고하세요. 키/인증 가져오기 코드는 다음과 같습니다.
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
안전 모드
(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를 사용하여 콜백 함수를 2개 이상 등록하거나 여러 함수를 하나의 함수로 결합할 수 있습니다. 한 페이지에 여러 차트를 그리기에 관해 자세히 알아보세요.

  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);

프로미스를 사용할 때의 한 가지 이점은 더 많은 .then(anotherFunction) 호출을 체이닝하여 더 많은 차트를 쉽게 그릴 수 있다는 것입니다. 프로미스를 사용하면 콜백에 필요한 특정 패키지와도 콜백이 연결되며, 이는 또 다른 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>
      

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