开始使用

请按照以下步骤将 Local Context Library 添加到项目,并进行初始化,然后配置 Local Context 地图视图。

启用所需的 API 和 SDK

若要使用 Local Context Library,您必须启用 Maps JavaScript API 和 Places API。为此,请按照说明启用一个或多个 API 或 SDK。请注意,必须在 Google Cloud 控制台中针对同一项目启用这两个 API。

加载 Local Context Library

若要加载 Local Context Library,请像往常一样加载 Maps JavaScript API,并添加以下参数:

  • libraries=localContext:用于加载 Local Context Library。
  • v=beta:使用此版本所需的参数。
  • key:包含您的 API 密钥。
  • callback:用于执行 initMap() 函数。

以下示例展示了包含上述所有选项的脚本标记:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=localContext&v=beta&callback=initMap">
</script>

创建新的 Local Context 地图视图

若要将 Local Context Library 添加到网页,请先创建一个 LocalContextMapView 实例,然后设置所需的属性:

  • element - 应显示地图的 div 元素(在本例中名为“map”)。
  • placeTypePreferences - Local Context Library 应返回的地点类型(最多 10 个)。
  • maxPlaceCount - 可显示的地点数量上限 (1 - 24)。
  • locationRestriction(可选)- 将地点搜索限制为特定位置。默认为地图视口。

有了 LocalContextMapView 实例后,您可以对内部 Map 实例设置地图选项LocalContextMapView 中包含的地图支持与标准 Maps JavaScript API 地图相同的所有地图选项。以下示例展示了如何创建新的 LocalContextMapView 实例,并在内部 Map 上设置几个选项:

TypeScript

let map: google.maps.Map;

function initMap() {
  const localContextMapView = new google.maps.localContext.LocalContextMapView({
    element: document.getElementById("map"),
    placeTypePreferences: [
      { type: "restaurant" },
      { type: "tourist_attraction" },
    ],
    maxPlaceCount: 12,
  });

  map = localContextMapView.map!;

  map.setOptions({
    center: { lat: 51.507307, lng: -0.08114 },
    zoom: 14,
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

let map;

function initMap() {
  const localContextMapView = new google.maps.localContext.LocalContextMapView({
    element: document.getElementById("map"),
    placeTypePreferences: [
      { type: "restaurant" },
      { type: "tourist_attraction" },
    ],
    maxPlaceCount: 12,
  });

  map = localContextMapView.map;
  map.setOptions({
    center: { lat: 51.507307, lng: -0.08114 },
    zoom: 14,
  });
}

window.initMap = initMap;

推迟加载 Local Context 数据

若要在初始化时推迟加载 Local Context 数据,您可以将 LocalContextMapView maxPlaceCount 选项设置为 0。如果您想要等到用户准备好查看数据后再加载,使用这种方法会非常方便。准备好加载 Local Context 数据后,请将 maxPlaceCount 设置为 1 或更大的值。以下示例展示了如何在不加载 Local Context 数据的情况下初始化地图,然后设置 maxPlaceCount 以加载数据:

// Initialize without Local Context data.
const localContextMapView = new google.maps.localContext.LocalContextMapView({
    element: document.querySelector('#map'),
    placeTypePreferences: ['restaurant'],
    maxPlaceCount: 0, // Avoids an automatic call to load places during initialization.
  });

//...

// Show places now.
localContextMapView.maxPlaceCount = 12;

对 Local Context 界面的显示进行切换

您可以将 LocalContextMapView maxPlaceCount 选项设置为 0 来切换 Local Context 界面元素。如需再次显示 Local Context 界面,请将 maxPlaceCount 设置为 1 或更大的值。

设置地图最小尺寸

Local Context Library 会根据 LocalContextMapView 的渲染大小相应调整显示界面。LocalContextMapView 支持的最小尺寸为:

  • 300 像素 x 480 像素(纵向)
  • 480 像素 x 380 像素(横向)

如果包含 LocalContextMapView 的元素的尺寸下降到支持的最小尺寸以下,系统不会显示 Local Context Library 元素(包括地点选择器和地图注点)。浏览器缩放级别会影响支持的最小尺寸;例如,如果浏览器窗口缩放到 200%,支持的最小尺寸为 600 x 960(纵向)和 960 x 760(横向)。

CSS 建议

Local Context Library DOM 中的 CSS 类不属于公共 API,并且不支持在 Local Context Library DOM 中设置元素的样式、修改元素或选择元素。我们强烈建议遵循以下准则,以免 DOM 样式发生冲突,并确保 Local Context Library 地图视图正确显示:

  • 请勿使用 Local Context Library CSS 类,因为这些类可能会在没有通知的情况下更改。
  • 请勿在 Local Context Library DOM 内设置元素的样式、修改元素或选择元素。

如果您使用的 CSS 框架可执行此类修改,也许可以解决样式冲突问题。

例如,如果您要将整个页面 box-sizing 更改为 border-box,请执行以下操作:

  • 使用 box-sizing 替换功能,将 <html> 元素设置为 border-box
  • 对于包含 Local Context Library 地图视图的元素,请使用 box-sizing: initial
  • 对于所有其他元素,请使用 box-sizing: inherit

这可确保 Local Context Library DOM 使用低特异性选择器将 box-sizing 重置为标准默认值。

代码如下所示:

html {
  box-sizing: border-box;
}
*, *::before, *::after {
  box-sizing: inherit;
}

.container-for-google-maps {
  box-sizing: initial;
}