Room-Leaflet
Room-Leaflet est un composant basé sur Room permettant d’afficher des cartes interactives en utilisant la librairie JavaScript open source Leaflet.
Room-Leaflet est disponible sous la forme d’un module ECMAScript 6 (une version non ECMAScript est également disponible) qui comme Room, ne nécessite pas de système de construction (build tools). Room-Leaflet est donc utilisable directement dans un navigateur Web.
Installation
Room-Leaflet est disponible sur :
- GitHub : https://github.com/GreenerSoft/Room-Leaflet
- NPM : https://www.npmjs.com/package/room-leaflet
- jsDelivr : https://www.jsdelivr.com/package/npm/room-leaflet
Vous pouvez aussi auto-héberger Room-Suspense en téléchargeant l’un des fichiers suivants :
Description | Fichier |
---|---|
Version ESM (source) | room-leaflet-1.0.0.js |
Version ESM (production) | room-leaflet-1.0.0.min.js |
Version non ESM (source) | room-leaflet-nm-1.0.0.js |
Version non ESM (production) | room-leaflet-nm-1.0.0.min.js |
Le référencement du fichier dans vos pages dépend de la version que vous voulez utiliser.
Pour utiliser Room-Leaflet il faut importer la librairie Leaflet.
Pour rappel, la librairie Leaflet utilise un fichier CSS qui doit impérativement être chargé avant la librairie et il est indispensable de donner une dimension par CSS à l’élément
<div>
qui contient la carte (classeleaflet-container
par défaut mais qui peut être changée via la propriétéclassName
du composant).
Version ESM
En version ESM, vous pouvez utiliser un élément <script>
avec un attribut type
à la valeur module
, mais vous avez en plus la possibilité de laisser Room-Leaflet importer dynamiquement la librairie Leaflet en tant que module ECMAScript à la condition d’ajouter dans votre carte d’importation une entrée nommée Leaflet (en plus des entrées Room et RomLeaflet).
Pour que cette possibilité fonction vous devez passez par un CDN capable de convertir Leaflet en module ECMAScript 6, c’est très simple comme indiqué dans cette article de GreenerSoft.
Une carte d’importation est obligatoire en version ESM à minima pour indiquer où est le module Room.
Vous trouverez un exemple de carte d’importation dans le fichier index.html
de notre dépôt Room-Test. Il contient par ailleurs plusieurs exemples d’utilisation de Room-Leaflet.
Version non ESM
En version non ESM, vous devez avoir un élément <script>
dans votre page HTML avant ceux pour Room et Room-Leaflet.
Vous avez alors un objet RoomLeafet
attaché à l’objet principal window
qui permet d’appeler les fonctions (RoomLeaflet.MapContainer()
par exemple).
Une autre solution plus simple consiste à utiliser l’affection par décomposition comme par exemple ici :
const {OpenStreetMapProvider, L, addTileLayer, MapContainer} = RoomLeaflet;
Vous pouvez alors par exemple appeler directement la fonction MapContainer()
sans préfixer avec RoomLeaflet.
.
Fournisseur de tuiles
Pour afficher un fond de carte ou des couches à superposer sur une carte, un fournisseur de tuiles (tiles) doit être utilisé.
Un fournisseur de tuiles est décrit par un objet provider
qui est constitué de 3 propriétés :
wms
: Un booléen qui indique si le fournisseur de tuiles est de type WMS ou pas.url
: Une chaîne de caractères contenant l’URL donnant les tuiles.options
: Un objet avec les propriétés décrites comme options de la méthodeL.tileLayer.wms()
si la propriétéwms
est àtrue
et les options de la méthodeL.tileLayer()
de Leaflet si la propriétéwms
est àfalse
.
L’objet provider
est utilisable avec les fonctions createTileLayer()
, addTileLayer()
et MapContainer()
de Room-Leaflet.
La fonction OpenStreetMapProvider()
de Room-Leaflet retourne un objet de cette forme.
Variable L
Classiquement avec Leaflet, la variable L
contient l’objet qui permet d’appeler les méthodes de Leaflet (elle est attachée à l’objet principal window
).
Cette variable est exportée par le module Room-Leaflet et il faut l’utiliser en version ESM surtout si vous laissez importer dynamiquement Leaflet par Room-Leaflet comme indiqué plus haut.
En version non ESM, la variable L
est également disponible (c’est juste un alias de la variable L
de window
).
Fonctions
Room-Leaflet est minimaliste en exportant uniquement 7 fonctions.
Fonction EUCenter()
Cette fonction retrourne les coordonnées du centre de l’Europe sous la forme d’un tableau contenant la latitude et la longitude.
Fonction FranceCenter()
Cette fonction retourne les coordonnées du centre de la France.
Fonction USACenter()
Cette fonction retourne les coordonnées du centre des USA.
Fonction OpenStreetMapProvider()
Cette fonction retourne un objet décrivant OpenStreetMap comme fournisseur de tuiles de fond de carte.
Elle est utilisable avec les fonctions createTileLayer()
, addTileLayer()
et MapContainer()
de Room-Leaflet.
Fonction createTileLayer()
Cette fonction retourne un objet TileLayer
de la librairie Leaflet à partir d’un fournisseur de tuiles.
La signature de la fonction est :
createTileLayer(provider)
Le paramètre requis provider
est un objet décrivant un fournisseur de tuiles.
Si la propriété wms
de l’objet provider
est à true
, la fonction utilise la méthode L.tileLayer.wms()
de Leaflet.
Si la propriété est à false
, la fonction utilise la méthode L.tileLayer()
de Leaflet.
La fonction
createTileLayer()
ne doit être appelée que via votre fonctionmount()
passée à la fonctionMapContainer()
car elle a besoin que la librairie Leaflet soit chargée.
Fonction addTileLayer()
Cette fonction créé et ajoute un objet TileLayer
de la librairie Leaflet à une carte donnée et à partir d’un fournisseur de tuiles. Elle retourne l’objet créé.
La signature de la fonction est :
addTileLayer(map, provider)
Le paramètre requis map
est un objet Map
de Leaflet qui représente la carte dans laquelle le layer doit être ajouté.
Le paramètre requis provider
est un objet décrivant un fournisseur de tuiles.
La fonction addTileLayer()
utilise en interne la fonction createTileLayer()
pour créer le layer.
La fonction
addTileLayer()
ne doit être appelée que via votre fonctionmount()
passée à la fonctionMapContainer()
car elle a besoin que la librairie Leaflet soit chargée.
Fonction MapContainer()
Cette fonction asynchrone retourne une promesse JavaScript qui après résolution donne le composant Room-Leaflet. Le composant est un élément <div>
contenant une carte gérée par Leaflet ou un élément <p>
si la librairie Leaflet n’est pas disponible (pas pu être chargée ou pas chargée).
En version ESM, c’est l’appel à cette fonction qui s’occupe de charger dynamiquement la librairie Leaflet en tant que module ECMAScript si la variable
L
n’est pas déjà renseignée.
La signature de la fonction est :
async MapContainer({id, className, provider, mount, unmount})
L’unique paramètre attendu est un objet pouvant contenir des propriétés toutes optionnelles :
id
: Une chaîne de caractères contenant l’identifiant CSS à utiliser pour l’élément<div>
.className
: Une chaîne de caractères contenant la ou les classes CSS à utiliser pour l’élément<div>
.provider
: Un objet décrivant le fournisseur de tuiles (fond de carte) à utiliser.mount
: Une fonction appelée au montage de l’élément<div>
dans le DOM.unmount
: Une fonction appelée à la suppression de l’élément<div>
du DOM.
Ces 5 propriétés sont spécifiques à Room-Leaflet mais vous pouvez en plus ajouter comme propriétés, toutes les options supportées par la méthode L.map()
de Leaflet, par exemple center
, zoom
, maxZoom
, scrollWellZoom
, etc.
Les fonctions mount()
et unmount()
reçoivent un unique paramètre map
qui est est un objet Map
de Leaflet et qui représente la carte associée à l’élément <div>
.
La fonction mount()
permet par exemple d’ajouter d’autres éléments dans la carte comme des couches supplémentaires (fonction addTileLayer()
), des marqueurs, des popups, etc. C’est aussi là qu’il est possible de créer des effets avec la fonction createEffect()
de Room ou de démarrer des timers.
La fonction unmount()
permet par exemple d’arrêter des timers démarrés dans la fonction mount()
ou de supprimer des éléments mémorisés pour éviter des fuites de mémoire.
Exemple
Dans l’exemple suivant, une carte est affichée centrée sur les USA avec par dessus les intempéries en cours (pluie, grêle, neige) obtenues par les radars météorologiques du réseau NEXRAD.
Ceci est réalisé par le code suivant :
function MapNexrad() {
return elements().div(
Suspense({fallback: BounceLoader()},
MapContainer({
className: "mapContainer",
provider: OpenStreetMapProvider(),
mount: map => addTileLayer(map, NexradProvider()),
center: USACenter(),
scrollWheelZoom: false,
zoom: 4
})
)
);
}
Le composant retourné par la fonction MapContainer()
étant asynchrone, il est passé comme enfant au composant Room-Suspense (il était possible de faire sans en déclarant la fonction MapNexrad()
asynchrone et en utilisant le mot clé await
devant l’appel de MapContainer()
).
Le fond de carte est donné par la fonction OpenStreetMapProvider()
via la propriété provider
.
Une fonction est associée à la propriété mount
qui se charge d’ajouter les tuiles des données météorologiques sur la carte quand elle est montée dans le DOM en utilisant la fonction addTileLayer()
avec un fournisseur de tuiles donné par la fonction NexradProvider()
.
Les propriétés center
, scrollWhellZoom
et zoom
(des options de la méthode L.map()
de Leaflet) sont utilisées pour gérer le centrage et le zoom par défaut de la carte.
Vous retrouverez cet exemple et une version animée de cette carte dans notre dépôt Room-Test.
Dernière mise à jour :