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

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

เนื้อหา

1. ภาพรวม
2. การลงทะเบียนและจัดการกิจกรรม
3. การดึงข้อมูลกิจกรรม
4. เหตุการณ์ select
5. กิจกรรมที่พร้อม
6. เหตุการณ์ข้อผิดพลาด
7. ตัวอย่างการจัดการเหตุการณ์

ภาพรวม

แผนภูมิของ 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" ออกแบบมาโดยมีข้อกําหนดดังต่อไปนี้

• เหตุการณ์ที่เลือกไม่ส่งพร็อพเพอร์ตี้หรือออบเจ็กต์ไปยังตัวแฮนเดิล (ตัวควบคุมฟังก์ชันไม่ควรคาดหวังว่าจะส่งพารามิเตอร์ไป)
• แผนภูมิควรเผยแพร่เมธอด 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)
• แผนภูมิบางรายการอาจไม่ทริกเกอร์เหตุการณ์ 'select' และแผนภูมิบางรายการอาจรองรับเฉพาะการเลือกแถวทั้งหมดหรือทั้งคอลัมน์ เอกสารของแต่ละแผนภูมิจะกําหนดเหตุการณ์และวิธีการที่รองรับ
• ระบบจะจัดการการเลือกหลายรายการแตกต่างกันในแผนภูมิต่างๆ (อนุญาตบางส่วนด้วย)
• หากต้องการอ่านข้อมูลที่เลือก คุณจะต้องเรียกใช้ 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 สิ้นสุดลง
• คุณควรเพิ่ม Listener ให้กับเหตุการณ์นี้ก่อนเรียกใช้เมธอด draw() เพราะจะทําให้เหตุการณ์เริ่มทํางานได้ก่อนที่จะตั้งค่า Listener และคุณจะไม่สามารถตรวจจับได้
• การเรียกเมธอดการโต้ตอบก่อนที่เหตุการณ์พร้อมจะเริ่มทํางาน คุณมีความเสี่ยงที่จะทําให้เมธอดเหล่านี้ทํางานไม่ถูกต้อง

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

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

ไวยากรณ์ตัวแฮนเดิลเหตุการณ์ที่พร้อม

function myReadyHandler(){...}

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

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

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

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

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

function myErrorHandler(err){...}

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

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

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

ตัวอย่างต่อไปนี้แสดงทั้ง 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());
});

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