Obsługa wersji

Zespół Maps JavaScript API regularnie aktualizuje interfejs API, wprowadzając nowe funkcje, poprawki błędów i ulepszenia wydajności. Na tej stronie opisaliśmy wersje interfejsu API, które możesz używać w swoich aplikacjach.

Kanały wersji i numery wersji

W aplikacji możesz określić kanały wersji lub numery wersji:

  • Kanał tygodniowy jest określany za pomocą parametru v=weekly.
    Ten kanał jest aktualizowany raz w tygodniu i zawiera najnowsze dane.
  • Kanał kwartalny jest określany za pomocą parametru v=quarterly.
    Ten kanał jest aktualizowany raz na kwartał i jest najbardziej przewidywalny.
  • Kanał beta jest określony za pomocą v=beta.
    Ten kanał jest oparty na kanale weekly i jest aktualizowany raz w tygodniu. Zawiera ono dodatkowe zmiany na potrzeby wczesnego testowania i opinii.
  • Kanał alfa jest określany za pomocą v=alpha.
    Ten kanał jest oparty na kanale beta i jest aktualizowany raz w tygodniu. Obejmuje on eksperymenty dotyczące opinii klientów na temat prototypów. Służy ona tylko do celów programistycznych i nie powinna być używana w wersji produkcyjnej.
  • Numer wersji jest określony za pomocą v=n.nn.
    Możesz wybrać v=3.59, v=3.58, v=3.57 lub v=3.56.
    Numery wersji są aktualizowane raz na kwartał (patrz Comiesięczne aktualizacje).

Jeśli nie określisz kanału ani wersji, domyślnie otrzymasz kanał tygodniowy. Jeśli migrujesz z planu premium i nie określisz wyraźnie kanału ani wersji, domyślnie otrzymasz kanał kwartalny. Jeśli podasz nieprawidłową wersję, otrzymasz kanał domyślny.

Wybór kanału tygodniowego

W przypadku większości aplikacji zalecamy korzystanie z kanału tygodniowego. To najnowsza wersja, która zawiera najnowsze poprawki błędów i ulepszenia wydajności. Kanał tygodniowy możesz określić, wczytując interfejs Maps JavaScript API za pomocą tego tagu skryptu:

  <script>
    (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
      key: "YOUR_API_KEY",
      v: "weekly",
    });
  </script>

Obecnie kanał tygodniowy ma wersję 3.59. Ta wersja jest aktualizowana co tydzień o nowe funkcje, poprawki błędów i ulepszenia działania.

W połowie lutego kanał tygodniowy zostanie zaktualizowany do wersji 3.60. W tym czasie nowa wersja może usunąć przestarzałe funkcje lub wprowadzić niekompatybilność wsteczną.

Wybieranie kanału kwartalnego

Niektóre aplikacje mogą korzystać z mniejszej liczby większych aktualizacji, ponieważ zapewnia to większą przewidywalność. W przypadku tych aplikacji należy korzystać z kanału kwartalnego. Stosuj to podejście, jeśli chcesz, aby poprawki błędów i ulepszenia wydajności były dostępne w oczekiwanym terminie (patrz comiesięczne aktualizacje). Kwartalny kanał możesz określić, wczytując interfejs Maps JavaScript API za pomocą tego tagu skryptu:

  <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "quarterly",
  });
  </script>

Obecnie kanał kwartalny ma wersję 3.58. W tym kwartale ta wersja nie będzie otrzymywać nowych funkcji, poprawek błędów ani ulepszeń działania. Co jakiś czas możemy wprowadzać w tej wersji poprawki błędów związanych z zabezpieczeniami.

W połowie lutego kanał kwartalny zostanie zaktualizowany do wersji 3.59. Wtedy nowa wersja będzie zawierać nowe funkcje, usuwać wycofane funkcje lub wprowadzać niezgodności wstecz od poprzednich 3 miesięcy.

Wybieranie wersji beta

Korzystaj z kanału wersji beta, aby wypróbować nowe funkcje i zmiany w wersji beta. Funkcje w wersji beta są w pełni funkcjonalne, ale mogą mieć jeszcze pewne problemy (użyj śledzika problemów, aby zgłosić problemy i przekazać opinię). Kanały beta nie są objęte gwarancją jakości usług ani żadnymi zasadami wycofywania, a niektóre zmiany mogą nie być zgodne ze starszymi wersjami.

Ten kanał jest oparty na kanale weekly i jest aktualizowany raz w tygodniu.

Kanał beta możesz określić, wczytując interfejs Maps JavaScript API za pomocą tego tagu skryptu:

  <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "beta",
  });
  </script>

Wybieranie kanału alfa

Korzystając z kanału alfa, możesz wypróbować nowe eksperymentalne funkcje i zmiany. Aby zgłaszać problemy i przesyłać opinie, użyj śledzika problemów. Kanału alfa nie obejmuje żadna gwarancja jakości usług ani żadna zasada wycofywania, a niektóre zmiany mogą nie być zgodne wstecznie z wcześniejszymi wersjami. Służy ona tylko do celów programistycznych i nie powinna być używana w wersji produkcyjnej.

Ten kanał jest oparty na kanale beta i jest aktualizowany raz w tygodniu.

Kanał alfa możesz określić, wczytując interfejs Maps JavaScript API za pomocą tego tagu skryptu:

  <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "alpha",
  });
  </script>

Wybieranie numeru wersji

Określ wersję za pomocą numeru tylko wtedy, gdy regularnie testujesz i aktualizujesz aplikację. Dzieje się tak, ponieważ wersje numerowane są ostatecznie usuwane, gdy co kwartał tworzone są nowe wersje. Numer wersji możesz określić, wczytując interfejs Maps JavaScript API za pomocą tego tagu skryptu:

  <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: 3.58,
  });
  </script>

Obecnie możesz określić v=3.59, v=3.58, v=3.57 lub v=3.56.

  • Wersja 3.59 jest aktualizowana co tydzień o nowe funkcje, poprawki błędów i ulepszenia wydajności.
  • Wersja 3.58 nie otrzymuje cotygodniowych aktualizacji.
  • Wersja 3.57 nie otrzymuje cotygodniowych aktualizacji.
  • Wersja 3.56 nie otrzymuje cotygodniowych aktualizacji.
  • Możemy co jakiś czas wprowadzać poprawki błędów związanych z bezpieczeństwem do dowolnej wersji.
  • Podczas tworzenia nowej wersji możemy wprowadzić zmiany, które nie będą zgodne z poprzednimi wersjami.

Po połowie lutego będzie można określić wartości v=3.60, v=3.59, v=3.58 lub v=3.57.

  • Wersja 3.60 będzie co tydzień otrzymywać aktualizacje z nowymi funkcjami, poprawkami błędów i ulepszeniami wydajności.
  • Wersja 3.59 nie będzie już otrzymywać cotygodniowych aktualizacji.
  • Wersja 3.58 nie będzie już otrzymywać cotygodniowych aktualizacji.
  • Wersja 3.57 nie będzie już otrzymywać cotygodniowych aktualizacji.
  • Możemy co jakiś czas wprowadzać poprawki błędów związanych z zabezpieczeniami do dowolnej wersji.
  • Wersja 3.56 nie będzie już dostępna. Wszelkie próby załadowania tej wersji zostaną zignorowane, a zamiast niej wyświetli się kanał domyślny.

Na diagramie poniżej widać, które wersje będą dostępne w poszczególnych kanałach w przyszłym roku.

v=weekly v=quarterly v=3.nn v=3.nn-1 Nov 2024 Feb 2025 May 2025 Aug 2025 v3.56 v3.57 v3.57 v3.58 v3.58 v3.58 v3.59 v3.59 v3.59 v3.59 v3.60 v3.60 v3.60 v3.61 v3.61 v3.62

Aktualizacja wpłynęła na moją aplikację

Gdy zaktualizujemy kanały wersji, może to wpłynąć na Twoją aplikację. Może to być spowodowane tym, że aplikacja korzysta z nieudokumentowanych lub wycofanych funkcji albo z powodu błędu lub wprowadzonej przez nas poprawki.

Jako tymczasowe rozwiązanie możesz skonfigurować aplikację tak, aby używała starszej wersji.

  1. Otwórz konsolę w narzędziach dla programistów w przeglądarce i sprawdź wartość zmiennej google.maps.version.
  2. Zaktualizuj tag skryptu, który wczytuje interfejs API, i wyślij żądanie z numerem starszej wersji.
    Jeśli na przykład google.maps.version to „3.59.2”, w tagu skryptu użyj wartości v=3.58.
    To tymczasowe obejście będzie działać tylko przez ograniczony czas.

Gdy wprowadzimy tymczasowe obejście, będziesz mieć czas (zazwyczaj 3–6 miesięcy) na zaktualizowanie aplikacji, aby nie używała już funkcji bez dokumentacji lub wycofanych funkcji, a także na naprawienie błędów.

Następnie wróć do pierwotnego tagu skryptu, aby załadować interfejs API.

Możesz też utworzyć zgłoszenie lub zgłosić problem.

Kwartalne e-maile z aktualnościami

Raz na kwartał zespół Maps JavaScript API udostępnia nową wersję. Dotyczy to połowy lutego, maja, sierpnia i listopada. Następna aktualizacja zostanie opublikowana w połowie lutego. Nowy kanał tygodniowy będzie zawierać wersję 3.60, a w tym samym czasie inne kanały zostaną zaktualizowane.

Cotygodniowe informacje o kanale

Kanał tygodniowy wskazuje obecnie wersję 3.59.

W połowie lutego kanał tygodniowy zostanie zaktualizowany z wersji 3.59 na wersję 3.60. Nowa wersja będzie zawierać nowe funkcje, usuwać wycofane funkcje lub wprowadzać niekompatybilność wsteczną. Po zaktualizowaniu kanału może być konieczne przetestowanie tych zmian.

W ciągu kwartału nowa wersja będzie co tydzień aktualizowana o nowe funkcje, poprawki błędów i ulepszenia wydajności. Nie spowoduje usunięcia wycofanych funkcji ani nie wprowadzi niezgodności wstecznej.

Kwartalny raport o kanale

Czwartek kanału wskazuje obecnie wersję 3.58.

W połowie lutego kwartalny kanał zostanie zaktualizowany z wersji 3.58 do wersji 3.59. Po aktualizacji ta wersja będzie zawierać nowe funkcje, usuwać wycofane funkcje lub wprowadzać niekompatybilność wsteczną z uwzględnieniem zmian wprowadzonych w ciągu ostatnich 3 miesięcy. Po zaktualizowaniu kanału może być konieczne przetestowanie tych zmian.

W tym kwartale ta wersja nie będzie zawierać nowych funkcji, poprawek błędów ani ulepszeń wydajności. Nie spowoduje usunięcia wycofanych funkcji ani nie wprowadzi niezgodności wstecznej.

Aktualizacje wersji

W połowie lutego numery wersji zostaną przerolowane, aby uwzględnić wydanie nowej wersji.

Wersja 3.60

W połowie lutego udostępnimy nową wersję 3.60. Po wydaniu ta wersja będzie zawierać nowe funkcje, usuwać wycofane funkcje lub wprowadzać niezgodności wstecz w stosunku do wersji 3.59. Aplikację należy przetestować po zmianie numeru wersji.

W trakcie kwartału nowa wersja będzie co tydzień aktualizowana o nowe funkcje, poprawki błędów i ulepszenia wydajności. Nie spowoduje usunięcia wycofanych funkcji ani nie wprowadzi niezgodności wstecznej.

Wersja 3.59

Ta wersja zawiera nowe funkcje, usuwa wycofane funkcje lub wprowadza niezgodności wsteczne w porównaniu z wersją 3.58. Aplikację należy przetestować po zmianie numeru wersji.

Po połowie lutego ta wersja nie będzie już aktualizowana o nowe funkcje, poprawki błędów ani ulepszenia działania. Nie spowoduje usunięcia wycofanych funkcji ani nie wprowadzi niezgodności wstecznej.

Wersja 3.58

Ta wersja zawiera nowe funkcje, usuwa wycofane funkcje lub wprowadza niezgodności wsteczne w stosunku do wersji 3.57. Aplikację należy przetestować po zmianie numeru wersji.

Ta wersja nie będzie już aktualizowana o nowe funkcje, poprawki błędów ani ulepszenia. Nie usunie funkcji wycofanych po tej wersji i nie wprowadzi nowych niezgodności wstecznej.

Wersja 3.57

Ta wersja zawiera nowe funkcje, usuwa wycofane funkcje lub wprowadza niezgodności wsteczne w porównaniu z wersją 3.56. Aplikację należy przetestować po zmianie numeru wersji.

Ta wersja nie będzie już aktualizowana o nowe funkcje, poprawki błędów ani ulepszenia. Nie usunie funkcji wycofanych po tej wersji i nie wprowadzi nowych niezgodności wstecznej.

Wersja 3.56

Po połowie lutego ta wersja zostanie usunięta i nie będzie można jej już używać. Każda próba załadowania tej wersji zostanie zignorowana, a zamiast niej wyświetli się kanał domyślny.

Obsługa wersji

W każdym kwartale dostępne są 4 wersje. Obsługiwane są wszystkie 4 te wersje.

Sprawdzanie wersji

Aby debugować, użyj właściwości google.maps.version, aby uzyskać w aplikacji bieżącą wersję interfejsu Maps JavaScript API. Poniższy przykładowy kod zapisuje wersję interfejsu API w konsoli przeglądarki. (więcej informacji o konsoli przeglądarki znajdziesz w  przewodniku po sprawdzaniu błędów w przeglądarce).

<!DOCTYPE html>
<html>
  <head>
    <title>Display Google Maps API Version</title>
  </head>
  <body>
    <script>
      function initMap() {
        // Add your map here.
        console.log('Google Maps API version: ' + google.maps.version);
      }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
    defer></script>
  </body>
</html>

Dokumentacja wersji interfejsu API

Przewodnik dla deweloperów zawsze opisuje tygodniową wersję.

Oprócz tego dla każdej wersji istnieje oddzielna referencja: