# Carte

> Découvrez comment utiliser le composant Carte pour afficher une carte interactive dans votre application, créer des marqueurs et afficher des itinéraires avec des fournisseurs de cartes comme Google Maps, OpenStreetMap et Mapbox.

https://docs.pandasuite.com/fr/essentials/components/map/

**Le composant Carte permet d'afficher une carte dans votre application, d'y créer des marqueurs (points d'intérêt, zones) ou d'afficher un itinéraire. Ce composant s'appuie sur un fournisseur de cartes : Google Maps, OpenStreetMap et Mapbox.**

[Image : Application mobile « Près de moi » affichant une carte OpenStreetMap de Montreuil avec deux marqueurs et une zone circulaire]

Google Maps, OpenStreetMap et Mapbox sont des outils de cartographie en ligne :

- [Google Maps](https://www.google.com/maps) est la référence en la matière.
- [OpenStreetMap](https://www.openstreetmap.fr/) est une carte du monde entier publiée gratuitement sous une licence de contenu libre. Construite par des contributeurs bénévoles, elle est éditable par tous et en constante évolution.
- [Mapbox](https://www.mapbox.com/) est plus avancé et offre de nombreuses personnalisations du fond de carte. Par contre, son utilisation nécessite un abonnement.

## Afficher une carte

Cliquez sur **Composants** et insérez le composant **Carte.**

Dans les **Propriétés**, choisissez le fournisseur : **Google Maps**, **OpenStreetMap** ou **Mapbox**.

Double-cliquez sur le composant au sein de votre espace de travail (ou cliquez sur la flèche de sa ligne dans la liste des objets) pour afficher la carte.

[Image : Carte de Paris ouverte avec ses outils de dessin ; ses propriétés encadrées : centre, Zoom 13, Zoom min. et max., OpenStreetMap et Repeat world]

Saisissez les coordonnées (Latitude et Longitude) du point central de votre carte. Définissez le niveau de zoom par défaut.

Utilisez **Min. zoom** et **Max. zoom** pour définir jusqu'où les utilisateurs peuvent dézoomer ou zoomer. Ces limites contraignent aussi les interactions utilisateur à la souris, au trackpad ou avec les contrôles de zoom.

Utilisez **Répéter le monde** pour contrôler le déplacement horizontal. Quand l'option est activée, les utilisateurs peuvent se déplacer sur des copies répétées du monde, tout en gardant les couches de carte et les marqueurs disponibles lorsque la carte se répète horizontalement. Quand elle est désactivée, les utilisateurs restent dans une seule carte du monde et ne peuvent pas dézoomer au-delà de la vue complète du monde.

> **Info**
>
> Si vous choisissez Google Maps, il est nécessaire d'insérer votre **clé API**.
> Pour Mapbox, vous devez impérativement créer un compte au préalable et
> récupérer votre **Access Token** pour afficher la carte. [En savoir
> plus](https://docs.mapbox.com/help/getting-started/access-tokens/)

Avec l'option **Localisation utilisateur**, vous pouvez actualiser la carte en fonction de la position de l'utilisateur. Quand elle est activée, utilisez **Contrôle de la carte** pour choisir comment la carte suit l'utilisateur : **Aucun**, **Une seule fois**, **Toujours**, **Jusqu'à un déplacement** ou **Jusqu'à un déplacement ou zoom**. Vous pouvez aussi choisir d'afficher l'épingle centrale avec **Afficher l'épingle du centre**.

## Ajouter des marqueurs et un itinéraire

Vous pouvez créer des [marqueurs](https://docs.pandasuite.com/fr/essentials/interactions/markers/), des points d'intérêts situés à une position spécifique sur la carte.

Pour créer un marqueur, utilisez les boutons d'édition qui apparaissent à gauche de la carte. Sélectionnez le type de marqueur (point d'intérêt, zone rectangulaire ou circulaire) et cliquez directement sur la carte pour le positionner. Vous pouvez également créer des tracés pour représenter un itinéraire.

> **Astuce**
>
> Vous n'avez pas besoin d'une base de données pour ajouter des marqueurs
> cliquables. Placez des marqueurs manuellement sur la carte et associez une
> action à chacun (**Ouvrir une pop-up**, **Aller à un écran**, **Ouvrir une
> URL**…).

Lorsque vous créez un marqueur, celui-ci s'affiche dans la liste de gauche.

[Image : Outil marqueur encadré sur la carte ; Jardin du Luxembourg, sélectionné dans la liste, affiche sa propriété Visible et sa position, encadrées]

Vous pouvez éditer les propriétés de ces marqueurs :

- Choisissez si le marqueur est **Visible**. Cette propriété prend en charge le data binding, ce qui permet d'afficher ou de masquer des marqueurs depuis un champ de collection ou un autre composant.
- Définissez sa position exacte (latitude et longitude).
- Personnalisez l'apparence de l'icône : indiquez l'URL d'une icône, sa taille et sa position.
- Choisissez si vous souhaitez afficher une pop-up au clic sur le marqueur. Vous pouvez personnaliser le texte.

> **Info**
>
> Pour l'apparence des marqueurs, nous utilisons le service
> [Geopify](https://apidocs.geoapify.com/playground/icon) : vous pouvez
> personnaliser l'apparence et générer une nouvelle URL. Vous pouvez également
> utiliser n'importe quel autre service.

[Image : Marqueur Jardin des Plantes : Show popup sur Yes avec son Message, encadrés, et la pop-up affichée au-dessus du marqueur sur la carte]

Il est également possible de créer des marqueurs dynamiquement [depuis une source de données](https://docs.pandasuite.com/fr/essentials/data/connect-your-app-to-a-data-source/).

Cette vidéo vous explique comment créer des marqueurs dynamiques sur une carte interactive :

[Vidéo : Tutoriel marqueurs dynamiques : créer des marqueurs sur une carte interactive depuis une source de données](https://www.youtube.com/embed/Q3KkP4RTAy4?si=v0DDcVFu8l6SqfiS)

### Créer des marqueurs dynamiques à partir d'une collection

Utilisez cette approche si vous souhaitez générer des marqueurs à partir de données structurées (par exemple une liste « Lieux ») et les garder faciles à mettre à jour.

1. Préparez vos données

   - Créez une [Collection](https://docs.pandasuite.com/fr/essentials/data/collection/) dans le [Datastore](https://docs.pandasuite.com/fr/essentials/data/datastore/).
   - Ajoutez des champs tels que : Titre (Texte), Position (Coordonnée), URL d'icône (Texte/Image), Description (Texte).

2. Ajoutez un marqueur à la Carte

   - Insérez le composant **Carte** et créez un seul marqueur.
   - Sélectionnez ce marqueur et activez la **Source dynamique**, puis liez-la à votre collection.

3. Liez les propriétés du marqueur
   - Ajoutez un data binding sur le **Centre** du marqueur et liez-le à votre champ Position (type Coordonnée).
   - Optionnel : liez d'autres propriétés, comme **Visible**, le texte de la pop-up (Titre/Description) et l'icône du marqueur (URL d'icône), aux champs de votre collection.

## Associer des actions aux marqueurs

Une fois que vos marqueurs sont créés, vous pouvez les utiliser pour déclencher une action.

Ouvrez la fenêtre **Actions** et sélectionnez un marqueur dans la liste. Associez l'action de votre choix (par exemple **Aller à un écran** ou **Ouvrir une pop-up**).

[Image : Déclencheurs de la Carte : un Simple tap / Clic par marqueur (L'Allée Verte, La Grosse Rochette) et Changement de la position de la carte]

Vous pouvez aussi utiliser l'action de marqueur **Focus** pour centrer la carte sur un marqueur spécifique.

## Contrôler la carte avec des actions

Utilisez les actions du composant Carte lorsqu'une autre interaction doit déplacer la carte :

- **Changer la position de la carte** modifie le centre et le niveau de zoom de la carte.
- **Ajuster les limites** ajuste la vue pour inclure tous les marqueurs visibles. Utilisez **Vertical padding** et **Horizontal padding** pour garder les marqueurs à distance des bords du composant.

Les marqueurs masqués sont ignorés par **Ajuster les limites**, car ils ne sont pas affichés sur la carte.

## Propriétés exposées

Le composant Carte expose les données suivantes pour le [data binding](https://docs.pandasuite.com/fr/essentials/data/data-binding/) :

- **Centre** : coordonnées actuelles du centre de la carte.
- **Zoom** : niveau de zoom actuel.

Utilisez le déclencheur **Changement de la position de la carte** lorsque vous devez réagir après un déplacement ou un zoom de la carte par l'utilisateur. Le déclencheur expose les nouvelles valeurs **Centre** et **Zoom** dans le flux d'action.

## Pour aller plus loin

- [Marqueurs](https://docs.pandasuite.com/fr/essentials/interactions/markers/)
- [Connecter une source de données](https://docs.pandasuite.com/fr/essentials/data/connect-your-app-to-a-data-source/)
- [Collection](https://docs.pandasuite.com/fr/essentials/data/collection/)
- [Data binding](https://docs.pandasuite.com/fr/essentials/data/data-binding/)
- [Actions interactives](https://docs.pandasuite.com/fr/essentials/interactions/interactive-actions/)
- [GPS / Géo-repérage](https://docs.pandasuite.com/fr/essentials/components/gps-geo-fencing/)
