Google 地图基础微件
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
上下文 widget 是一种 Google 地图 Pre-GA 产品,是一个用于支持或补充其他 Google 地图内容的视觉容器。借助 Google 地图情境微件,您可以将 Google 地图接地集成到应用中,打造由 LLM 赋能的对话式聊天体验。上下文 widget 使用上下文令牌 googleMapsWidgetContextToken
进行渲染,该令牌在 Vertex AI API 响应中返回,可用于渲染视觉内容。
情境化 widget 可根据您的使用场景提供不同的功能:
- 在 Google 地图提示用于生成答案的场景中,它会显示主观的用户生成内容 (UGC)。
- 当 Vertex AI 仅生成文本回答时,此插件有助于通过地图可视化效果和数据来丰富结果。
内容相关 widget 的运作方式
上下文 widget 会以 googleMapsWidgetContextToken
的形式显示 Vertex AI 依托 Google 地图进行接地的回答。使用此令牌可呈现上下文相关微件并显示响应。
了解详情。事件流如下所示:
- 使用依托 Google 地图接地的查询调用 Vertex AI API。
- Vertex AI 会返回
googleMapsWidgetContextToken
。
- 使用令牌呈现上下文相关微件。
- 上下文 widget 会显示 Vertex AI 的回答。
以下示例展示了从 Vertex AI API 返回的上下文令牌的格式。
"googleMapsWidgetContextToken": "widgetcontent/AcBXPQdpWQWbap9H-OH8sEKmOXxmEKAYvff0tvthhneMQC3VrqWCjpnPBl4-Id98FGiA_S_t8aeAeJj0T6JkWFX56Bil8oBSR0W8JH3C_RSYLbTjxKdpxc9yNn6JcZTtolIRZon9xi6WpNGuSyjcIxWu2S0hwpasNOpUlWrG1RxVCB4WD1fsz_pwR236mG36lMxevXTQ_JnfdYNuQwQ4Lc3vn...<snip>...
Ts5VJE_b3IC5eE_6wez0nh61r7foTUZpP7BXMwxR-7Wyfcj6x1v6mIWsFGr1o0p_HSAMNqWPg-aFVnkPLhAkOR6MaNZOfezTva-gxHlu7z_haFvYxcUE1qfNVQ",
渲染 Google 地图上下文 widget
如需呈现和使用 Google 地图上下文 widget,请在显示该 widget 的网页上使用 Maps JavaScript API 的 Alpha 版。如需了解详情,请参阅加载 Maps JavaScript API。
您还必须使用已启用以加载 Google Maps JavaScript API 的 API 密钥。
验证 places
库是否已加载。
以下部分介绍了如何呈现 Google 地图情境化 widget。使用自定义 HTML 或 JavaScript 创建情境 widget。
使用自定义 HTML 元素
以下部分介绍了如何使用自定义 HTML 元素呈现 Google 地图情境 widget。通过将 gmp-place-contextual
元素添加到网页中来创建情境化 widget。
-
将 gmp-place-contextual
元素添加到网页中:
<gmp-place-contextual id="widget"></gmp-place-contextual>
-
在任何以 Google 地图为依据的回答中,都有一个相应的 googleMapsWidgetContextToken
,可用于呈现情境化 widget。
以下函数展示了如何更新上下文令牌:
let widget = document.querySelector('#widget'); // a div that contains the widget
widget.contextToken = contextToken;
-
可选:指定列表布局。有效值包括:
- 紧凑布局:
<gmp-place-contextual-list-config layout="compact">
- 纵向布局:
<gmp-place-contextual-list-config layout="vertical">
以下示例展示了如何将列表布局更改为紧凑型:
<gmp-place-contextual id="widget">
<gmp-place-contextual-list-config layout="compact">
</gmp-place-contextual-list-config>
</gmp-place-contextual>
-
可选:更改地图模式。有效值包括:
- 2D 路线图地图:
<gmp-place-contextual-map-config map-mode="roadmap">
- 3D 混合地图:
<gmp-place-contextual-map-config map-mode="hybrid">
- 无地图:
<gmp-place-contextual-map-config map-mode="none">
以下示例展示了如何将地图模式更改为 2D 地图:
<gmp-place-contextual id="widget">
<gmp-place-contextual-map-config map-mode="roadmap">
</gmp-place-contextual-map-config>
</gmp-place-contextual>
使用 JavaScript
以下部分介绍了如何通过以编程方式创建 PlaceContextualElement
并将其附加到 DOM 来呈现 Google 地图情境化 widget。
创建情境化 widget。
let widget = document.querySelector('#widget'); // a div that contains the widget
async function createWidget(contextToken) {
await google.maps.importLibrary('places');
const placeContextualElement = new
google.maps.places.PlaceContextualElement({ contextToken }); // contextToken can be empty at initialization.
widget.appendChild(placeContextualElement);
}
- 在任何以 Google 地图为依据的回答中,都有一个相应的
googleMapsWidgetContextToken
,用于呈现情境化 widget。以下函数展示了如何更新上下文令牌:
widget.contextToken = contextToken;
-
可选:指定列表布局。有效值包括:
- 紧凑布局:
google.maps.places.PlaceContextualListLayout.COMPACT
- 纵向布局:
google.maps.places.PlaceContextualListLayout.VERTICAL
以下示例展示了如何将列表布局更改为紧凑型:
const widgetConfig = new google.maps.places.PlaceContextualListConfigElement({
layout: google.maps.places.PlaceContextualListLayout.COMPACT
});
widget.appendChild(widgetConfig);
-
可选:更改地图模式。有效值包括:
- 2D 路线图地图:
google.maps.places.PlaceContextualListMapMode.ROADMAP
- 3D 混合地图:
google.maps.places.PlaceContextualListMapMode.HYBRID
- 无地图:
google.maps.places.PlaceContextualListMapMode.NONE
以下示例展示了如何将地图模式更改为 2D 地图:
const widgetConfig = new google.maps.places.PlaceContextualListConfigElement({
mapMode: google.maps.places.PlaceContextualListMapMode.ROADMAP
});
widget.appendChild(widgetConfig);
禁止投放广告的地区
为确保 Google 地图平台安全可靠,我们会限制某些内容和活动。如需查看禁止地区的列表,请参阅
Google Maps Platform 禁止地区。
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-10。
[null,null,["最后更新时间 (UTC):2025-08-10。"],[],[],null,["| This product or feature is Experimental (pre-GA). Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. Pre-GA Offerings are covered by the [Google\n| Maps Platform Service Specific Terms](https://cloud.google.com/maps-platform/terms/maps-service-terms). For more information, see the [launch stage descriptions](/maps/launch-stages).\n\nThe contextual widget is a Google Maps Pre-GA Offering that's a visual container used to\nsupport or supplement other Google Maps content. The Google Maps contextual widget lets you\nintegrate Grounding with Google Maps into your applications to create a conversational\nLLM-powered chat experience. The contextual widget is rendered using the context token,\n`googleMapsWidgetContextToken`, which is returned in the Vertex AI API\nresponse and can be used to render visual content.\n\nThe contextual widget serves different functions depending on your scenario:\n\n- It displays subjective user-generated content (UGC) in the scenario where Google Maps prompting is used for answer generation.\n- It helps to enrich results with map visualizations and data when Vertex AI generates just a text response.\n\nHow the contextual widget works\n\nThe contextual widget displays a response from Grounding with Google Maps in Vertex AI,\nin the\nform of a `googleMapsWidgetContextToken`. Use this token to render the contextual\nwidget, and display the response.\n[Learn more](https://cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-maps).\nThe event flow is as follows:\n\n1. Call the Vertex AI API with a query grounded with Google Maps.\n2. Vertex AI returns a `googleMapsWidgetContextToken`.\n3. Render the contextual widget using the token.\n4. The contextual widget displays the response from Vertex AI.\n\nThe following example shows how a context token looks when returned from the Vertex AI API. \n\n```javascript\n\"googleMapsWidgetContextToken\": \"widgetcontent/AcBXPQdpWQWbap9H-OH8sEKmOXxmEKAYvff0tvthhneMQC3VrqWCjpnPBl4-Id98FGiA_S_t8aeAeJj0T6JkWFX56Bil8oBSR0W8JH3C_RSYLbTjxKdpxc9yNn6JcZTtolIRZon9xi6WpNGuSyjcIxWu2S0hwpasNOpUlWrG1RxVCB4WD1fsz_pwR236mG36lMxevXTQ_JnfdYNuQwQ4Lc3vn...\u003csnip\u003e...\nTs5VJE_b3IC5eE_6wez0nh61r7foTUZpP7BXMwxR-7Wyfcj6x1v6mIWsFGr1o0p_HSAMNqWPg-aFVnkPLhAkOR6MaNZOfezTva-gxHlu7z_haFvYxcUE1qfNVQ\",\n```\n\nRender the Google Maps contextual widget\n\nTo render and use the Google Maps contextual widget, use the alpha version of the\nMaps JavaScript API on the page that displays the widget. For more information,\nsee [Load the Maps JavaScript API](/maps/documentation/javascript/load-maps-js-api).\nYou must also use the API key that was enabled to load the Google Maps JavaScript API.\nVerify that the `places` library has been loaded.\n\nThe following section describes how to render the Google Maps contextual widget. Create a\ncontextual widget by using custom HTML or with JavaScript.\n\nUse custom HTML elements\n\nThe following section describes how to render the Google Maps contextual widget using custom\nHTML elements. Create a contextual widget by adding the `gmp-place-contextual`\nelement to the page.\n\n1. Add the `gmp-place-contextual` element to the page:\n\n ```html\n \u003cgmp-place-contextual id=\"widget\"\u003e\u003c/gmp-place-contextual\u003e\n ```\n2.\n In any response that is grounded with Google Maps, there's a corresponding\n `googleMapsWidgetContextToken` that can be used to render the contextual widget.\n The following function shows how to update the context token:\n\n ```javascript\n let widget = document.querySelector('#widget'); // a div that contains the widget\n widget.contextToken = contextToken;\n ```\n3. Optional: Specify the list layout. Valid values include the following:\n - Compact layout: `\u003cgmp-place-contextual-list-config layout=\"compact\"\u003e`\n - Vertical layout: `\u003cgmp-place-contextual-list-config layout=\"vertical\"\u003e`\n\n The following example shows how to change the list layout to compact: \n\n ```html\n \u003cgmp-place-contextual id=\"widget\"\u003e\n \u003cgmp-place-contextual-list-config layout=\"compact\"\u003e\n \u003c/gmp-place-contextual-list-config\u003e\n \u003c/gmp-place-contextual\u003e\n ```\n4. Optional: Change the map mode. Valid values include the following:\n - 2D roadmap map: `\u003cgmp-place-contextual-map-config map-mode=\"roadmap\"\u003e`\n - 3D hybrid map: `\u003cgmp-place-contextual-map-config map-mode=\"hybrid\"\u003e`\n - No map: `\u003cgmp-place-contextual-map-config map-mode=\"none\"\u003e`\nThe following example shows how to change the map mode to a 2D map: \n\n```html\n\u003cgmp-place-contextual id=\"widget\"\u003e\n \u003cgmp-place-contextual-map-config map-mode=\"roadmap\"\u003e\n \u003c/gmp-place-contextual-map-config\u003e\n\u003c/gmp-place-contextual\u003e\n```\n\nUse JavaScript\n\nThe following section describes how to render the Google Maps contextual widget by\nprogrammatically creating a `PlaceContextualElement` and appending it to the DOM.\n\n1. Create a contextual widget.\n\n ```javascript\n let widget = document.querySelector('#widget'); // a div that contains the widget\n\n async function createWidget(contextToken) {\n await google.maps.importLibrary('places');\n const placeContextualElement = new\n google.maps.places.PlaceContextualElement({ contextToken }); // contextToken can be empty at initialization.\n widget.appendChild(placeContextualElement);\n }\n ```\n2. In any response that's grounded with Google Maps, there's a corresponding `googleMapsWidgetContextToken` that's used to render the contextual widget. The following function shows how to update the context token: \n\n ```javascript\n widget.contextToken = contextToken;\n ```\n3. Optional: Specify the list layout. Valid values include the following:\n - Compact layout: `google.maps.places.PlaceContextualListLayout.COMPACT`\n - Vertical layout: `google.maps.places.PlaceContextualListLayout.VERTICAL`\n4. The following example shows how to change the list layout to compact: \n\n```javascript\nconst widgetConfig = new google.maps.places.PlaceContextualListConfigElement({\n layout: google.maps.places.PlaceContextualListLayout.COMPACT\n});\nwidget.appendChild(widgetConfig);\n```\n5. Optional: Change the map mode. Valid values include the following:\n - 2D roadmap map: `google.maps.places.PlaceContextualListMapMode.ROADMAP`\n - 3D hybrid map: `google.maps.places.PlaceContextualListMapMode.HYBRID`\n - No map: `google.maps.places.PlaceContextualListMapMode.NONE`\n6. The following example shows how to change the map mode to a 2D map: \n\n```javascript\nconst widgetConfig = new google.maps.places.PlaceContextualListConfigElement({\n mapMode: google.maps.places.PlaceContextualListMapMode.ROADMAP\n});\nwidget.appendChild(widgetConfig);\n```\n\nProhibited territories Google Maps restricts certain content and activities to maintain a safe and reliable platform. For a list of prohibited territories, see [Google Maps\nPlatform Prohibited Territories](https://cloud.google.com/maps-platform/terms/maps-prohibited-territories)."]]