情境小工具是 Google 地圖正式發布前產品，屬於視覺容器，用於支援或補充其他 Google 地圖內容。Google 地圖情境小工具可讓您將 Grounding with Google 地圖整合至應用程式，打造以對話式大型語言模型為基礎的即時通訊體驗。情境小工具是使用情境符記 googleMapsWidgetContextToken 轉譯，該符記會顯示在 Vertex AI API 回應中，可用於轉譯視覺內容。
情境小工具會根據不同情境提供不同功能：
在 Google 地圖提示用於生成答案的情況下，這項功能會顯示主觀的使用者原創內容 (UGC)。
當 Vertex AI 只生成文字回覆時，這項功能有助於以地圖視覺化效果和資料豐富結果。
內容相關小工具的運作方式
情境小工具會以 googleMapsWidgetContextToken 形式，顯示 Vertex AI「利用 Google 地圖建立基準」功能的回覆。使用這個權杖算繪情境小工具，並顯示回覆。
瞭解詳情。事件流程如下：
如要算繪及使用 Google 地圖情境小工具，請在顯示小工具的頁面上使用 Alpha 版的 Maps JavaScript API。詳情請參閱「載入 Maps JavaScript API」。您也必須使用已啟用來載入 Google Maps JavaScript API 的 API 金鑰。確認 places 程式庫已載入。
下一節說明如何算繪 Google 地圖情境小工具。使用自訂 HTML 或 JavaScript 建立內容相關小工具。
使用自訂 HTML 元素
下一節說明如何使用自訂 HTML 元素，算繪 Google 地圖情境小工具。在網頁中加入 gmp-place-contextual 元素，即可建立內容相關小工具。
下一節說明如何以程式輔助方式建立 PlaceContextualElement，並將其附加至 DOM，進而算繪 Google 地圖情境小工具。
建立情境小工具。
letwidget=document.querySelector('#widget');// a div that contains the widgetasyncfunctioncreateWidget(contextToken){awaitgoogle.maps.importLibrary('places');constplaceContextualElement=newgoogle.maps.places.PlaceContextualElement({contextToken});// contextToken can be empty at initialization.widget.appendChild(placeContextualElement);}
在任何以 Google 地圖為基礎的回覆中，都會有對應的 googleMapsWidgetContextToken，用於算繪情境小工具。下列函式說明如何更新情境權杖：
[null,null,["上次更新時間：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)."]]
