弹窗 Popup 与提示 Tooltip

标准版提供 Popup 和 Tooltip 两个类，用于在地图上显示信息气泡和悬浮提示。

---

Popup

弹窗组件，可在地图指定位置显示 HTML 内容。

构造函数

class Popup {
  readonly id: string;

  constructor(options?: PopupOptions);
}

interface PopupOptions {
  position?: Coordinate;
  content?: string | HTMLElement;
  offset?: [number, number, number?];
  closeButton?: boolean;
  maxWidth?: number;
  className?: string;
}

属性

属性	类型	默认值	说明
id	string	自动生成	弹窗唯一标识

方法

方法	参数	返回值	说明
setPosition(c)	c: Coordinate	this	设置弹窗位置
setContent(c)	c: string | HTMLElement	this	设置弹窗内容
setOffset(o)	o: [number, number, number?]	this	设置偏移量
setFeature(f)	f: Feature	this	关联要素
open()	—	this	打开弹窗
close()	—	this	关闭弹窗
isOpen()	—	boolean	是否打开
getElement()	—	HTMLElement	获取 DOM 元素
update()	—	this	刷新弹窗

示例

基本用法

import { Popup } from '@gmap/standard';

const popup = new Popup({
  position: [116.397, 39.908],
  content: '<h3>天安门广场</h3><p>北京市中心</p>',
  offset: [0, -20],
  closeButton: true,
  maxWidth: 300,
  className: 'my-popup',
});

popup.open();

绑定到要素

import { Popup, Point } from '@gmap/standard';

const popup = new Popup({
  content: '<strong>站点 A</strong>',
});

// 假设 feature 是从查询得到的要素
popup.setFeature(feature);
popup.setPosition(feature.geometry.getCentroid().get());
popup.open();

动态更新内容

const popup = new Popup({ position: [116.4, 39.9] });
popup.open();

// 动态更新
popup.setContent('<p>加载中...</p>');

// 异步获取数据后更新
fetch('/api/info/123')
  .then(res => res.json())
  .then(data => {
    popup.setContent(`
      <h3>${data.name}</h3>
      <p>类型: ${data.type}</p>
      <p>面积: ${data.area} km²</p>
    `);
    popup.update();
  });

链式调用

const popup = new Popup()
  .setPosition([116.397, 39.908])
  .setContent('Hello!')
  .setOffset([0, -10])
  .open();

关闭弹窗

// 关闭
popup.close();
console.log(popup.isOpen()); // false

---

Tooltip

提示组件，在鼠标悬停时显示简短信息。

构造函数

class Tooltip {
  readonly id: string;

  constructor();
}

属性

属性	类型	说明
id	string	提示唯一标识（自动生成）

方法

方法	参数	返回值	说明
show(coord, content?)	coord: Coordinate, content?: string	this	在指定位置显示提示
showForFeature(f, content?)	f: Feature, content?: string	this	为要素显示提示
hide()	—	this	隐藏提示
setContent(c)	c: string	this	设置提示内容

示例

基本用法

import { Tooltip } from '@gmap/standard';

const tooltip = new Tooltip();

// 在指定位置显示
tooltip.show([116.397, 39.908], '这里是天安门');

// 更新内容
tooltip.setContent('更新后的提示');

// 隐藏
tooltip.hide();

配合图层使用

import { Tooltip } from '@gmap/standard';

const tooltip = new Tooltip();

// 当鼠标悬停在要素上时显示提示
layer.on('mouseenter', (e) => {
  const name = e.feature.properties.name;
  const value = e.feature.properties.value;
  tooltip.showForFeature(e.feature, `${name}: ${value}`);
});

layer.on('mouseleave', () => {
  tooltip.hide();
});

链式调用

const tooltip = new Tooltip()
  .show([116.4, 39.9], '提示内容')
  .setContent('更新内容');

---

Popup 与 Tooltip 对比

特性	Popup	Tooltip
交互方式	点击触发	悬停触发
内容类型	HTML 字符串或 HTMLElement	纯文本字符串
是否可关闭	支持关闭按钮	自动隐藏
定位方式	坐标 + 偏移	跟随鼠标
关联要素	setFeature()	showForFeature()
典型用途	要素详情面板	要素名称提示

综合示例

import { Popup, Tooltip, GeoJsonSource, FeatureLayer, SimpleRenderer, FillSymbol } from '@gmap/standard';

const source = new GeoJsonSource({ id: 'districts', data: districtsGeoJSON });
const layer = new FeatureLayer({
  id: 'districts',
  source,
  renderer: new SimpleRenderer({ symbol: new FillSymbol({ color: '#3388ff' }) }),
});

const popup = new Popup({ offset: [0, -15], closeButton: true, maxWidth: 350 });
const tooltip = new Tooltip();

// 悬停显示名称
layer.on('mouseenter', (e) => {
  tooltip.showForFeature(e.feature, e.feature.properties.name);
});

layer.on('mouseleave', () => {
  tooltip.hide();
});

// 点击显示详情
layer.on('click', (e) => {
  const p = e.feature.properties;
  popup
    .setFeature(e.feature)
    .setPosition(e.coordinate)
    .setContent(`
      <div class="popup-content">
        <h3>${p.name}</h3>
        <table>
          <tr><td>人口</td><td>${p.population.toLocaleString()}</td></tr>
          <tr><td>面积</td><td>${p.area} km²</td></tr>
          <tr><td>密度</td><td>${(p.population / p.area).toFixed(0)} 人/km²</td></tr>
        </table>
      </div>
    `)
    .open();
});

map.on('click', () => popup.close());