หน้านี้ได้รับการแปลโดย Cloud Translation API

โหลดไลบรารี

หน้านี้แสดงวิธีโหลดไลบรารีของ 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 ได้อย่างน้อย 1 ครั้งเพื่อโหลดแพ็กเกจสำหรับแผนภูมิบางประเภท

อาร์กิวเมนต์ตัวแรกของ google.charts.load คือชื่อหรือหมายเลขเวอร์ชัน เป็นสตริง หากคุณระบุ 'current' การดำเนินการนี้จะทำให้ระบบโหลด Google Charts รุ่นล่าสุดอย่างเป็นทางการ หากต้องการลองใช้ผู้สมัครสำหรับรุ่นถัดไป ให้ใช้ 'upcoming' แทน โดยทั่วไป ทั้ง 2 แบบจะมีความแตกต่างเพียงเล็กน้อยมากและแทบจะเหมือนกันทั้งหมด ยกเว้นเมื่อมีการเปิดตัวรุ่นใหม่ เหตุผลทั่วไปในการใช้ upcoming คือคุณต้องการทดสอบประเภทแผนภูมิหรือฟีเจอร์ใหม่ที่ Google จะเปิดตัวใน 2-3 เดือนข้างหน้า (เราประกาศการเปิดตัวที่กำลังจะมีขึ้นในฟอรัมของเรา และขอแนะนำให้คุณลองใช้เมื่อประกาศ เพื่อให้แน่ใจว่าการเปลี่ยนแปลงแผนภูมิจะยอมรับได้)

ตัวอย่างด้านบนสมมติว่าคุณต้องการแสดง corechart (แท่ง คอลัมน์ เส้น พื้นที่ พื้นที่ขั้นบันได ลูกโป่ง วงกลม โดนัท ชุดผสม แท่งเทียน ฮิสโตแกรม กระจาย) หากต้องการใช้แผนภูมิประเภทอื่นหรือแผนภูมิเพิ่มเติม ให้ใช้แทนหรือเพิ่มชื่อแพ็กเกจที่เหมาะสมสำหรับ corechart ด้านบน (เช่น {packages: ['corechart', 'table', 'sankey']}. คุณสามารถดูชื่อแพ็กเกจในส่วน "การโหลด" ของหน้าเอกสารของแต่ละแผนภูมิ

ตัวอย่างนี้จะสมมติว่าคุณมีฟังก์ชัน JavaScript ชื่อ 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>

รายละเอียดการโหลด

ก่อนอื่นคุณต้องโหลดตัวโหลดเอง ซึ่งทำในแท็ก script แยกต่างหากด้วย src="https://www.gstatic.com/charts/loader.js" แท็กนี้สามารถอยู่ใน head หรือ body ของเอกสาร หรือแทรกแบบไดนามิกลงในเอกสารขณะโหลดหรือหลังจากโหลดเสร็จแล้วก็ได้

<script src="https://www.gstatic.com/charts/loader.js"></script>

หลังจากโหลดตัวโหลดแล้ว คุณสามารถโทรหา google.charts.load ตำแหน่งที่คุณเรียกอาจอยู่ในแท็ก script ใน head หรือ body ของเอกสาร โดยคุณจะเรียกใช้ขณะที่เอกสารยังโหลดอยู่หรือเมื่อใดก็ได้หลังจากที่โหลดเอกสารเสร็จแล้ว

ตั้งแต่เวอร์ชัน 45 คุณอาจเรียกใช้ google.charts.load มากกว่า 1 ครั้งเพื่อโหลดแพ็กเกจเพิ่มเติม แต่จะปลอดภัยขึ้นหากหลีกเลี่ยงการดำเนินการดังกล่าว คุณจะต้องตั้งค่าหมายเลขเวอร์ชันและภาษาให้เหมือนกันทุกครั้ง

ตอนนี้คุณใช้พารามิเตอร์ URL เก่าของ JSAPI autoload ได้แล้ว แต่ค่าของพารามิเตอร์นี้ต้องใช้การจัดรูปแบบ JSON และการเข้ารหัส URL ที่เข้มงวด ใน JavaScript คุณใช้การเข้ารหัส jsonObject ได้ด้วยโค้ดนี้ encodeURIComponent(JSON.stringify(jsonObject))

ข้อจำกัด

หากคุณใช้เวอร์ชันก่อน v45 การโหลด Google แผนภูมิจะมีข้อจำกัดเล็กๆ น้อยๆ ที่สำคัญบางประการดังนี้

คุณสามารถโทรหา google.charts.load ได้เพียงครั้งเดียวเท่านั้น แต่คุณแสดงแพ็กเกจทั้งหมดที่จะต้องใช้ในการโทรครั้งเดียวได้ จึงไม่จำเป็นต้องโทรแยกต่างหาก
หากใช้ ChartWrapper คุณต้องโหลดแพ็กเกจทั้งหมดที่ต้องการอย่างชัดแจ้ง แทนที่จะต้องใช้ ChartWrapper เพื่อโหลดแพ็กเกจให้คุณโดยอัตโนมัติ
สำหรับแผนภูมิภูมิศาสตร์และแผนภูมิแผนที่ คุณต้องโหลดทั้งตัวโหลดไลบรารีเก่าและตัวโหลดไลบรารีใหม่ ขอย้ำอีกครั้งว่านี่เป็นเพียงเวอร์ชันก่อน v45 เท่านั้น และไม่ควรทำเช่นนี้กับเวอร์ชันหลังๆ
```
<script src="https://www.gstatic.com/charts/loader.js"></script>
<script src="https://www.google.com/jsapi"></script>
```

โหลดชื่อหรือหมายเลขเวอร์ชัน

อาร์กิวเมนต์แรกของการเรียก google.charts.load คือชื่อหรือหมายเลขเวอร์ชัน ขณะนี้มีเพียงชื่อเวอร์ชันพิเศษ 2 ชื่อ และเวอร์ชันที่ถูกตรึงไว้หลายเวอร์ชัน

current: สำหรับผลงานอย่างเป็นทางการล่าสุดซึ่งจะมีการเปลี่ยนแปลงทุกครั้งที่เราเผยแพร่รุ่นใหม่ เวอร์ชันนี้ผ่านการทดสอบได้ดีและไม่มีข้อบกพร่อง แต่คุณอาจเลือกระบุเวอร์ชันที่หยุดทำงานแล้วแทนเมื่อพอใจแล้ว
เร็วๆ นี้: นี่เป็นรุ่นถัดไปในขณะที่ยังอยู่ระหว่างการทดสอบและก่อนที่จะกลายเป็นรุ่นปัจจุบันอย่างเป็นทางการ โปรดทดสอบเวอร์ชันนี้เป็นประจำเพื่อให้คุณทราบโดยเร็วที่สุดว่ามีปัญหาใดๆ ที่ควรแก้ไขก่อนที่เวอร์ชันนี้จะกลายเป็นเวอร์ชันอย่างเป็นทางการหรือไม่

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

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

แผนภูมิเวอร์ชันหยุดนิ่งจะระบุด้วยตัวเลข และอธิบายไว้ในรุ่นอย่างเป็นทางการของเรา หากต้องการโหลดเวอร์ชันที่ตรึงไว้ ให้แทนที่ current หรือ upcoming ในการโทร google.charts.load ด้วยหมายเลขเวอร์ชันที่ตรึงไว้ ดังนี้

<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
    google.charts.load('43', {packages: ['corechart']});
    google.charts.setOnLoadCallback(drawChart);
    ...
</script>

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

โหลดการตั้งค่า

พารามิเตอร์ที่ 2 ในการเรียกใช้ google.charts.load คือออบเจ็กต์สำหรับการระบุการตั้งค่า พร็อพเพอร์ตี้ต่อไปนี้รองรับการตั้งค่า

พัสดุ

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

ภาษา

โค้ดสำหรับภาษาหรือสถานที่ที่ควรปรับแต่งข้อความที่อาจเป็นส่วนหนึ่งของแผนภูมิ ดูรายละเอียดเพิ่มเติมได้ที่ภาษา

Callback

ฟังก์ชันที่จะเรียกใช้เมื่อโหลดแพ็กเกจแล้ว หรือจะระบุฟังก์ชันนี้โดยการเรียกใช้ google.charts.setOnLoadCallback ดังที่แสดงในตัวอย่างด้านบนก็ได้ โปรดดูรายละเอียดเพิ่มเติมที่การติดต่อกลับ

  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });

mapsApiKey

(v45) การตั้งค่านี้ช่วยให้คุณระบุคีย์ที่อาจใช้กับแผนภูมิภูมิศาสตร์และแผนภูมิแผนที่ได้ คุณอาจต้องดำเนินการนี้แทนที่จะใช้ลักษณะการทำงานเริ่มต้นซึ่งอาจส่งผลให้มีการควบคุมบริการสำหรับผู้ใช้เป็นครั้งคราว ดูวิธีตั้งค่าคีย์ของคุณเองเพื่อใช้บริการ "Google Maps JavaScript API" ได้ที่นี่ รับคีย์/การตรวจสอบสิทธิ์ รหัสจะมีลักษณะดังนี้

  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });

safeMode

(v47) เมื่อตั้งค่าเป็น "จริง" แผนภูมิและเคล็ดลับเครื่องมือทั้งหมดที่สร้าง 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 ได้ การรอให้เอกสารโหลดเสร็จนั้นไม่เพียงพอ คุณต้องลงทะเบียนฟังก์ชัน Callback เนื่องจากการโหลดนี้อาจใช้เวลาสักครู่จึงจะเสร็จ ซึ่งทำได้ 3 วิธีด้วยกัน ระบุการตั้งค่า callback ในการเรียกใช้ google.charts.load หรือเรียกใช้ setOnLoadCallback ที่ส่งผ่านฟังก์ชันเป็นอาร์กิวเมนต์ หรือใช้ Promise ที่ส่งคืนจากการเรียกใช้ google.charts.load

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

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

  google.charts.setOnLoadCallback(drawChart1);
  google.charts.setOnLoadCallback(drawChart2);
  // OR
  google.charts.setOnLoadCallback(
    function() { // Anonymous function that calls drawChart1 and drawChart2
         drawChart1();
         drawChart2();
      });

ติดต่อกลับผ่าน Promise

อีกวิธีหนึ่งในการลงทะเบียนการติดต่อกลับคือการใช้ Promise ที่ส่งคืนจากการเรียกใช้ google.charts.load ซึ่งทำได้โดยการเพิ่มการเรียกใช้ไปยังเมธอด then() ด้วยโค้ดที่มีลักษณะดังต่อไปนี้

  google.charts.load('upcoming', {packages: ['corechart']}).then(drawChart);

ข้อดีอย่างหนึ่งของการใช้ Promise คือคุณสามารถวาดแผนภูมิเพิ่มเติมได้ง่ายๆ ด้วยการเชื่อมโยงการโทร .then(anotherFunction) ที่มากขึ้น การใช้ Promise จะเชื่อมโยง Callback กับแพ็กเกจเฉพาะที่จำเป็นสำหรับ Callback นั้น ซึ่งมีความสำคัญหากคุณต้องการโหลดแพ็กเกจเพิ่มเติมด้วยการเรียก 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>

โค้ดสำหรับเครื่องมือโหลดไลบรารีเก่า

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

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

ถัดไป: การเตรียม ข้อมูล