이 페이지는 Cloud Translation API를 통해 번역되었습니다.

이벤트 처리

이 페이지에서는 차트로 실행된 이벤트를 수신 대기하고 처리하는 방법을 설명합니다.

개요

Google 차트에서 리슨할 수 있는 이벤트를 실행할 수 있습니다. 이벤트는 사용자가 차트를 클릭할 때와 같은 사용자 작업에 의해 트리거될 수 있습니다. 특정 이벤트가 발생할 때마다 호출되는 자바스크립트 메서드를 등록하고 해당 이벤트와 관련된 데이터를 사용할 수 있습니다.

모든 차트는 자체 이벤트를 정의하며, 해당 차트의 문서에는 각 이벤트가 발생한 시점, 의미, 이벤트와 관련된 정보를 가져오는 방법이 설명되어 있어야 합니다. 이 페이지에서는 차트에서 이벤트를 수신하도록 등록하는 방법과 이를 처리하는 방법을 설명합니다.

선택 가능한 차트 중 하나를 실행해야 하는 이벤트가 1개 있습니다. 그러나 이 이벤트의 행동과 의미는 각 차트에서 정의됩니다.

차트 이벤트는 표준 DOM 이벤트와 별개이며 서로 다릅니다.

이벤트 등록 및 처리

이벤트 핸들러를 등록하려면 이벤트를 노출하는 차트의 이름, 수신 대기할 이벤트의 문자열 이름, 이벤트가 발생했을 때 호출할 함수의 이름을 사용해 google.visualization.events.addListener() 또는 addOneTimeListener()를 호출합니다. 함수는 실행된 이벤트인 단일 매개변수를 허용해야 합니다. 차트 문서에 설명된 대로 이 이벤트에는 이벤트에 관한 맞춤 정보가 포함될 수 있습니다.

중요: 차트에 준비된 이벤트가 표시되는 경우 차트에서 메서드를 전송하거나 수신하려고 하기 전에 항상 해당 이벤트가 실행될 때까지 기다려야 합니다. 이러한 차트는 준비 이벤트가 발생하기 전에 작동할 수 있지만 이 동작은 보장되지 않습니다.

다음 코드 스니펫은 사용자가 테이블 행을 클릭할 때마다 알림 상자를 보여줍니다.

// Create a table chart on your page.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Every time the table fires the "select" event, it should call your
// selectHandler() function.
google.visualization.events.addListener(table, 'select', selectHandler);

function selectHandler(e) {
  alert('A table row was selected');
}

이 메서드는 특정 테이블 객체의 이벤트를 수신 대기할 때만 등록하며, 특정 객체의 이벤트를 수신하도록만 등록할 수 있습니다.

다음과 같이 함수 정의를 전달할 수도 있습니다.

// Pass in a function definition.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

이벤트 정보 가져오기

이벤트는 일반적으로 핸들러 함수에 정보를 매개변수로 전달하거나 정보를 전역 객체에 추가하는 방식으로 정보를 노출합니다. 이벤트가 정보를 노출하는지 여부 및 방법은 차트의 문서에 설명되어야 합니다. 두 가지 유형의 정보를 모두 가져오는 방법은 다음과 같습니다.

핸들러에 전달되는 이벤트 정보

차트가 데이터를 처리 함수에 매개변수로 전달하면 다음과 같이 데이터를 검색할 수 있습니다.

// google.visualization.table exposes a 'page' event.
google.visualization.events.addListener(table, 'page', myPageEventHandler);
...
function myPageEventHandler(e) {
  alert('The user is navigating to page ' + e['page']);
}

핸들러에 전달된 매개변수에는 차트에 문서화되어야 하는 속성이 포함됩니다. 이러한 방식으로 이벤트 정보를 노출하는 차트의 예는 테이블 차트의 페이지 이벤트를 참조하세요.

전역 객체로 전달되는 이벤트 정보

대신 일부 이벤트는 전역 객체의 속성을 변경한 후 요청할 수 있습니다. 이에 관한 일반적인 예로 사용자가 차트의 일부를 선택하면 실행되는 '선택' 이벤트가 있습니다. 이 경우 코드에서 차트에서 getSelection()을 호출하여 현재 선택 항목이 무엇인지 확인해야 합니다. 자세한 내용은 아래의 선택 이벤트를 참고하세요.

// orgChart is my global orgchart chart variable.
google.visualization.events.addListener(orgChart, 'select', selectHandler);
...
// Notice that e is not used or needed.
function selectHandler(e) {
  alert('The user selected' + orgChart.getSelection().length + ' items.');

select 이벤트

앞서 언급했듯이 선택 가능한 모든 차트에서는 차트에서 선택한 항목의 값을 가져올 수 있도록 표준 방식으로 작동하는 '선택' 이벤트를 실행해야 합니다. (그러나 차트가 이러한 방식으로 작동해야 하는 절대 요구사항은 없습니다. 차트 문서를 확인하세요.)

일반적으로 'select' 이벤트를 노출하는 차트는 다음과 같은 사양으로 설계됩니다.

선택 이벤트는 속성이나 객체를 핸들러에 전달하지 않습니다 (함수 핸들러는 전달된 매개변수가 예상되지 않아야 함).
차트는 선택된 데이터 요소를 설명하는 객체의 배열을 반환하는 getSelection() 메서드를 표시해야 합니다. 이러한 객체에는 row 및 column 속성이 있습니다. row 및 column는 DataTable에서 선택된 항목의 행 및 열 색인입니다. 선택 이벤트는 차트의 HTML 요소가 아닌 그래프의 기본 데이터를 설명합니다. 선택한 항목의 데이터를 가져오려면 DataTable.getValue() 또는 getFormattedValue()를 호출해야 합니다.
row 및 column가 모두 지정된 경우 선택된 요소는 셀입니다. row만 지정된 경우 선택한 요소는 행입니다. column만 지정된 경우 선택한 요소가 열입니다.
차트는 setSelection(selection) 메서드를 노출하여 기본 테이블에서 선택을 변경하고 차트에서 해당하는 데이터를 선택해야 합니다. 선택 매개변수: getSelection() 배열과 유사한 배열입니다. 여기서 각 요소는 row 및 column 속성이 있는 객체입니다. row 속성은 DataTable에서 선택된 행의 색인을 정의하고 column 속성은 DataTable에서 선택한 열의 색인을 정의합니다. 이 메서드가 호출되면 차트는 새 선택이 무엇인지 시각적으로 나타내야 합니다. setSelection()의 구현은 'select' 이벤트를 트리거하면 안 됩니다.
row 및 column가 모두 지정된 경우 선택된 요소는 셀입니다. row만 지정된 경우 선택한 요소는 행입니다. column만 지정된 경우 선택한 요소가 열입니다.

주의사항:

차트가 일부 선택을 무시할 수 있습니다. 예를 들어 선택한 행만 표시할 수 있는 표는 setSelection 구현에서 셀 또는 열 요소를 무시할 수 있습니다.
일부 차트는 '선택' 이벤트를 트리거하지 않을 수 있으며, 일부 차트는 전체 행 선택 또는 전체 열 선택만 지원할 수도 있습니다. 각 차트의 문서는 차트에서 지원하는 이벤트와 메서드를 정의합니다.
다중 선택은 서로 다른 차트에서 서로 다르게 처리됩니다 (일부는 허용하지 않음).
선택한 데이터를 읽으려면 핸들러에서 DataTable.getValue()를 호출해야 합니다. 이를 사용 설정하는 가장 간단한 방법은 DataTable 객체를 전역으로 설정하는 것입니다.

다음 예시에서는 테이블 차트의 요소가 선택되면 선택한 테이블 요소가 포함된 알림 상자를 표시합니다.

표 차트는 행 선택 이벤트만 실행합니다. 하지만 코드는 일반적이며 행, 열, 셀 선택 이벤트에 사용할 수 있습니다.

이 예의 핸들러 코드는 다음과 같습니다.

// Create our table.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Add our selection handler.
google.visualization.events.addListener(table, 'select', selectHandler);

// The selection handler.
// Loop through all items in the selection and concatenate
// a single message from all of them.
function selectHandler() {
  var selection = table.getSelection();
  var message = '';
  for (var i = 0; i < selection.length; i++) {
    var item = selection[i];
    if (item.row != null && item.column != null) {
      var str = data.getFormattedValue(item.row, item.column);
      message += '{row:' + item.row + ',column:' + item.column + '} = ' + str + '\n';
    } else if (item.row != null) {
      var str = data.getFormattedValue(item.row, 0);
      message += '{row:' + item.row + ', column:none}; value (col 0) = ' + str + '\n';
    } else if (item.column != null) {
      var str = data.getFormattedValue(0, item.column);
      message += '{row:none, column:' + item.column + '}; value (row 0) = ' + str + '\n';
    }
  }
  if (message == '') {
    message = 'nothing';
  }
  alert('You selected ' + message);
}

준비된 이벤트

대부분의 차트는 비동기식으로 렌더링됩니다. 모든 Google 차트는 draw()를 호출한 후 준비된 이벤트를 발생시키며, 이는 차트가 렌더링되고 속성을 반환하거나 추가 메서드 호출을 처리할 준비가 되었음을 나타냅니다. draw()를 호출한 후 항상 준비 이벤트를 수신 대기하기 전에 대기해야 합니다.

일반적으로 '준비됨' 이벤트를 노출하는 차트는 다음과 같은 사양으로 설계됩니다.

준비된 이벤트는 어떤 속성도 핸들러에 전달하지 않습니다 (함수 핸들러는 전달된 매개변수가 없어야 함).
차트가 상호작용할 준비가 되면 차트에서 준비된 이벤트를 실행해야 합니다. 차트 그리기가 비동기식인 경우 draw 메서드가 종료될 때뿐만 아니라 상호작용 메서드를 실제로 호출할 수 있을 때 이벤트를 실행하는 것이 중요합니다.
draw() 메서드를 호출하기 전에 이 이벤트에 리스너를 추가해야 합니다. 그러지 않으면 리스너가 설정되기 전에 이벤트가 발생할 수 있으므로 포착하지 못하게 됩니다.
준비된 이벤트가 실행되기 전에 상호작용 메서드를 호출하면 이러한 메서드가 제대로 작동하지 않을 위험이 있습니다.

규칙에 따라 '준비된' 이벤트를 실행하지 않는 차트는 draw 메서드가 종료되고 사용자에게 제어 권한을 반환한 직후에 상호작용할 수 있습니다. 차트가 준비된 이벤트를 실행하는 경우 아래와 같이 메서드를 호출하기 전에 이 이벤트가 발생할 때까지 기다려야 합니다.

google.visualization.events.addListener(tableChart, 'ready', myReadyHandler);

준비된 이벤트 핸들러 구문

function myReadyHandler(){...}

준비된 이벤트 핸들러는 어떠한 매개변수도 전달되지 않습니다.

error 이벤트

차트에서 오류가 발생하는 경우 오류 이벤트를 발생시켜 적절하게 처리할 수 있어야 합니다. 이벤트 핸들러에는 각 차트에 해당하는 맞춤 이벤트 속성과 함께 오류에 대한 설명이 전달됩니다. 이후 단계에서 발생할 수 있는 오류를 포착하려면 차트를 인스턴스화한 후에 바로 이 이벤트를 구독해야 합니다.

goog.visualization.errors 도우미 함수를 사용하여 모든 오류를 사용자에게 적절하게 표시할 수 있습니다.

오류 이벤트 핸들러 구문

function myErrorHandler(err){...}

오류 이벤트 핸들러에 다음 멤버와 함께 객체를 전달해야 합니다.

id[필수] - 차트를 포함하는 DOM 요소의 ID 또는 렌더링할 수 없는 경우 차트 대신 표시되는 오류 메시지를 표시합니다.
message[필수] - 오류를 설명하는 짧은 메시지 문자열입니다.
detailedMessage[선택사항] - 오류에 대한 자세한 설명입니다.
options[선택사항]- 이 오류 및 차트 유형에 적합한 맞춤 매개변수가 포함된 객체입니다.