- Google maps javascript libraries
- Как начать работу с Dynamic Library Import
- TypeScript
- JavaScript
- Обязательные параметры
- Необязательные параметры
- Как использовать пакет NPM js-api-loader
- TypeScript
- JavaScript
- Как использовать устаревший тег script для загрузки
- Как добавить тег script
- Параметры URL для загрузки с помощью устаревшего тега script
- Обязательные параметры (для устаревшего тега script)
- Необязательные параметры (для устаревшего тега script)
- Как перейти на Dynamic Library Import API
- Этапы переноса
- До
- После
- До
- После
- Open source libraries
- Web Components
- Extended Component Library
- Loading the API
- JS API loader
- React wrapper
- Using TypeScript
- TypeScript types
- TypeScript guards
- Extending markers and overlays
- Marker clusterer
- Marker manager
- Web map service (WMS)
- Marker labels
- Three.js overlays
- Deck.gl overlays
- Testing and linting
- ESLint plugin
- Jest mocks
- Node.js Libraries
- Node.js client library
- Polyline encoding
- URL signing
Google maps javascript libraries
В этом руководстве рассказывается, как загрузить Maps JavaScript API. Это можно сделать тремя способами:
Как начать работу с Dynamic Library Import
Загрузите Maps JavaScript API, добавив встроенный загрузчик в код приложения, как показано в следующем фрагменте кода:
Вы также можете добавить код встроенного загрузчика прямо в код JavaScript.
Чтобы загружать библиотеки во время выполнения, используйте оператор await для вызова метода importLibrary() внутри функции async , как показано в следующем примере кода:
TypeScript
JavaScript
Обязательные параметры
Необязательные параметры
- v – версия Maps JavaScript API, которую нужно загрузить.
- libraries – дополнительные библиотеки Maps JavaScript API, которые нужно загрузить (список, разделенный запятыми). В большинстве случаев не рекомендуется использовать фиксированный набор библиотек, но в этом случае разработчики могут точно настроить кеширование на сайте.
- language – язык, который нужно использовать. Определяет отображение элементов интерфейса и управления картой, уведомлений об авторских правах, маршрутов и ответов на запросы к сервису. Вы можете ознакомиться со списком поддерживаемых языков.
- region – код региона. От него зависит, как будет выглядеть карта той или иной страны или территории.
- solutionChannel – используется для отслеживания работы с образцами кода, которые мы публикуем, чтобы помочь разработчикам освоиться с API. Параметр запроса solutionChannel включается в вызовы API, выполняемые из образцов кода.
- authReferrerPolicy – ограничивает доступ к API по источнику ссылок HTTP, заданному пользователями Maps JS в Cloud Console (на страницах с какими URL будет срабатывать ключ API). Доступ можно ограничить только определенными адресами. Если вы хотите, чтобы ключ API могли использовать все страницы в домене или источнике, присвойте параметру значение authReferrerPolicy: «origin» . Это ограничит объем данных, пересылаемых при авторизации запросов от Maps JavaScript API. Если параметр определен и ограничения по источнику ссылок HTTP включены в Cloud Console, Maps JavaScript API сможет загружаться только на страницах домена (без уточнения пути), которым предоставлен доступ.
Как использовать пакет NPM js-api-loader
Пакет @googlemaps/js-api-loader доступен для загрузки с помощью менеджера пакетов NPM. Установите его, используя следующую команду:
npm install @googlemaps/js-api-loader
Пакет можно импортировать в приложение:
import < Loader >from "@googlemaps/js-api-loader"
Загрузчик предоставляет объект Promise и интерфейс обратного вызова. Ниже показано использование load() (метода Promise по умолчанию).
TypeScript
JavaScript
Как использовать устаревший тег script для загрузки
Устаревший тег script для загрузки все ещё поддерживается. Этот раздел содержит сведения для интеграций, в которых используется этот тег. Google рекомендует перейти на Dynamic Library Loading API.
Как добавить тег script
Чтобы загрузить Maps JavaScript API в HTML-файле, добавьте тег script , как показано ниже.
Параметры URL для загрузки с помощью устаревшего тега script
В этом разделе описаны все параметры, которые можно задать в строке запроса с URL для загрузки Maps JavaScript API. Обязательными являются лишь некоторые из параметров. Параметры разделяются амперсандами ( & ) в соответствии со стандартом написания URL.
В примере ниже приведен URL со всеми возможными параметрами и их условными значениями.
https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY &callback=FUNCTION_NAME &v=VERSION &libraries="LIBRARIES" &language="LANGUAGE" ®ion="REGION" &solution_channel="SOLUTION_IDENTIFIER" &auth_referrer_policy="AUTH_REFERRER_POLICY"
В следующем примере тег script загружает Maps JavaScript API по указанному в нём URL:
Обязательные параметры (для устаревшего тега script)
Перечисленные ниже параметры обязательны для загрузки Maps JavaScript API.
- key – ваш ключ API. Maps JavaScript API не будет загружаться, если не указать действительный ключ.
- callback – глобальная функция, которую нужно вызвать по окончании загрузки Maps JavaScript API.
Необязательные параметры (для устаревшего тега script)
С помощью перечисленных ниже параметров можно запрашивать конкретные версии Maps JavaScript API, загружать дополнительные библиотеки, выбирать региональные настройки карты и задавать ограничения по источнику ссылок HTTP.
- v – версия Maps JavaScript API, которую нужно использовать.
- libraries – дополнительные библиотеки Maps JavaScript API, которые нужно загрузить (список, разделенный запятыми).
- language – язык, который нужно использовать. Определяет отображение элементов интерфейса и управления картой, уведомлений об авторских правах, маршрутов и ответов на запросы к сервису. Список поддерживаемых языков приводится в разделе часто задаваемых вопросов.
- region – код региона. От него зависит, как будет выглядеть карта той или иной страны или территории.
- solution_channel – используется для отслеживания работы с образцами кода, которые мы публикуем, чтобы помочь разработчикам освоиться с API. Параметр запроса solution_channel включается в вызовы API, выполняемые из образцов кода. Примечание. Этот параметр можно использовать только с решениями Google. Подробнее читайте в разделе Параметр решений платформы Google Карт.
- auth_referrer_policy – ограничивает доступ к API по источнику ссылок HTTP, заданному пользователями Maps JS в Cloud Console (на страницах с какими URL будет срабатывать ключ API). Доступ можно ограничить только определенными адресами. Если вы хотите, чтобы ключ API могли использовать все страницы в домене или источнике, присвойте параметру значение auth_referrer_policy=origin . Это ограничит объем данных, пересылаемых при авторизации запросов от Maps JavaScript API. Такая возможность доступна в версиях 3.46 и выше. Если параметр определен и ограничения по источнику ссылок HTTP включены в Cloud Console, Maps JavaScript API сможет загружаться только на страницах домена (без уточнения пути), которым ограничен доступ.
Как перейти на Dynamic Library Import API
В этом разделе описаны действия, необходимые для переноса интеграции на Dynamic Library Import API.
Этапы переноса
Сначала замените устаревший тег script для загрузки на тег для встроенного загрузчика.
До
После
Затем измените код приложения:
- Сделайте функцию initMap() асинхронной.
- Вызовите метод importLibrary() , чтобы загрузить нужные библиотеки и обратиться к ним.
До
let map; function initMap() < map = new google.maps.Map(document.getElementById("map"), < center: < lat: -34.397, lng: 150.644 >, zoom: 8, >); > window.initMap = initMap;
После
let map; // initMap is now async async function initMap() < // Request libraries when needed, not in the script tag. const < Map >= await google.maps.importLibrary("maps"); // Short namespaces can be used. map = new Map(document.getElementById("map"), < center: < lat: -34.397, lng: 150.644 >, zoom: 8, >); > initMap();
Если не указано иное, контент на этой странице предоставляется по лицензии Creative Commons «С указанием авторства 4.0», а примеры кода – по лицензии Apache 2.0. Подробнее об этом написано в правилах сайта. Java – это зарегистрированный товарный знак корпорации Oracle и ее аффилированных лиц.
Последнее обновление: 2023-07-13 UTC.
Open source libraries
Many open source libraries are available to provide additional functionality for Maps JavaScript API. These libraries are versioned on GitHub and published to NPM.
Web Components
Use Maps JavaScript API Web Components to quickly add maps functionality to your websites. Web Components encapsulate boilerplate code, best practices, and responsive design, reducing complex map UIs into what is effectively a single HTML element.
Extended Component Library
Google Maps Platform Extended Component Library is a set of Web Components that helps developers build better maps faster, and with less effort.
npm i @googlemaps/extended-component-library
Loading the API
Modern web applications may benefit from using the following libraries to load the Maps JavaScript API.
JS API loader
Dynamically load the Maps JavaScript API with Promises.
npm i @googlemaps/js-api-loader
React wrapper
A wrapper component to declaratively load the Maps JavaScript API.
npm i @googlemaps/react-wrapper
Using TypeScript
TypeScript users can get started with the following packages. Check out the using TypeScript guide for additional information.
TypeScript types
TypeScript types for Maps JavaScript API
TypeScript guards
TypeScript guards to narrow union types.
npm i -D @googlemaps/typescript-guards
Extending markers and overlays
The following libraries extend classes such as Marker and OverlayView.
Marker clusterer
Creates and manages per-zoom-level clusters for large amounts of markers.
npm i @googlemaps/markerclusterer
Marker manager
Adds and removes markers based upon map viewport changes.
npm i @googlemaps/markermanager
Web map service (WMS)
Add Open Geospatial Consortium (OGC) layers such as a Web Map Service (WMS) to a map.
Marker labels
Add custom HTML labels to markers.
npm i @googlemaps/markerwithlabel
Three.js overlays
Use WebGL and ThreeJS for high performance visualizations.
Deck.gl overlays
Use Deck.gl as a custom Google Maps overlay.
Testing and linting
Use these libraries to ensure best practices and make testing easier for the Maps JavaScript API.
ESLint plugin
Use custom ESLint rules to lint your code.
npm i -D eslint-plugin-googlemaps
Jest mocks
Mocks to use with the Jest testing library.
npm i -D @googlemaps/jest-mocks
Node.js Libraries
Note: The following libraries do not work in browser environments and are implemented for Node.js and server environments.
Node.js client library
Node.js client library for making calls from cloud functions or serverside code.
npm i @googlemaps/google-maps-services-js
Polyline encoding
Encode and decode polylines in Node.js.
npm i @googlemaps/polyline-codec
URL signing
Sign URLs in Node.js for additional security.
npm i @googlemaps/url-signature
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2023-07-18 UTC.