UNPKG

leaflet

Version:

JavaScript library for mobile-friendly interactive maps

220 lines (180 loc) • 7.12 kB
import {DivOverlay} from './DivOverlay.js'; import {Point} from '../geometry/Point.js'; import * as DomUtil from '../dom/DomUtil.js'; import * as Util from '../core/Util.js'; /** @import {Defaults, DivOverlayEventMap, PointExpression, TooltipDefaults, TooltipOptions, ZoomAnimEvent} from '../types.js' */ /** @import {LatLng} from '../geo/LatLng.js' */ /** @import {LeafletMap} from '../map/Map.js' */ const defaultOptions = { /** `Map pane` where the tooltip will be added. */ pane: 'tooltipPane', /** * Optional offset of the tooltip position, in pixels. Mirrored horizontally when an `auto` tooltip opens to the * left. * @type {PointExpression} */ offset: [0, 0], /** * Direction where to open the tooltip. Possible values are: `right`, `left`, `top`, `bottom`, `center`, `auto`. * `auto` will dynamically switch between `right` and `left` according to the tooltip position on the map. * @type {'right' | 'left' | 'top' | 'bottom' | 'center' | 'auto'} */ direction: 'auto', /** Whether to open the tooltip permanently or only on pointerover. */ permanent: false, /** If true, the tooltip will follow the pointer instead of being fixed at the feature center. */ sticky: false, /** Tooltip container opacity. */ opacity: 0.9 }; /** @typedef {typeof defaultOptions} TooltipDefaultsValues */ /** * Which point of the tooltip (as a fraction of its width and height) sits at the anchor, for each direction. * @type {Record<string, [number, number]>} */ const directions = {top: [0.5, 1], bottom: [0.5, 0], center: [0.5, 0.5], right: [0, 0.5], left: [1, 0.5]}; /** * @typedef {Object} TooltipEventProps * @property {Tooltip} tooltip The tooltip that was opened or closed. */ /** * Used to display small texts on top of map layers. * @example * If you want to just bind a tooltip to marker: * * ```js * marker.bindTooltip("my tooltip text").openTooltip(); * ``` * Path overlays like polylines also have a `bindTooltip` method. * * A tooltip can be also standalone: * * ```js * const tooltip = new Tooltip() * .setLatLng(latlng) * .setContent('Hello world!<br />This is a nice tooltip.') * .addTo(map); * ``` * or * ```js * const tooltip = new Tooltip(latlng, {content: 'Hello world!<br />This is a nice tooltip.'}) * .addTo(map); * ``` * * **Security note.** Tooltip string content is rendered as HTML. If your content may include untrusted input (e.g. * data from users or external APIs), sanitize it first, or build a DOM element using `textContent` to render it as * plain text: * * ```js * const el = document.createElement('div'); * el.textContent = untrustedString; * marker.bindTooltip(el); * ``` * * Note about tooltip offset. Leaflet takes two options in consideration * for computing tooltip offsetting: * - the `offset` Tooltip option: it defaults to [0, 0], and it's specific to one tooltip. * Add a positive x offset to move the tooltip to the right, and a positive y offset to * move it to the bottom. Negatives will move to the left and top. * - the `tooltipAnchor` Icon option: this will only be considered for Marker. You * should adapt this value if you use a custom icon. * * @template {TooltipOptions} [O=TooltipOptions] * @template {DivOverlayEventMap} [E=DivOverlayEventMap] * @extends {DivOverlay<O & TooltipDefaults, E>} */ export class Tooltip extends DivOverlay { /** @type {Defaults<TooltipOptions>} */ static defaultOptions = defaultOptions; /** @param {LeafletMap} map */ onAdd(map) { super.onAdd(map); this.setOpacity(this.options.opacity); map.fire('tooltipopen', {tooltip: this}); if (this._source) { this.addEventParent(this._source); /** @type {Element | null | undefined} */ this._ariaSource = this._source.getElement?.(); if (this._ariaSource) { updateDescribedBy(this._ariaSource, this._container.id, true); } this._source.fire('tooltipopen', {tooltip: this}, true); } } /** @param {LeafletMap} map */ onRemove(map) { super.onRemove(map); map.fire('tooltipclose', {tooltip: this}); if (this._source) { this.removeEventParent(this._source); if (this._ariaSource) { updateDescribedBy(this._ariaSource, this._container.id, false); } this._ariaSource = null; this._source.fire('tooltipclose', {tooltip: this}, true); } } getEvents() { const events = super.getEvents(); if (!this.options.permanent) { events.preclick = this.close; } return events; } _initLayout() { const prefix = 'leaflet-tooltip', className = `${prefix} ${this.options.className || ''} leaflet-zoom-animated`; this._contentNode = this._container = DomUtil.create('div', className); this._container.setAttribute('role', 'tooltip'); this._container.id = `leaflet-tooltip-${Util.stamp(this)}`; } _updateLayout() {} _adjustPan() {} /** @param {Point} pos */ _setPosition(pos) { const container = this._container, offset = new Point(this.options.offset).clone(); let direction = this.options.direction; if (!(direction in directions)) { // auto: open away from the map center, mirroring the offset direction = pos.x <= this._map._getCenterLayerPoint().x ? 'right' : 'left'; if (direction === 'left') { offset.x = -offset.x; } } const [fx, fy] = directions[direction]; const shift = this._getAnchor(direction).add(offset); for (const d in directions) { container.classList.toggle(`leaflet-tooltip-${d}`, d === direction); } // a percentage translate follows the tooltip's own size, so it never has to be measured (which would // force a reflow per tooltip on every zoom); browsers without CSS round() ignore the second value container.style.translate = `${-fx * 100}% ${-fy * 100}%`; container.style.translate = `round(${-fx * 100}%, 1px) round(${-fy * 100}%, 1px)`; DomUtil.setPosition(container, pos._add(shift)); } _updatePosition() { const pos = this._map._snapLayerPoint(this._map.latLngToLayerPoint(/** @type {LatLng} */ (this._latlng))); this._setPosition(pos); } /** * Sets the opacity of the tooltip. * @param {number} opacity */ setOpacity(opacity) { this.options.opacity = opacity; if (this._container) { this._container.style.opacity = `${opacity}`; } } /** @param {ZoomAnimEvent} e */ _animateZoom(e) { const pos = this._map._latLngToNewLayerPoint(/** @type {LatLng} */ (this._latlng), e.zoom, e.center); this._setPosition(pos); } /** @param {string} [direction] */ _getAnchor(direction) { // Where should we anchor the tooltip on the source layer? return new Point(this._source?._getTooltipAnchor && !this.options.sticky ? this._source._getTooltipAnchor(direction) : [0, 0]); } } // aria-describedby is a whitespace-separated ID list that the app may also be using /** @param {Element} el @param {string} id @param {boolean} add */ function updateDescribedBy(el, id, add) { const ids = Util.splitWords(el.getAttribute('aria-describedby') ?? '').filter(s => s && s !== id); if (add) { ids.push(id); } if (ids.length) { el.setAttribute('aria-describedby', ids.join(' ')); } else { el.removeAttribute('aria-describedby'); } }