liyuanqiu / leaflet-spots Goto Github PK

View Code? Open in Web Editor NEW

0.0 1.0 0.0 4.14 MB

A paradigm and tool for rendering spots on a leaflet map.

TypeScript 91.69% JavaScript 8.31%

leaflet

leaflet-spots's Introduction

Introduce

leaflet-spots is a paradigm and tool for rendering spots on a leaflet map.

Motivation

Part of my job is data visualization based on geographic location. For example:

Texi/bus realtime positioning
IoT realtime positioning
Satellites projecting on earth
User distribution

Taxis, buses, IoT devices, satellite projections, users need to be drawn on the map, and I call them spot. A taxi is a spot, a user is a spot, etc.

See this example:

This kind of projects have an almost same logic, so I decided to abstract it out to be a common extension of leaflet.

Demo

https://codesandbox.io/s/leaflet-spot-demo-80eyw

Installation

# install dependency
yarn add leaflet
// or
// npm install --save leaflet

# install leaflet-spots
yarn add leaflet-spots
// or
// npm install --save leaflet-spots

Quick Start

See this demo with source code:

https://codesandbox.io/s/leaflet-spot-demo-80eyw

API Reference

import { LeafletSpots, MetadataParser } from 'leaflet-spots';

class MetadataParser<T>

Describe how to parse your data in class MetadataParser

T is the type of your metadata like { id: 1, lng: 120, lat: 30 }

Method	Parameters	Return	Description
constructor	MetadataParserOptions<T>	-	-

MetadataParserOptions

export interface MetadataParserOptions<T> {
  /**
   * parse lat,lng from metadata
   */
  parseLatlng: LatlngParser<T>;
  /**
   * parse leaflet shape from metadata
   */
  parseShape: ShapeParser<T>;
  /**
   * parse id from metadata
   */
  parseId: IdParser<T>;
  /**
   * parse whether the station should be update
   */
  parseShouldUpdate?: ShouldUpdateParser<T>;
  /**
   * parse whether the station is filtered
   */
  parseFilteration?: FilterationParser<T>;
}

Parser types

export type LatlngParser<T> = (metadata: T) => LatLng;
export type ShapeParser<T> = (metadata: T) => Layer;
export type IdParser<T> = (metadata: T) => string;
export type ShouldUpdateParser<T> = (prev: T, next: T) => boolean;
export type FilterationParser<T> = (metadata: T) => boolean;

class LeafletSpots<T>

Using this class to visualize your data

T is the type of your metadata like { id: 1, lng: 120, lat: 30 }

Method	Parameters	Return	Description
constructor	LeafletSpotsOptions<T>	-	-
getLayer	-	LayerGroup	The layer group that holds all the spots
setSpots	T[]	void	Set spots data, LeafletSpots will render them to leaflet map instance
addSpot	T	void	Add a spot to leaflet map instance
removeSpot	T	void	Remove a spot from leaflet map instance
updateSpot	T	void	Update a spot in leaflet map instance
selectSpot	T	void	Mark this spot to be selected
unselectSpot	T	void	Cancel selection
forceRender	-	void	Force rerender all spots

LeafletSpotsOptions

/**
 * The options to create the instance of `LeafletSpots`
 * @template T User data unit
 */
export interface LeafletSpotsOptions<T> {
  /**
   * Use `MetadatParser` to parse user data.
   * @template T User data unit
   */
  metadataParser: MetadataParser<T>;
  /**
   * The spot events which will be attached to the spot.
   * @template T User data unit
   */
  spotEvents?: SpotEvents<T>;
  /**
   * handle interactive like 'selected', 'filtered', etc
   * @template T User data unit
   */
  handleInteractive?: InteractiveHandler<T>;
}

SpotEvents<T>

/**
 * The spot events which will be attached to the spot.
 * @template T User data unit
 */
export interface SpotEvents<T> {
  [eventName: string]: (e: LeafletEvent, metadata: T) => void;
}

InteractiveHandler<T>

/**
 * Interactive options.
 */
export interface InteractiveOptions {
  filtered: boolean;
  selected: boolean;
}

/**
 * User defined handler for interactive.
 * @template T User data unit
 */
export type InteractiveHandler<T> = (
  metadata: T,
  shape: Layer,
  options: InteractiveOptions,
) => void;