หน้านี้จะแสดงวิธีโหลดไลบรารีของ Google Chart
การโหลดไลบรารีพื้นฐาน
หน้าเว็บทุกหน้าที่มี Google Charts ควรจะมีบรรทัดต่อไปนี้ใน <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 Maps เวอร์ชันอย่างเป็นทางการล่าสุด หากต้องการทดลองใช้รุ่นถัดไป
ให้ใช้ 'upcoming'
แทน โดยทั่วไปแล้ว ทั้ง 2 แบบจะมีความแตกต่างเพียงเล็กน้อยมากและจะยังคงแตกต่างกันทุกประการ ยกเว้นว่าจะเปิดตัวเพลงใหม่เมื่อใด สาเหตุทั่วไปที่ใช้ upcoming
คือคุณต้องการทดสอบประเภทแผนภูมิหรือฟีเจอร์ใหม่ที่ Google จะเปิดตัวใน 1 หรือ 2 เดือนข้างหน้า (เราประกาศเรื่องประกาศที่กําลังจะมีขึ้นในฟอรัมและขอแนะนําให้คุณลองใช้เมื่อประกาศแล้ว เพื่อให้แน่ใจว่าการเปลี่ยนแปลงแผนภูมิของคุณจะยอมรับได้)
ตัวอย่างข้างต้นจะถือว่าคุณต้องการแสดง corechart
(แท่ง คอลัมน์ เส้น พื้นที่ พื้นที่ขั้นบันได ลูกโป่ง พาย โดนัท คอมโบ เชิงเทียน ฮิสโตแกรม แผนภูมิกระจาย) หากต้องการใช้แผนภูมิประเภทอื่นหรือเพิ่มเติม โปรดแทนที่หรือเพิ่มชื่อแพ็กเกจที่เหมาะสมสําหรับ corechart
ด้านบน (เช่น {packages: ['corechart',
'table', 'sankey']}
ดูชื่อแพ็กเกจได้ในส่วน "กําลังโหลด" ของหน้าเอกสารประกอบสําหรับแต่ละแผนภูมิ
ตัวอย่างนี้ยังสมมติว่าคุณมีฟังก์ชัน JavaScript ชื่อ drawChart
ซึ่งกําหนดไว้ที่ใดที่หนึ่งในหน้าเว็บของคุณ คุณจะตั้งชื่อฟังก์ชันนั้นได้ตามต้องการ แต่โปรดตรวจสอบว่า URL นั้นไม่ซ้ํากันทั่วโลกและได้รับการกําหนดไว้ก่อนที่คุณจะอ้างอิงในการเรียกใช้ google.charts.setOnLoadCallback
หมายเหตุ: Google Maps เวอร์ชันก่อนหน้าใช้โค้ดที่ต่างจากด้านบนเพื่อโหลดไลบรารี หากต้องการอัปเดตแผนภูมิที่มีอยู่ให้ใช้โค้ดใหม่ โปรดดูอัปเดตโค้ดตัวโหลดไลบรารี
ลองดูตัวอย่างการวาดแผนภูมิวงกลมโดยใช้เทคนิคการโหลดเบื้องต้นดังนี้
<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 autoload
ของ JSAPI เก่าได้แล้ว แต่ค่าของพารามิเตอร์นี้จะต้องใช้การจัดรูปแบบ JSON และการเข้ารหัส URL ที่เคร่งครัด ใน JavaScript คุณสามารถเข้ารหัส jsonObject
โดยใช้โค้ดนี้ encodeURIComponent(JSON.stringify(jsonObject))
ข้อจำกัด
หากคุณใช้เวอร์ชัน v45 เวอร์ชันก่อนๆ จะมีข้อจํากัดด้านการโหลดที่สําคัญเล็กน้อย 2-3 ข้อ ดังนี้
- คุณสามารถโทรได้เพียง
google.charts.load
เพียงครั้งเดียว แต่คุณระบุแพ็กเกจทั้งหมดที่ต้องใช้ในการโทรครั้งเดียวได้ จึงไม่จําเป็นต้องต่อสายอีก - หากคุณใช้ ChartWrapper คุณต้องโหลดแพ็กเกจทั้งหมดที่ต้องการอย่างชัดเจน แทนที่จะต้องนํา ChartWrapper มาใช้โหลดแพ็กเกจให้คุณโดยอัตโนมัติ
- สําหรับ Geด้านล่างนี้ และแผนภูมิแผนที่ คุณต้องโหลดทั้งตัวโหลดไลบรารีเก่าและตัวโหลดไลบรารีใหม่ ขอย้ําอีกครั้งว่าการดําเนินการนี้เป็นเฉพาะกับเวอร์ชันก่อน 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 Maps ที่ค้าง
แผนภูมิที่ตรึงไว้จะแสดงเป็นตัวเลขและเป็นไปตามรุ่นอย่างเป็นทางการ
หากต้องการโหลดเวอร์ชันที่ตรึงไว้ ให้แทนที่ 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 เพื่อโหลดข้อมูลที่จําเป็นโดยอัตโนมัติ
- language
- โค้ดของภาษาหรือสถานที่ตั้งที่ควรจะใช้ปรับแต่งข้อความที่อาจเป็นส่วนหนึ่งของแผนภูมิ ดูรายละเอียดเพิ่มเติมได้ที่ภาษา
- โค้ดเรียกกลับ
- ฟังก์ชันที่ระบบจะเรียกใช้เมื่อมีการโหลดแพ็กเกจ หรือจะระบุฟังก์ชันนี้โดยเรียกใช้
google.charts.setOnLoadCallback
ตามที่แสดงในตัวอย่างด้านบนก็ได้ ดูรายละเอียดเพิ่มเติมที่การติดต่อกลับgoogle.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
- คีย์ API ของแผนที่
- (v45) การตั้งค่านี้ให้คุณระบุคีย์ที่คุณอาจใช้กับ
แผนภูมิภูมิศาสตร์ และแผนภูมิแผนที่
คุณควรใช้วิธีนี้แทนการใช้ลักษณะการทํางานเริ่มต้น ซึ่งอาจส่งผลให้มีการควบคุมบริการเป็นครั้งคราวให้แก่ผู้ใช้
ดูวิธีตั้งค่าคีย์ของคุณเองโดยใช้บริการ "Google JavaScript JavaScript API" ได้ที่นี่
ดาวน์โหลดคีย์/การตรวจสอบสิทธิ์ โค้ดจะมีลักษณะดังนี้
var myMapsApiKey = 'SomeMagicToSetThis'; google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey });
- โหมดปลอดภัย
- (v47)
เมื่อตั้งค่าเป็น "จริง" แผนภูมิและเครื่องมือเคล็ดลับทั้งหมดที่สร้าง HTML จากข้อมูลที่ผู้ใช้ระบุจะทําความสะอาดโดยการนําองค์ประกอบและแอตทริบิวต์ที่ไม่ปลอดภัยออก
หรือจะโหลดไลบรารีในโหมดปลอดภัยได้โดยใช้ทางลัดที่ยอมรับการตั้งค่าการโหลดเดียวกัน แต่โหลดเวอร์ชัน "ปัจจุบัน" เสมอ
google.charts.safeLoad({ packages: ['corechart'] });
ภาษา
ภาษาใช้สําหรับปรับแต่งข้อความสําหรับประเทศและภาษา โดยจะส่งผลต่อการจัดรูปแบบของค่า เช่น สกุลเงิน วันที่ และตัวเลข
โดยค่าเริ่มต้น Google Maps จะโหลดภาษา "en" คุณลบล้างค่าเริ่มต้นนี้ได้โดยการระบุภาษาอย่างชัดแจ้งในการตั้งค่าการโหลด
หากต้องการโหลดแผนภูมิที่จัดรูปแบบไว้สําหรับภาษาหนึ่งๆ ให้ใช้การตั้งค่า language
แบบนี้
// Load Google Charts for the Japanese locale. google.charts.load('current', {'packages':['corechart'], 'language': 'ja'});
ไปที่ลิงก์นี้เพื่อดูตัวอย่างแบบเรียลไทม์
ติดต่อกลับ
ก่อนที่จะใช้แพ็กเกจทั้งหมดที่ google.charts.load
โหลดได้ คุณต้องรอให้การโหลดเสร็จสมบูรณ์ การรอให้เอกสารโหลดเสร็จยังไม่เพียงพอ เนื่องจากจะต้องใช้เวลาสักครู่ก่อนที่การโหลดนี้จะเสร็จสมบูรณ์ คุณจึงต้องลงทะเบียนฟังก์ชันเรียกกลับ ซึ่งทําได้ 3 วิธีด้วยกัน ระบุการตั้งค่า callback
ในการเรียก google.charts.load
หรือเรียกใช้ setOnLoadCallback
ที่ส่งผ่านฟังก์ชันเป็นอาร์กิวเมนต์ หรือใช้ Promise ที่การเรียก google.charts.load
โปรดทราบว่าในทุกวิธีเหล่านี้ คุณจะต้องระบุคํานิยามฟังก์ชันแทนการเรียกใช้ฟังก์ชัน คําจํากัดความของฟังก์ชันที่คุณระบุอาจเป็นฟังก์ชันที่มีชื่อ (คุณเพียงแค่ตั้งชื่อเท่านั้น) หรือฟังก์ชันที่ไม่ระบุตัวตน เมื่อโหลดแพ็กเกจเสร็จแล้ว ระบบจะเรียกใช้ฟังก์ชันเรียกกลับนี้โดยไม่มีอาร์กิวเมนต์ ตัวโหลดกําลังรอให้เอกสารโหลดเสร็จก่อนที่จะเรียกใช้โค้ดเรียกกลับ
หากต้องการวาดแผนภูมิมากกว่า 1 แผนภูมิ คุณสามารถลงทะเบียนฟังก์ชันเรียกกลับได้มากกว่า 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 ยังเชื่อมโยงการเรียกโค้ดกลับไปยังแพ็กเกจที่เจาะจงที่จําเป็นสําหรับการเรียกกลับดังกล่าวด้วย ซึ่งมีความสําคัญ หากต้องการโหลดแพ็กเกจที่มีการเรียก 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> |
หากต้องการอัปเดตแผนภูมิที่มีอยู่ คุณสามารถแทนที่โค้ดตัวโหลดไลบรารีเก่าด้วยโค้ดใหม่ได้ แต่โปรดคํานึงถึงข้อจํากัดเกี่ยวกับการโหลดไลบรารีที่อธิบายไว้ข้างต้น