Aller au contenu principal

HTMLMapmlViewerElement

L’interface HTMLMapmlViewerElement représente l’élément <mapml-viewer>.

Propriétés​

Nom de la propriétéDescription
controlsActive ou désactive les contrôles natifs de la carte. Reproduit l’attribut controls.
controlsListPermet de changer l’ensemble des contrôles natifs. Reproduit l’attribut controlslist.
extentRetourne l’étendue de la carte affichée. En lecture seule.
latObtient ou définit la latitude de la carte. Reproduit dans l’attribut de contenu lat. Aucun effet sur l'état dynamique de la carte.
lonObtient ou définit la longitude de la carte. Reproduit dans l’attribut de contenu lon. Aucun effet sur l'état dynamique de la carte.
projectionProjection de la carte. Reproduit l’attribut projection.
zoomObtient ou définit le niveau de zoom de la carte. Reproduit dans l’attribut de contenu zoom. Aucun effet sur l'état dynamique de la carte.

controls​

Pour ajouter des contrôles à la carte :

let map = document.querySelector('mapml-viewer');
map.controls = true; // ou false pour supprimer des contrôles

Pour vérifier si les contrôles de la carte sont activés ou désactivés :

let map = document.querySelector('mapml-viewer');
let controlsAdded = map.controls;

controlsList​

La propriété controlsList renvoie une DOMTokenList qui aide l'utilisateur à sélectionner les contrôles à afficher sur l'élément mapml-viewer en fonction des valeurs possibles.

Pour définir l’attribut controlslist :

let map = document.querySelector('mapml-viewer');
map.controlsList.value = "noreload nozoom"; // les valeurs peuvent être noreload | nofullscreen | nozoom | nolayer
map.controlsList.add("nofullscreen"); // peut également être ajouté à l'aide de la méthode 'add'
map.controlsList.toggle("nolayer"); // peut également être basculé à l'aide de la méthode 'toggle.
// Voir toutes les méthodes ici - https://developer.mozilla.org/fr/docs/Web/API/DOMTokenList

Pour obtenir la valeur de controlslist :

let map = document.querySelector('mapml-viewer');
let controlsList = map.controlsList.value;

extent​

Lire seulement. Pour obtenir l’étendue de la carte :

let map = document.querySelector('mapml-viewer');
let extent = map.extent;
Afficher un exemple d’étendue
/**
*extent = 
*  {
*    {
*      "topLeft": {
*        "tcrs": [
*          {
*            "horizontal": 906.7586206896551,
*            "vertical": 981.7241379310345
*          },
*          ...
*        ],
*        "tilematrix": [
*          {
*            "horizontal": 3.5420258620689653,
*            "vertical": 3.8348599137931036
*          },
*          ...
*        ],
*        "gcrs": {
*          "horizontal": -93.05456518322721,
*          "vertical": 63.783997873304855
*        },
*        "pcrs": {
*          "horizontal": 131686.24163915217,
*          "vertical": 1646487.1729743406
*        }
*      },
*      "bottomRight": {
*        "tcrs": [
*          {
*            "horizontal": 914.9655172413793,
*            "vertical": 1015.5172413793102
*          },
*          ...
*        ],
*        "tilematrix": [
*          {
*            "horizontal": 3.574084051724138,
*            "vertical": 3.9668642241379306
*          },
*          ...
*        ],
*        "gcrs": {
*          "horizontal": -85.62509797700041,
*          "vertical": 52.14641630380798
*        },
*        "pcrs": {
*          "horizontal": 446541.0380154103,
*          "vertical": 350026.2467191592
*        }
*      },
*      "projection": "CBMTILE",
*      "zoom": {
*        "minZoom": 0,
*        "maxZoom": 25
*      }
*    }
*  }
*/

lat​

Pour définir la latitude : 

let map = document.querySelector('mapml-viewer');
map.lat = 21.4; // rien ne se produit si la valeur n’est pas valide

Notez que la valeur fournie n'affecte pas l'état de la visionneuse de carte, sauf au chargement du document, ou lorsqu'une instance d'un élément <mapml-viewer> est construite et ajoutée par programme au DOM. Pour modifier la valeur, utilisez zoomTo()

Pour obtenir la latitude :

let map = document.querySelector('mapml-viewer');
let latitude = map.lat;

lon​

Pour définir la longitude :

let map = document.querySelector('mapml-viewer');
map.lon = 21.4; // rien ne se produit si la valeur n’est pas valide

Notez que la valeur fournie n'affecte pas l'état de la visionneuse de carte, sauf au chargement du document, ou lorsqu'une instance d'un élément <mapml-viewer> est construite et ajoutée par programme au DOM. Pour modifier la valeur, utilisez zoomTo()

Pour obtenir la longitude :

let map = document.querySelector('mapml-viewer');
let longitude = map.lon;

projection​

Pour fixer ou modifier la projection:

let map = document.querySelector('mapml-viewer');
map.projection = "CBMTILE"; // rien ne se produit si la projection n’est pas valide ou définie

Pour obtenir la projection :

let map = document.querySelector('mapml-viewer');
let projection = map.projection;

zoom​

Pour définir le niveau de zoom :

let map = document.querySelector('mapml-viewer');
map.zoom = 3; // rien ne se produit si la valeur n’est pas valide

Notez que la valeur fournie n'affecte pas l'état de la visionneuse de carte, sauf au chargement du document, ou lorsqu'une instance d'un élément <mapml-viewer> est construite et ajoutée par programme au DOM. Pour modifier la valeur, utilisez zoomTo()

Pour obtenir la longitude :

let map = document.querySelector('mapml-viewer');
let zoom = map.zoom;

Méthodes​

MéthodeDescription
back()Revient à l’état précédent dans l’historique des mouvements de la carte.
forward()Passe au mouvement panoramique suivant dans l’historique de la carte.
reload()Efface l’historique des mouvements panoramiques de la carte et retourne à l’emplacement de départ.
toggleDebug()Active ou désactive le débogage de la carte.
viewSource()Affiche la source de la carte.
defineCustomProjection(options)Définir une projection personnalisée à utiliser par la page.
zoomTo(lat, lon, zoom)Survole la carte ou effectue un mouvement panoramique vers un (nouvel) emplacement et à un autre niveau de zoom.
geojson2mapml(json, options)Convertit une caractéristique GeoJSON ou une chaîne ou un objet de collection de caractéristiques en élément MapML <layer-> contenant un ou plusieurs éléments <map-feature>.

back()​

Pour reculer dans l’historique de la carte :

let map = document.querySelector('mapml-viewer');
map.back();

forward()​

Pour avancer dans l’historique de la carte :

let map = document.querySelector('mapml-viewer');
map.forward();

reload()​

Pour effacer l’historique de la carte et retourner à l’emplacement initial :

let map = document.querySelector('mapml-viewer');
map.reload();

toggleDebug()​

Pour activer ou désactiver le débogage de la carte :

let map = document.querySelector('mapml-viewer');
map.toggleDebug();

viewSource()​

Pour afficher la source de la carte affichée :

let map = document.querySelector('mapml-viewer');
map.viewSource();

defineCustomProjection(options)​

MapML définit quelques projections CRS (Système de référence des coordonnées) intégrées en pavés, dont la projection Web Mercator (OSMTILE), la projection pseudo-plate carrée (WGS84) et la grille de pavés de base du Canada (CBMTILE).

L’élément personnalisé <mapml-viewer> fournit l’interface de programmation d’applications (API) personnalisée des projections, qui vous permet de créer vos propres projections et de les utiliser dans l’élément <mapml-viewer>, défini avec la syntaxe "proj4" étendue du langage JSON et prise en charge par la bibliothèque proj4js.

Nous n’examinerons pas l’élément <mapml-viewer> lui-même ici, sauf pour dire que l’attribut projection de la carte doit avoir la même valeur que le membre projection de l’objet JSON que vous transmettez à la méthode defineCustomProjection de l’API personnalisée des projections, et que chaque élément <layer-> présent dans la carte doit comporter une déclaration et être programmé dans ce système de coordonnées pour s’afficher correctement.

L’API personnalisée des projections est fournie par l’élément <mapml-viewer>. Dans un navigateur, elle peut être définie sur l’objet de fenêtre. Toutefois, parce que des éléments personnalisés utilisent des modules ES6, il est pratique de la placer sur l’élément de mappage qui l’utilise.

Pour que l’appel de la méthode defineCustomProjection réussisse, vous devez coder la méthode de projection et les paramètres de projection sous la forme de membres d’une chaîne JSON. La marche à suivre pour ce faire n’est pas toujours simple, mais diverses ressources peuvent vous faciliter la vie, comme https://spatialreference.org où vous pouvez obtenir la version proj4 de pratiquement n’importe quelle définition SRC.

N’oubliez pas de mettre le nom du membre entre guillemets, suivi d’un deux-points. Par exemple, "projection": "NOM_DE_MA_PROJECTION". Les valeurs comportant une chaîne sont également insérées dans des guillemets, et les nombres et tableaux suivent la [syntaxe JSON] normale (https://developer.mozilla.org/fr/docs/Learn/JavaScript/Objects/JSON).

La définition d’une projection personnalisée requiert plusieurs membres.

  • projection - Nom (chaîne de caractères) donné à votre projection. Nous recommandons d’utiliser uniquement des majuscules pour mettre en évidence le nom des projections. Vous ne pouvez pas mettre un deux-points (":") dans le nom, car ceci créerait une confusion avec celui des listes de codes URI EPSG: ou ogc:. En effet, nous définissons ici une projection CRS qui comporte des paramètres propres au mappage en ligne, dont nous parlerons plus loin.
  • proj4string - Cette chaîne étant traitée par proj4js, il faut fournir les paramètres d’une méthode de projection prise en charge par cette bibliothèque et dans un format compatible avec celle-ci.
  • origin - Tableau à deux nombres qui représentent l’origine de la grille de pavés en coordonnées du système de coordonnées projetées, dont les unités sont habituellement des mètres. L’origine se trouve toujours dans le coin supérieur gauche de la grille de pavés, et les numéros de colonnes et de rangées augmentent de façon séquentielle, respectivement vers la droite et vers le bas, comme le prévoit la norme du service Web des pavés cartographiques (SWPC).
  • resolutions - Tableau de nombres, triés selon leur taille en mètres en ordre décroissant, des dimensions « réelles » d’un pixel carré. La résolution est calculée sur la base d’une taille de pixel nominale établie à 0,28 mm, telle que définie par la norme SWPC. PRENEZ NOTE QUE LES SERVICES DE PAVÉS DE L’ENVIRONMENTAL SYSTEMS RESEARCH INSTITUTE (ESRI) NE SE SERVENT HABITUELLEMENT PAS DE CETTE VALEUR PARCE QU’ILS UTILISENT UNE TAILLE NOMINALE DE 96 POINTS PAR POUCES (PPP) (réglable). Puisque l’échelle varie dans l’étendue de tout système de coordonnées projetées, la résolution en pixels n’est habituellement valide que là où les dimensions sont limitées, par exemple le long de l’équateur dans la projection Web Mercator. Les endroits où la résolution en pixels est valide changent en fonction de la méthode et des paramètres de la projection. Si vous voulez utiliser votre projection personnalisée avec un service de pavés existants, l’ensemble de résolutions doit correspondre à celui des pavés dans un cache.
  • bounds - Tableau composé de deux tableaux de paires de coordonnées, qui définit une zone de délimitation autour d’une partie du système de référence des coordonnées projetées, habituellement en mètres. Les requêtes doivent être valides, la latitude et la longitude étant définies à l’intérieur de ces limites. Les requêtes visant des cartes, des pavés et des transformations de coordonnées qui dépassent ces limites ne seront pas exécutées pour éliminer le trafic redondant et les erreurs.
  • tilesize - Les pavés sont toujours carrés et ont habituellement 256 pixels d’arête, mais vous pouvez ajuster cette dimension par un nombre entier. Les nombres 256, 512, 1024, 2048 ou 4096 devraient tous fonctionner.

zoomTo(lat, lon, zoom)​

Pour déplacer le centre de la carte et modifier le niveau de zoom :

var options = {
  enableHighAccuracy: true,
  timeout: 5000,
  maximumAge: 0
};

function success(pos) {
  var crd = pos.coords;

  let map = document.querySelector('mapml-viewer');
  map.zoomTo(crd.latitude,crd.longitude, 17); // zoom codé en dur
  // peut calculer le niveau de zoom en fonction du degré de précision de la position
  console.log(`Plus ou moins ${crd.accuracy} mètres.`);
}

function error(err) {
  console.warn(`ERROR(${err.code}): ${err.message}`);
}

navigator.geolocation.getCurrentPosition(success, error, options);

geojson2mapml(json, options)​

Convertit une caractéristique GeoJSON ou une chaîne ou un objet de collection de caractéristiques en élément MapML <layer-> contenant un ou plusieurs éléments <map-feature>.

astuce

Jetez un coup d’œil à cette application au moyen de l’API geojson2mapml!

Paramètres​

ParamètreDescription
<String | Object> jsonChaîne ou objet GeoJSON
Options <Object>Ensemble de paires de clés ou de valeurs qui personnalise la couche de sortie MapML. Toutes les options sont facultatives et décrites ci-après.

Options​

<Object> Ensemble de paires de clés ou de valeurs qui personnalise la couche de sortie MapML. Toutes les options sont facultatives et décrites ci-après.

OptionTypeDefaultDescription
label<String>json.name, json.title ou "Layer"Définit la label de la couche de sortie.
projection<String>OSMTILEDéfinit la projection de la couche de sortie. Les valeurs définies incluent : OSMTILE, CBMTILE, WGS84, and APSTILE.
caption<String | Function>Utilise la valeur labelFonction qui accepte la caractéristique JSON et retourne une chaîne, OU une chaîne qui est le nom d’une propriété à mapper sur featurecaption. Si aucune propriété associée n’est trouvée, la chaîne fournie sert de valeur de la légende de la caractéristique. Voir la section Utilisation des options de base pour un exemple.
properties<Function | String | HTMLElement>Les propriétés seront mappées à un table HTML.Précise la façon dont les propriétés sont mappées. <Function> - Fonction qui accepte un argument – l’objet GeoJSON feature – et qui doit retourner un HTMLElement qui devient l’unique élément-enfant de <properties>. <String> - Chaîne qui sera analysée syntaxiquement et utilisée comme unique élément-enfant de <properties> avec toutes les caractéristiques. <HTMLElement> - Élément qui servira d’unique élément- enfant de <properties> avec toutes les caractéristiques. Voir la section utilisation des options de base pour un exemple.
geometryFunction<Function>La géométrie MapML reproduit la valeur géométrique GeoJSON<Function> Fonction pour modifier les descendants générés de <map-geometry> qui peut ajouter des classes, hyperlinks et des spans à l’instance. Un élément <map-geometry> simple est créé par défaut. La fonction accepte deux arguments : l’élément-enfant généré de <map-geometry> et l’objet de la caractéristique JSON pour retourner un élément-enfant modifié de <map-geometry>. Voir la section Utilisation des options de base pour un exemple.

Événements​

Nom de l’événementDescription
layerchangeDéclenché lorsqu’une couche change de src, habituellement lorsque l’utilisateur clique sur un lien.
loadDéclenché après que le contenu de toutes les couches a été chargé
clickDéclenché lorsque la carte reçoit les événements mousedown et mouseup
dblclickDéclenché lorsque l’utilisateur double-clique sur la carte ou touche celle-ci
mousemoveDéclenché à répétition lorsque le pointeur de la souris est déplacé sur la carte
mouseoverDéclenché une fois lorsque le pointeur de la souris est placé sur la carte
mouseoutDéclenché une fois lorsque le pointeur de la souris sort de la carte
mousedownDéclenché lorsque l’utilisateur appuie sur le bouton principal de la souris alors que le pointeur de la souris se trouve sur la carte
mouseupDéclenché lorsque l’utilisateur relâche le bouton principal de la souris alors que le pointeur de la souris se trouve sur la carte
movestartDéclenché avant que la carte commence à bouger ou que la fenêtre d’affichage change
moveDéclenché à répétition lorsque la carte bouge
moveendDéclenché lorsque la carte ne bouge plus
zoomstartDéclenché avant que le niveau de zoom de la carte change
zoomDéclenché à répétition lorsque le niveau de zoom de la carte change
zoomendDéclenché après que le niveau de zoom de la carte a changé
preclickDéclenché avant que l’utilisateur clique sur la carte
contextmenuDéclenché lorsque l’utilisateur fait un clic droit sur la carte ou touche celle-ci

Exemples​

geojson2mapml​

Utilisation des options de base​

Utilisation de chaque option en contexte

option d’étiquette geojson2mapml
geojson2mapml(json, {label: "Centre-ville d’Ottawa"});

Chaîne d’options​

Exemple montrant comment utiliser des chaînes pour définir les options label, projection, caption et properties.

let map = document.querySelector('mapml-viewer');
let json = {
    "name": "Nom par défaut",
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [-75.6916809,45.4186964]
    },
    "properties": {"desc": "Ceci est un point"}
};

// GeoJSON à MapML
let output = map.geojson2mapml(json, {label: "Exemple 1", projection: "CBMTILE", caption: "desc", properties: "<h3>Ceci est un en-tête de propriété</h3>"});
Cliquez pour afficher la sortie HTMLElement
<layer- label="Example 1" checked="">
   <map-meta name="projection" content="CBMTILE"></map-meta>
   <map-meta name="cs" content="gcrs"></map-meta>
   <map-feature>
      <map-featurecaption>Ceci est un point</map-featurecaption>
      <map-geometry>
         <map-point>
            <map-coordinates>-75.6916809 45.4186964</map-coordinates>
         </map-point>
      </map-geometry>
      <map-properties>
         <h3>Ceci est un en-tête de propriété</h3>
      </map-properties>
   </map-feature>
</layer->

Fonction d’options​

Exemple montrant comment les fonctions peuvent servir à définir les options caption et properties.

let map = document.querySelector('mapml-viewer');
let json = {
    "name": "Nom par défaut",
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [-75.6916809,45.4186964]
    },
    "properties": {"desc": "Ceci est un point"}
};

// function to set caption
let cap = function c(j) {
  let str = "Ce point se trouve à : (" + j.geometry.coordinates[0] + ", " + j.geometry.coordinates[1] + ").";
  return str;
}

// fonction pour définir des propriétés
let prop = function f(p) {
  let parser = new DOMParser();
  return parser.parseFromString("<h1>" + p.properties.desc + "'s property</h1>", "text/html").body.firstChild;
}

// GeoJSON à MapML
let output = map.geojson2mapml(json, {label: "Exemple 2", caption: cap, properties: prop});
Cliquez pour afficher la sortie HTMLElement
<layer- label="Example 2" checked="">
   <map-meta name="projection" content="OSMTILE"></map-meta>
   <map-meta name="cs" content="gcrs"></map-meta>
   <map-feature>
      <map-featurecaption>Ce point se trouve à : (-75.6916809, 45.4186964).</map-featurecaption>
      <map-geometry>
         <map-point>
            <map-coordinates>-75.6916809 45.4186964</map-coordinates>
         </map-point>
      </map-geometry>
      <map-properties>
         <h1>Ceci est une propriété du point</h1>
      </map-properties>
   </map-feature>
</layer->

Options par défaut​

Exemple montrant la sortie par défaut lorsqu’aucune option n’est fournie.

let map = document.querySelector('mapml-viewer');
let json = {
 "title": "Géométrie du point",
 "bbox": [-75.916809, 45.886964, -75.516809, 45.26964],
 "type": "FeatureCollection",
 "features": [{
     "type": "Feature",
     "geometry": {
         "type": "Point",
         "coordinates": [-75.6916809, 45.4186964]
     },
     "properties": {
         "prop0": "Ceci est un point"
     }
 }]
};

// GeoJSON à MapML
let output = map.geojson2mapml(json);
Cliquez pour afficher la sortie HTMLElement
<layer- label="Géométrie du point" checked="">
   <map-meta name="extent" content="top-left-longitude=-75.916809, top-left-latitude=45.886964, bottom-right-longitude=-75.516809,bottom-right-latitude=45.26964"></map-meta>
   <map-meta name="projection" content="OSMTILE"></map-meta>
   <map-meta name="cs" content="gcrs"></map-meta>
   <map-feature>
      <map-featurecaption>Géométrie du point</map-featurecaption>
      <map-geometry>
         <map-point>
            <map-coordinates>-75.6916809 45.4186964</map-coordinates>
         </map-point>
      </map-geometry>
      <map-properties>
         <table>
            <thead>
               <tr>
                  <th role="columnheader" scope="col">Property name</th>
                  <th role="columnheader" scope="col">Property value</th>
               </tr>
            </thead>
            <tbody>
               <tr>
                  <th scope="row">prop0</th>
                  <td itemprop="prop0">This is a Point</td>
               </tr>
            </tbody>
         </table>
      </map-properties>
   </map-feature>
</layer->

defineCustomProjection​

Basic options usage​

<!doctype html>
<html lang="fr">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Exemple d'un projection personnalisée</title>
  <script type="module" src="web-map/mapml-viewer.js"></script>
  <script type="module">
    let customProjectionDefinition = `{
      "projection": "ATLAS_POLAR_MAP",
      "proj4string" : "+proj=aeqd +lat_0=90 +lon_0=-90 +x_0=0 +y_0=0 +ellps=sphere +units=m +no_defs +type=crs",
      "origin" : [-20015200,20015200],
      "resolutions" :  [33073,16536.5,8268.246,4134.123,2067.061,1033.531,516.765],
      "bounds" : [[4979939,-4846977],[-5139071,3980038]],
      "tilesize" : 256
      }`;
    let map = document.querySelector("mapml-viewer");
    let cProjection = map.defineCustomProjection(customProjectionDefinition);    
    map.projection = cProjection;
  </script>
</head>
<body>
  <mapml-viewer projection="ATLAS_POLAR_MAP" zoom="2" lat="83.48919" lon="-87.7687" controls>
    <layer- label="Carte polaire murale de l’Atlas du Canada" checked>
    <map-link rel="license" title="Plateforme géospatiale fédérale canadienne" href="https://geoappext.nrcan.gc.ca/arcgis/rest/services/FGP/NCR_RCN/MapServer/"></map-link>
      <map-extent units="ATLAS_POLAR_MAP" checked hidden>
        <map-input type="zoom" name="z" min="0" max="6" value="6" ></map-input>
        <map-input type="location" name="x" axis="column" units="tilematrix" min="116" max="186"></map-input>
        <map-input type="location" name="y" axis="row" units="tilematrix" min="125" max="184"></map-input>
        <map-link rel="tile" tref="https://geoappext.nrcan.gc.ca/arcgis/rest/services/FGP/NCR_RCN/MapServer/tile/{z}/{y}/{x}/"></map-link>
        <map-link rel="tile" tref="https://geoappext.nrcan.gc.ca/arcgis/rest/services/FGP/NCR_RCN_A/MapServer/tile/{z}/{y}/{x}/"></map-link>
      </map-extent>
    </layer->
  </mapml-viewer>
</body>
</html>

Spécifications​

Spécification
HTMLMapmlViewerElement

Exigences​

Signaler les problèmes liés à ces exigences sur GitHub

exigenceaméliorationpeu pratiqueindécisen cours de discussion

Spéc.VisualiseurAPI
Propriétéscompletcompletcomplet
Méthodeslimité *completlimité *
Exceptions *
  1. Aucune spécification ne sera fournie pour les méthodes toggleDebug() ou viewSource().
  2. La méthode defineCustomProjection est implémentée, mais n'est pas encore spécifiée
  3. L'API des projections personnalisées (defineCustomProjection) est en cours de discussion, en particulier le format du paramètre options
  4. La spécification du paramètre options de la méthode geojson2mapml n'est pas définitive.