กิจกรรมการจัดการ

หน้านี้อธิบายวิธีฟังและจัดการเหตุการณ์ที่แผนภูมิเริ่มทำงาน

เนื้อหา

ภาพรวม

แผนภูมิของ Google จะเริ่มเหตุการณ์ที่คุณฟังได้ เหตุการณ์สามารถทริกเกอร์ได้จากการกระทำของผู้ใช้ เช่น เมื่อผู้ใช้คลิกแผนภูมิ คุณลงทะเบียนเมธอด JavaScript เพื่อให้ระบบเรียกใช้ได้ทุกครั้งที่เหตุการณ์บางอย่างเริ่มทำงาน โดยอาจมีข้อมูลเฉพาะสำหรับเหตุการณ์ดังกล่าว

แผนภูมิทุกรายการจะระบุเหตุการณ์ของตัวเอง และเอกสารประกอบสำหรับแผนภูมินั้นควรอธิบายเวลาที่เหตุการณ์แต่ละรายการเริ่มทำงาน ความหมาย และวิธีดึงข้อมูลที่เชื่อมโยงกับเหตุการณ์นั้นๆ กลับมา หน้านี้จะอธิบายวิธีลงทะเบียนเพื่อรับเหตุการณ์จากแผนภูมิ และวิธีจัดการ

มี 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());
});

การดึงข้อมูลกิจกรรม

โดยทั่วไปเหตุการณ์จะเปิดเผยข้อมูลได้ 2 วิธี ได้แก่ การส่งผ่านข้อมูลไปยังฟังก์ชันของเครื่องจัดการเป็นพารามิเตอร์ หรือโดยการเพิ่มข้อมูลลงในออบเจ็กต์ส่วนกลาง คุณควรอธิบายกรณีและวิธีการที่เหตุการณ์แสดงข้อมูลในเอกสารสำหรับแผนภูมินั้น ต่อไปนี้เป็นวิธีเรียกข้อมูลทั้ง 2 ประเภท

ข้อมูลเหตุการณ์ที่ส่งผ่านไปยังเครื่องจัดการ

หากแผนภูมิส่งข้อมูลเป็นพารามิเตอร์ไปยังฟังก์ชันการจัดการ คุณจะเรียกข้อมูลได้ดังที่แสดงที่นี่

// 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" ได้รับการออกแบบโดยมีข้อกำหนดต่อไปนี้

• เหตุการณ์ที่เลือกไม่ส่งพร็อพเพอร์ตี้หรือออบเจ็กต์ไปยังตัวแฮนเดิล (ตัวแฮนเดิลฟังก์ชันไม่ควรคาดหวังให้มีการส่งพารามิเตอร์ใดๆ ไปยังตัวแฮนเดิล)
• แผนภูมิควร แสดงเมธอด getSelection() ซึ่งแสดงผลอาร์เรย์ของออบเจ็กต์ที่อธิบายองค์ประกอบข้อมูลที่เลือก ออบเจ็กต์เหล่านี้มีพร็อพเพอร์ตี้ row และ column row และ column คือดัชนีแถวและคอลัมน์ของรายการที่เลือกใน DataTable (เหตุการณ์การเลือกจะอธิบายข้อมูลที่สำคัญในกราฟ ไม่ใช่องค์ประกอบ HTML ในแผนภูมิ) หากต้องการรับข้อมูลของรายการที่เลือก คุณจะต้องโทรหา DataTable.getValue() หรือ getFormattedValue()
  หากระบุทั้ง row และ column องค์ประกอบที่เลือกจะเป็นเซลล์ หากระบุเฉพาะ row องค์ประกอบที่เลือกจะเป็นแถว หากระบุเฉพาะ column องค์ประกอบที่เลือกจะเป็นคอลัมน์
• แผนภูมิควร แสดงเมธอด setSelection(selection) เพื่อเปลี่ยนการเลือกในตารางที่สำคัญ และเลือกข้อมูลที่เกี่ยวข้องในแผนภูมิ พารามิเตอร์ 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()

โดยทั่วไป แผนภูมิที่แสดงเหตุการณ์ "พร้อม" ได้รับการออกแบบโดยมีข้อกำหนดต่อไปนี้

• เหตุการณ์ที่พร้อมใช้จะไม่ส่งผ่านพร็อพเพอร์ตี้ใดๆ ไปยังเครื่องจัดการ (เครื่องจัดการฟังก์ชันไม่ควรคาดหวังให้มีการส่งพารามิเตอร์ใดๆ ไปยังเครื่องจัดการ)
• แผนภูมิควร เริ่มการทำงานของเหตุการณ์ Ready หลังจากที่แผนภูมิพร้อมสำหรับการโต้ตอบ หากภาพวาดแผนภูมิเป็นแบบไม่พร้อมกัน สิ่งสำคัญคือต้องให้เหตุการณ์เริ่มทำงานเมื่อมีการเรียกใช้วิธีการโต้ตอบจริง ไม่ใช่เฉพาะเมื่อเมธอด draw สิ้นสุดลงเท่านั้น
• คุณควรเพิ่ม Listener เหตุการณ์นี้ก่อนที่จะเรียกใช้เมธอด draw() เพราะมิฉะนั้น เหตุการณ์อาจเริ่มทำงานก่อนที่จะตั้งค่า Listener และคุณจะตรวจจับไม่ได้
• การเรียกวิธีการโต้ตอบก่อนที่เหตุการณ์พร้อมจะเริ่มทำงานนั้น คุณมีความเสี่ยงที่วิธีการเหล่านี้จะทำงานอย่างไม่ถูกต้อง

กฎคือแผนภูมิที่ไม่เริ่มการทำงานของเหตุการณ์ "พร้อม" จะพร้อมสำหรับการโต้ตอบทันทีหลังจากที่เมธอด draw สิ้นสุดลงและแสดงผลการควบคุมให้แก่ผู้ใช้ หากแผนภูมิทำให้เหตุการณ์พร้อมใช้งานเริ่มทำงาน คุณควรรอให้มีการส่งเหตุการณ์ก่อนเรียกใช้เมธอดในเหตุการณ์ ดังที่แสดงด้านล่าง

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

ไวยากรณ์ Ready Event Handler

function myReadyHandler(){...}

เครื่องจัดการเหตุการณ์ที่พร้อมใช้จะไม่ส่งผ่านพารามิเตอร์ใดๆ

เหตุการณ์ข้อผิดพลาด

แผนภูมิควรจะแสดงเหตุการณ์ที่ผิดพลาดเมื่อพบข้อผิดพลาดบางอย่าง เพื่อให้คุณจัดการได้อย่างสวยงาม เครื่องจัดการเหตุการณ์จะส่งผ่านคำอธิบายของข้อผิดพลาด ตลอดจนพร็อพเพอร์ตี้เหตุการณ์ที่กำหนดเองสำหรับแต่ละแผนภูมิโดยเฉพาะ คุณควรสมัครใช้บริการเหตุการณ์นี้ทันทีหลังจากสร้างแผนภูมิเพื่อดักจับข้อผิดพลาดที่อาจเกิดขึ้นในขั้นตอนหลังจากนี้

คุณสามารถใช้ฟังก์ชันตัวช่วยของ goog.visualization.errors เพื่อช่วยให้แสดงข้อผิดพลาดแก่ผู้ใช้ได้อย่างแนบเนียน

ไวยากรณ์ตัวแฮนเดิลเหตุการณ์ข้อผิดพลาด

function myErrorHandler(err){...}

เครื่องจัดการเหตุการณ์ที่มีข้อผิดพลาดควรส่งผ่านออบเจ็กต์ที่มีสมาชิกต่อไปนี้

• id [ต้องระบุ] - รหัสขององค์ประกอบ DOM ที่มีแผนภูมิ หรือข้อความแสดงข้อผิดพลาดที่แสดงแทนแผนภูมิหากแสดงผลไม่ได้
• message [ต้องระบุ] - สตริงข้อความสั้นๆ ที่อธิบายข้อผิดพลาด
• detailedMessage [ไม่บังคับ] - คำอธิบายข้อผิดพลาดโดยละเอียด
• options [Optional]- ออบเจ็กต์ที่มีพารามิเตอร์ที่กำหนดเองที่เหมาะกับข้อผิดพลาดและประเภทแผนภูมินี้

ตัวอย่างการจัดการเหตุการณ์

ตัวอย่างต่อไปนี้แสดงทั้ง getSelection() และ setSelection() โดยจะซิงค์การเลือกระหว่าง 2 แผนภูมิที่ใช้ตารางข้อมูลเดียวกัน คลิกที่แผนภูมิเพื่อซิงค์ข้อมูลการเลือกในแผนภูมิอื่น

// 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());
});

คลิกที่แผนภูมิด้านล่างบนแถวของตารางหรือองค์ประกอบของแผนภูมิ เพื่อดูการทำงานของการเลือก