이벤트 처리

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

목차

개요

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

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

선택 가능한 차트에서 실행해야 하는 한 가지 이벤트는 select 이벤트입니다. 그러나 이 이벤트의 동작과 의미는 각 차트에서 정의됩니다.

차트 이벤트는 표준 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']);
}

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

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

일부 이벤트는 대신 전역 객체의 속성을 변경하며 이를 요청할 수 있습니다. 이에 대한 일반적인 예로는 사용자가 차트의 일부를 선택할 때 발생하는 'select' 이벤트가 있습니다. 이 경우 코드는 차트에서 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' 이벤트를 실행해야 합니다. 하지만 차트가 이러한 방식으로 작동해야 한다는 절대적인 요구사항은 없습니다. 차트에 관한 문서를 확인하세요.

일반적으로 'select' 이벤트를 노출하는 차트는 다음과 같은 사양에 따라 디자인됩니다.

• select 이벤트는 어떠한 속성 또는 객체도 핸들러에 전달하지 않습니다 (함수 핸들러는 매개변수가 전달될 것으로 예상해서는 안 됨).
• 차트는 선택한 데이터 요소를 설명하는 객체의 배열을 반환하는 getSelection() 메서드를 노출해야 합니다 . 이러한 객체에는 row 및 column 속성이 있습니다. row 및 column는 DataTable에서 선택된 항목의 행 및 열 색인입니다. 선택 이벤트는 차트의 HTML 요소가 아닌 그래프의 기본 데이터를 설명합니다. 선택한 항목의 데이터를 가져오려면 DataTable.getValue() 또는 getFormattedValue()를 호출해야 합니다.
  row와 column가 모두 지정된 경우 선택된 요소는 셀입니다. row만 지정된 경우 선택한 요소는 행입니다. column만 지정된 경우 선택한 요소는 열입니다.
• 차트는 setSelection(selection) 메서드를 노출하여 기본 테이블의 선택사항을 변경하고 차트에서 해당 데이터를 선택해야 합니다 . getSelection() 배열과 유사한 배열인 selection 매개변수입니다. 여기서 각 요소는 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);
}

ready 이벤트

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

일반적으로 'ready' 이벤트를 노출하는 차트는 다음과 같은 사양에 따라 디자인됩니다.

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

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

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

준비된 이벤트 핸들러 구문

function myReadyHandler(){...}

ready 이벤트 핸들러에 매개변수가 전달되지 않습니다.

error 이벤트

차트에서 일종의 오류가 발생하면 원활하게 처리할 수 있도록 오류 이벤트를 발생시켜야 합니다. 이벤트 핸들러에는 오류에 대한 설명과 각 차트별 맞춤 이벤트 속성이 전달됩니다. 이후 단계에서 발생할 수 있는 오류를 잡아내려면 차트를 인스턴스화한 직후에 이 이벤트를 구독해야 합니다.

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

오류 이벤트 핸들러 구문

function myErrorHandler(err){...}

오류 이벤트 핸들러는 다음 멤버가 포함된 객체를 전달해야 합니다.

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

이벤트 처리 예

다음 예에서는 getSelection()과 setSelection()을 모두 보여줍니다. 동일한 데이터 테이블을 사용하는 두 차트 간에 선택사항을 동기화합니다. 두 차트 중 하나를 클릭하면 다른 차트의 선택사항을 동기화할 수 있습니다.

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

var orgchart = new google.visualization.OrgChart(document.getElementById('org_div'));
orgchart.draw(data, {});

// When the table is selected, update the orgchart.
google.visualization.events.addListener(table, 'select', function() {
  orgchart.setSelection(table.getSelection());
});

// When the orgchart is selected, update the table chart.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

아래 차트에서 표의 행 또는 차트 요소를 클릭하면 선택사항을 확인할 수 있습니다.