การอัปเกรดแอปพลิเคชัน Maps JavaScript API จาก V2 เป็น V3

Maps JavaScript API v2 จะใช้งานไม่ได้อีกต่อไปตั้งแต่วันที่ 26 พฤษภาคม 2021 ด้วยเหตุนี้ แผนที่ v2 ของเว็บไซต์จะหยุดทำงานและแสดงข้อผิดพลาด JavaScript หากต้องการใช้แผนที่บนเว็บไซต์ต่อไป ให้เปลี่ยนไปใช้ Maps JavaScript API v3 คู่มือนี้จะช่วยคุณ ตลอดขั้นตอน

ภาพรวม

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

  1. รับคีย์ใหม่ ตอนนี้ Maps JavaScript API ใช้ Google Cloud Console เพื่อจัดการคีย์แล้ว หากคุณยังใช้คีย์ v2 อยู่ โปรดรับคีย์ API ใหม่ก่อนที่จะเริ่มการย้ายข้อมูล
  2. อัปเดต Bootstrap สำหรับ API ของคุณ แอปพลิเคชันส่วนใหญ่จะโหลด Maps JavaScript API v3 ด้วยรหัสต่อไปนี้
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
  3. อัปเดตรหัสของคุณ จำนวนการเปลี่ยนแปลงที่ต้องการจะขึ้นอยู่กับแอปพลิเคชันของคุณ การเปลี่ยนแปลงทั่วไปมีดังนี้
    • อ้างอิงเนมสเปซของ google.maps เสมอ ใน v3 โค้ด Maps JavaScript API ทั้งหมดจะจัดเก็บอยู่ในเนมสเปซ google.maps.* แทนเนมสเปซส่วนกลาง ออบเจ็กต์ส่วนใหญ่ก็มีการเปลี่ยนชื่อให้เป็นส่วนหนึ่งของกระบวนการนี้ด้วย ตัวอย่างเช่น ตอนนี้คุณจะโหลด google.maps.Map แทน GMap2
    • นำการอ้างอิงถึงวิธีการที่ล้าสมัยออก มีการนำวิธียูทิลิตีทั่วไปออกหลายรายการ เช่น GDownloadURL และ GLog แทนที่ฟังก์ชันการทำงานนี้ด้วยไลบรารียูทิลิตีของบุคคลที่สาม หรือนำการอ้างอิงเหล่านี้ออกจากโค้ดของคุณ
    • (ไม่บังคับ) เพิ่มไลบรารีลงในโค้ด มีฟีเจอร์หลายรายการที่มีการขยายสู่ไลบรารียูทิลิตี เพื่อให้แต่ละแอปต้องโหลดเฉพาะบางส่วนของ API ที่จะใช้เท่านั้น
    • (ไม่บังคับ) กำหนดค่าโปรเจ็กต์เพื่อใช้ภายนอก v3 คุณสามารถใช้ภายนอก v3 เพื่อช่วยตรวจสอบโค้ดด้วยคอมไพเลอร์การปิด หรือเพื่อทริกเกอร์การเติมข้อความอัตโนมัติใน IDE ดูข้อมูลเพิ่มเติมเกี่ยวกับ การคอมไพล์ขั้นสูงและการซ่อนเนื้อหา
  4. ทดสอบและทำซ้ำ ถึงตอนนี้คุณจะยังคง ยังมีงานต้องทำอีก แต่ข่าวดีคือคุณจะสามารถใช้แอปพลิเคชันแผนที่ v3 ใหม่ได้!

การเปลี่ยนแปลงใน Maps JavaScript API เวอร์ชัน 3

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

การเปลี่ยนแปลงบางอย่างใน API v3 ได้แก่

  • ไลบรารีหลักที่ปรับปรุงประสิทธิภาพ ฟังก์ชันเสริมหลายรายการได้ย้ายไปอยู่ในไลบรารีเพื่อช่วยลดเวลาในการโหลดและการแยกวิเคราะห์สำหรับ Core API ซึ่งช่วยให้แผนที่โหลดได้อย่างรวดเร็วในทุกอุปกรณ์
  • ปรับปรุงประสิทธิภาพของฟีเจอร์หลายรายการ เช่น การแสดงผลรูปหลายเหลี่ยมและ ตำแหน่งเครื่องหมาย
  • แนวทางใหม่ของขีดจำกัดการใช้งานฝั่งไคลเอ็นต์เพื่อรองรับที่อยู่ที่แชร์ซึ่งพร็อกซีอุปกรณ์เคลื่อนที่และไฟร์วอลล์ขององค์กรใช้ได้ดียิ่งขึ้น
  • เพิ่มการรองรับเบราว์เซอร์ที่ทันสมัยและเบราว์เซอร์ในอุปกรณ์เคลื่อนที่หลายรายการ การรองรับ Internet Explorer 6 ถูกนำออกแล้ว
  • นำคลาสตัวช่วยสำหรับวัตถุประสงค์ทั่วไปออก ( GLog หรือ GDownloadUrl) ปัจจุบันมีไลบรารี JavaScript ที่ยอดเยี่ยมจำนวนมากที่มีฟังก์ชันการทำงานคล้ายกัน เช่น Closure หรือ jQuery
  • การติดตั้งใช้งาน Street View HTML5 ที่จะโหลดบนอุปกรณ์เคลื่อนที่
  • ภาพพาโนรามา Street View ที่กำหนดเองด้วยรูปภาพของคุณเอง ซึ่งช่วยให้คุณสามารถแชร์ภาพพาโนรามาของลานสกี บ้านที่ประกาศขาย หรือสถานที่ที่น่าสนใจอื่นๆ ได้
  • การปรับแต่งแผนที่ที่มีการจัดรูปแบบ ซึ่งให้คุณเปลี่ยนการแสดงองค์ประกอบบนแผนที่ฐานให้เข้ากับสไตล์ภาพที่เป็นเอกลักษณ์ของคุณ
  • รองรับบริการใหม่หลายรายการ เช่น ElevationService และ Distance Matrix
  • บริการเส้นทางที่ปรับปรุงใหม่จะแสดงเส้นทางทางเลือก การเพิ่มประสิทธิภาพเส้นทาง (วิธีแก้ปัญหาโดยประมาณของ ปัญหาเกี่ยวกับการเดินทางของพนักงานขาย) เส้นทางจักรยาน (ที่มี เลเยอร์จักรยาน) เส้นทางขนส่งสาธารณะ และ เส้นทางที่ลากได้
  • รูปแบบการเข้ารหัสพิกัดภูมิศาสตร์ที่อัปเดตซึ่งมีข้อมูลประเภทที่แม่นยำมากกว่าค่า accuracy จาก Geoที่อยู่ในรายการ API v2
  • การรองรับหน้าต่างข้อมูลหลายรายการในแผนที่เดียว

การอัปเกรดแอปพลิเคชันของคุณ

คีย์ใหม่ของคุณ

Maps JavaScript API v3 ใช้ระบบคีย์ใหม่จาก v2 คุณอาจใช้คีย์ v3 กับแอปพลิเคชันอยู่แล้ว ซึ่งในกรณีนี้ไม่จำเป็นต้องเปลี่ยนแปลง ตรวจสอบ URL ที่คุณโหลด Maps JavaScript API สำหรับพารามิเตอร์ key เพื่อยืนยัน หากค่าคีย์ขึ้นต้นด้วย "ABQIAA" แสดงว่าคุณกำลังใช้คีย์ v2 หากมีคีย์ v2 คุณต้องอัปเกรดเป็นคีย์ v3 ด้วยการย้ายข้อมูล ซึ่งจะมีคุณสมบัติดังนี้

ระบบจะส่งคีย์เมื่อโหลด Maps JavaScript API v3 ดูข้อมูลเพิ่มเติมเกี่ยวกับการสร้างคีย์ API

โปรดทราบว่าหากคุณเป็นลูกค้า Google Maps API for Work คุณอาจใช้รหัสไคลเอ็นต์ที่มีพารามิเตอร์ client แทนการใช้พารามิเตอร์ key ได้ Maps JavaScript API v3 ยังคงรองรับรหัสไคลเอ็นต์และไม่จำเป็นต้องผ่านกระบวนการอัปเกรดคีย์

การโหลด API

การแก้ไขโค้ดครั้งแรกที่คุณจะต้องทำกับโค้ดเกี่ยวข้องกับวิธีโหลด API ในเวอร์ชัน 2 คุณโหลด Maps JavaScript API ผ่านคำขอที่ส่งไปยัง http://maps.google.com/maps หากโหลด Maps JavaScript API v3 คุณจะต้องทำการเปลี่ยนแปลงต่อไปนี้

  1. โหลด API จาก //maps.googleapis.com/maps/api/js
  2. นำพารามิเตอร์ file ออก
  3. อัปเดตพารามิเตอร์ key ด้วยคีย์ v3 ใหม่ ลูกค้า Google Maps API for Work ควรใช้พารามิเตอร์ client
  4. (แพ็กเกจพรีเมียมของ Google Maps Platform เท่านั้น) ตรวจสอบว่าระบุพารามิเตอร์ client ตามที่อธิบายไว้ใน คู่มือนักพัฒนาซอฟต์แวร์แพ็กเกจพรีเมียมของ Google Maps Platform
  5. นําพารามิเตอร์ v ออกเพื่อขอเวอร์ชันที่เผยแพร่ล่าสุด หรือเปลี่ยนค่าตามรูปแบบการกำหนดเวอร์ชัน v3
  6. (ไม่บังคับ) แทนที่พารามิเตอร์ hl ด้วย language และเก็บค่าไว้
  7. (ไม่บังคับ) เพิ่มพารามิเตอร์ libraries เพื่อโหลดไลบรารีที่ไม่บังคับ

ในกรณีที่เรียบง่ายที่สุด v3 Bootstrap จะระบุเฉพาะพารามิเตอร์คีย์ API ของคุณเท่านั้น:

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>

ตัวอย่างด้านล่างขอ Maps JavaScript API v2 เวอร์ชันล่าสุดในภาษาเยอรมัน

<script src="//maps.google.com/maps?file=api&v=2.x&key=YOUR_API_KEY&hl=de"></script>

ตัวอย่างด้านล่างเป็นคำขอที่เทียบเท่าสำหรับเวอร์ชัน 3

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&language=de"></script>

ขอแนะนำเนมสเปซของ google.maps

การเปลี่ยนแปลงที่เห็นได้ชัดที่สุดใน Maps JavaScript API v3 คือการเปิดตัวเนมสเปซ google.maps API v2 จะวางออบเจ็กต์ทั้งหมดในเนมสเปซทั่วโลกโดยค่าเริ่มต้น ซึ่งอาจทำให้เกิดความขัดแย้งในการตั้งชื่อ ภายใน v3 ออบเจ็กต์ทั้งหมดจะอยู่ในเนมสเปซ google.maps

เมื่อย้ายข้อมูลแอปพลิเคชันไปยัง v3 คุณจะต้องเปลี่ยนโค้ดเพื่อใช้ประโยชน์จากเนมสเปซใหม่ ขออภัย การค้นหา "G" และแทนที่ด้วย "google.maps" อาจทำงานได้ไม่สมบูรณ์ แต่ก็เป็นไปตามกฎทั่วไปที่ควรใช้เมื่อตรวจสอบโค้ด ด้านล่างนี้คือตัวอย่างบางส่วนของคลาสที่เทียบเท่าในเวอร์ชัน 2 และ v3

v2 v3
GMap2 google.maps.Map
GLatLng google.maps.LatLng
GInfoWindow google.maps.InfoWindow
GMapOptions google.map.MapOptions
G_API_VERSION google.maps.version
GPolyStyleOptions google.maps.PolygonOptions
or google.maps.PolylineOptions

การนำโค้ดที่ล้าสมัยออก

Maps JavaScript API v3 ทำงานเหมือนกับฟังก์ชันส่วนใหญ่ในเวอร์ชัน 2 อย่างไรก็ตาม มีบางคลาสที่ไม่รองรับอีกต่อไป ในการย้ายข้อมูล คุณควรแทนที่คลาสเหล่านี้ด้วยไลบรารียูทิลิตีของบุคคลที่สามหรือนำการอ้างอิงเหล่านี้ออกจากโค้ดของคุณ มีไลบรารี JavaScript ที่ยอดเยี่ยมจำนวนมากที่มีฟังก์ชันการทำงานคล้ายกัน เช่น Closure หรือ jQuery

คลาสต่อไปนี้ไม่มี Maps JavaScript API v3 พร้อมกัน

GBoundsGLanguage
GBrowserIsCompatibleGLayer
GControlGLog
GControlAnchorGMercatorProjection
GControlImplGNavLabelControl
GControlPositionGObliqueMercator
GCopyrightGOverlay
GCopyrightCollectionGPhotoSpec
GDownloadUrlGPolyEditingOptions
GDraggableObjectGScreenOverlay
GDraggableObjectOptionsGStreetviewFeatures
GFactualGeocodeCacheGStreetviewLocation
GGeoAddressAccuracyGStreetviewOverlay
GGeocodeCacheGStreetviewUserPhotosOptions
GGoogleBarGTileLayerOptions
GGoogleBarAdsOptionsGTileLayerOverlayOptions
GGoogleBarLinkTargetGTrafficOverlayOptions
GGoogleBarListingTypesGUnload
GGoogleBarOptionsGXml
GGoogleBarResultListGXmlHttp
GInfoWindowTabGXslt
GKeyboardHandler

การเปรียบเทียบโค้ด

มาเปรียบเทียบแอปพลิเคชัน 2 รายการง่ายๆ ที่เขียนด้วย API v2 และ v3

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    
<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>

คุณจะเห็นว่าทั้ง 2 แอปพลิเคชันมีความแตกต่างกันอยู่มาก การเปลี่ยนแปลงสำคัญมีดังนี้

  • มีการเปลี่ยนแปลงที่อยู่ที่ใช้โหลด API
  • ไม่จำเป็นต้องใช้เมธอด GBrowserIsCompatible() และ GUnload() ใน v3 อีกต่อไป และเรานำเมธอดออกจาก API แล้ว
  • ระบบจะแทนที่ออบเจ็กต์ GMap2 ด้วย google.maps.Map เป็นออบเจ็กต์กลางใน API
  • ขณะนี้คุณสมบัติจะโหลดผ่านคลาสตัวเลือก ในตัวอย่างข้างต้น เราตั้งค่าพร็อพเพอร์ตี้ 3 รายการที่จำเป็นต่อการโหลดแผนที่ ได้แก่ center, zoom และ mapTypeId ผ่านออบเจ็กต์ MapOptions ในบรรทัด
  • UI เริ่มต้นจะเปิดอยู่โดยค่าเริ่มต้นใน v3 คุณปิดใช้ฟีเจอร์นี้ได้โดยตั้งค่าพร็อพเพอร์ตี้ disableDefaultUI เป็น "จริง" ในออบเจ็กต์ MapOptions

สรุป

ถึงตอนนี้ คุณจะได้ทราบถึงประเด็นสำคัญๆ ที่เกี่ยวข้องกับการย้ายข้อมูลจาก Maps JavaScript API เวอร์ชัน 2 เป็นเวอร์ชัน 3 กันไปแล้ว ยังมีข้อมูลเพิ่มเติมที่คุณอาจจำเป็นต้องทราบอีก แต่จะขึ้นอยู่กับใบสมัครของคุณ ในส่วนต่อไปนี้ เราได้รวมวิธีการย้ายข้อมูลสำหรับกรณีเฉพาะที่คุณอาจพบ นอกจากนี้ ยังมีแหล่งข้อมูลอื่นๆ อีกหลายรายการที่อาจเป็นประโยชน์ในระหว่างกระบวนการอัปเกรด

หากมีปัญหาหรือข้อสงสัยเกี่ยวกับบทความนี้ โปรดใช้ลิงก์ส่งความคิดเห็นที่ด้านบนของหน้านี้

ข้อมูลอ้างอิงโดยละเอียด

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

  • เหตุการณ์ - การลงทะเบียนและการจัดการเหตุการณ์
  • การควบคุม - การควบคุมตัวควบคุมทิศทางที่ปรากฏในแผนที่
  • การวางซ้อน - การเพิ่มและการแก้ไขวัตถุใน แผนที่
  • ประเภทแผนที่ - ชิ้นส่วนแผนที่ฐาน
  • เลเยอร์ - การเพิ่มและแก้ไขเนื้อหาเป็นกลุ่ม เช่น เลเยอร์ KML หรือเลเยอร์การจราจร
  • บริการ - การทำงานร่วมกับบริการพิกัดภูมิศาสตร์ เส้นทาง หรือบริการ Street View ของ Google

กิจกรรม

โมเดลเหตุการณ์สำหรับ Maps JavaScript API v3 นั้นคล้ายกับที่ใช้ใน v2 แม้ว่าจะมีการเปลี่ยนแปลงไปอย่างมาก

การควบคุม

Maps JavaScript API แสดงตัวควบคุม UI ที่ช่วยให้ผู้ใช้โต้ตอบกับแผนที่ได้ คุณใช้ API เพื่อปรับแต่งวิธีที่การควบคุมเหล่านี้จะปรากฏได้

การวางซ้อน

การวางซ้อนจะแสดงวัตถุที่คุณ "เพิ่ม" ลงในแผนที่เพื่อกำหนดจุด เส้น พื้นที่ หรือคอลเล็กชันของวัตถุ

ประเภทแผนที่

ประเภทของแผนที่ที่มีอยู่ใน v2 และ v3 จะแตกต่างกันเล็กน้อย แต่ประเภทแผนที่พื้นฐานทั้งหมดพร้อมใช้งานใน API ทั้งสองเวอร์ชัน โดยค่าเริ่มต้น v2 จะใช้ชิ้นส่วนแผนที่โรดแมปแบบมาตรฐาน อย่างไรก็ตาม v3 กำหนดให้ต้องระบุประเภทแผนที่ที่เจาะจงเมื่อสร้างออบเจ็กต์ google.maps.Map

เลเยอร์

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

บริการ