121 lines
2.8 KiB
Markdown
121 lines
2.8 KiB
Markdown
# ngx-open-map-wrapper
|
||
|
||
An Angular 16+ library that provides a **unified map component** with automatic fallback between **MapLibre GL** (WebGL vector maps) and **Leaflet** (raster maps).
|
||
|
||
It automatically chooses the best renderer for the user’s device:
|
||
- **MapLibre GL** if WebGL is supported
|
||
- **Leaflet** if WebGL is not available or raster rendering is forced
|
||
|
||
---
|
||
|
||
## ✨ Features
|
||
|
||
- 🗺️ Always shows a map — automatically picks the right engine for the device
|
||
- ⚡ Uses **MapLibre GL** for modern devices with WebGL support
|
||
- 🪶 Falls back to **Leaflet** for older or low‑end devices
|
||
- 🎯 Unified API for markers, zoom, and center — no need to learn two libraries
|
||
- 📱 Works seamlessly across desktop and mobile
|
||
- 🧩 Angular‑native: standalone components, signals, and modern syntax
|
||
|
||
---
|
||
|
||
## 📦 Installation
|
||
|
||
Install the library and its peer dependencies:
|
||
|
||
```bash
|
||
yarn add ngx-open-open-map-wrapper leaflet maplibre-gl
|
||
```
|
||
|
||
Then import the required CSS styles in your global `styles.css` (or `styles.scss`):
|
||
|
||
```css
|
||
@import "leaflet/dist/leaflet.css";
|
||
@import "maplibre-gl/dist/maplibre-gl.css";
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 Usage
|
||
|
||
### Import the component
|
||
|
||
Since the library is **standalone‑ready**, you can import the component directly:
|
||
|
||
```ts
|
||
import { Component } from '@angular/core';
|
||
import { MapComponent, MapFacade } from 'ngx-open-open-map-wrapper';
|
||
|
||
@Component({
|
||
selector: 'app-root',
|
||
standalone: true,
|
||
imports: [MapComponent],
|
||
template: `
|
||
<open-map
|
||
[center]="[46.3385, -72.6106]"
|
||
[zoom]="14"
|
||
(mapReady)="onMapReady($event)"
|
||
></open-map>
|
||
`,
|
||
})
|
||
export class AppComponent {
|
||
private map?: MapFacade;
|
||
|
||
onMapReady(facade: MapFacade) {
|
||
this.map = facade;
|
||
this.map.addMarker([46.3385, -72.6106], { color: 'blue' });
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## ⚙️ API
|
||
|
||
### `MapComponent` Inputs
|
||
- `center: [lat, lng]` → Initial map center
|
||
- `zoom: number` → Initial zoom level
|
||
- `forceRaster: boolean` → Force Leaflet raster mode even if WebGL is available
|
||
- `styleUrl: string` → MapLibre style URL (default: MapLibre basic style)
|
||
|
||
### `MapComponent` Outputs
|
||
- `(mapReady: MapFacade)` → Emits the `MapFacade` instance once the map is initialized
|
||
|
||
---
|
||
|
||
### `MapFacade` Methods
|
||
- `setCenter([lat, lng])` → Move the map center
|
||
- `setZoom(zoom: number)` → Set zoom level
|
||
- `addMarker([lat, lng], { color?: string })` → Add a marker
|
||
- `destroy()` → Clean up map instance
|
||
|
||
---
|
||
|
||
## 🧩 WebGL Detection Directive
|
||
|
||
You can also use the directive directly if you want to check WebGL support:
|
||
|
||
```html
|
||
<div webglDetection (webglSupport)="onWebGLCheck($event)">
|
||
@if (webglOk) {
|
||
<my-component-using-webgl></my-component-using-webgl>
|
||
} @else {
|
||
<p>WebGL not supported → fallback</p>
|
||
}
|
||
</div>
|
||
```
|
||
|
||
```ts
|
||
webglOk = false;
|
||
|
||
onWebGLCheck(supported: boolean) {
|
||
this.webglOk = supported;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📜 License
|
||
|
||
MIT
|