Les modèles de correspondance sont un moyen de spécifier des groupes d'URL: un modèle de correspondance correspond à un ensemble spécifique d'URL. Ils sont destinés à des extensions à l'aide d'API WebExtensions dans quelques endroits, notamment pour spécifier les documents dans lesquels charger des content scripts,  et pour spécifier les URL à ajouter aux auditeurs webRequest.

Les API qui utilisent des modèles de correspondance acceptent généralement une liste de modèles de correspondance et effectueront les actions appropriées si l'URL correspond à l'un des motifs. Voir, par exemple, la clé content_scripts dans manifest.json.

Structure du modèle de correspondance

Tous les modèles de correspondance sont spécifiés comme des chaînes. Outre le motif spécial "<all_urls>", les modèles de correspondance se composent de trois parties : schéma, l'hôte, et le chemin d'accès. Le schéma et l'hôte sont séparés par "://".

<scheme>://<host><path>

schéma

Le composant du schéma peut prendre l'une des deux formes suivantes :

Form Matches
"*" Seulement "http" et "https".
Un des "http", "https", "file", "ftp", "app". Seulement le schéma donné.

hôte

Le composant hôte peut prendre l'une des trois formes suivantes :

Form Matches
"*" Tout hôte
"*." Suivi d'une partie du nom d'hôte L'hôte donné et l'un de ses sous-domaines
Un nom d'hôte complet, sans caractères génériques Seul l'hôte donné

hôte est facultatif seulement si le schéma est un "fichier".

Notez que le caractère générique ne peut apparaître qu'au début.

chemin

Le composant du chemin d'accès doit commencer par un "/".

Ensuite, il peut contenir éventuellement toute combinaison du caractère générique "*" et de l'un des caractères autorisés dans les chemins d'URL. Contrairement à l'hôte, le composant du chemin peut contenir le caractère générique "*" au milieu ou à la fin, et le caractère "*" peut apparaître plusieurs fois.

<all_urls>

La valeur spéciale "<all_urls>" correspond à toutes les URL sous l'un des schémas pris en charge: c'est-à-dire : "http", "https", "file", "ftp", "app".

Exemples

Modèle Exemple utilisations Exemple non supportés

<all_urls>

Match all URLs.

http://example.org/

ftp://files.somewhere.org/

https://a.org/some/path/

resource://a/b/c/
(unsupported scheme)

*://*.mozilla.org/*

Match all HTTP and HTTPS URLs that are hosted at "mozilla.org" or one of its subdomains.

http://mozilla.org/

https://mozilla.org/

http://a.mozilla.org/

http://a.b.mozilla.org/

https://b.mozilla.org/path/

ftp://mozilla.org/
(unmatched scheme)

http://mozilla.com/
(unmatched host)

http://firefox.org/
(unmatched host)

*://mozilla.org/

Match all HTTP and HTTPS URLs that are hosted at exactly "mozilla.org/".

http://mozilla.org/

https://mozilla.org/

ftp://mozilla.org/
(unmatched scheme)

http://a.mozilla.org/
(unmatched host)

http://mozilla.org/a
(unmatched path)

ftp://mozilla.org/

Match only "ftp://mozilla.org/".

ftp://mozilla.org

http://mozilla.org/
(unmatched scheme)

ftp://sub.mozilla.org/
(unmatched host)

ftp://mozilla.org/path
(unmatched path)

https://*/path

Match HTTPS URLs on any host, whose path is "path".

https://mozilla.org/path

https://a.mozilla.org/path

https://something.com/path

http://mozilla.org/path
(unmatched scheme)

https://mozilla.org/path/
(unmatched path)

https://mozilla.org/a
(unmatched path)

https://mozilla.org/
(unmatched path)

https://*/path/

Match HTTPS URLs on any host, whose path is "path/".

https://mozilla.org/path/

https://a.mozilla.org/path/

https://something.com/path/

http://mozilla.org/path/
(unmatched scheme)

https://mozilla.org/path
(unmatched path)

https://mozilla.org/a
(unmatched path)

https://mozilla.org/
(unmatched path)

https://mozilla.org/*

Match HTTPS URLs only at "mozilla.org", with any path.

https://mozilla.org/

https://mozilla.org/path

https://mozilla.org/another

https://mozilla.org/path/to/doc

http://mozilla.org/path
(unmatched scheme)

https://mozilla.com/path
(unmatched host)

https://mozilla.org/a/b/c/

Match only this URL.

https://mozilla.org/a/b/c/ Anything else.

https://mozilla.org/*/b/*/

Match HTTPS URLs hosted on "mozilla.org", whose path contains a component "b" somewhere in the middle.

https://mozilla.org/a/b/c/

https://mozilla.org/d/b/f/

https://mozilla.org/a/b/c/d/

https://mozilla.org/b/*/
(unmatched path)

https://mozilla.org/a/b/
(unmatched path)

file:///blah/*

Match any FILE URL whose path begins with "blah".

file:///blah/

file:///blah/bleh

file:///bleh/
(unmatched path)

Modèles de correspondance invalides

Invalid pattern Reason
resource://path/ Unsupported scheme.
https://mozilla.org No path.
https://mozilla.*.org/ "*" in host must be at the start.
https://*zilla.org/ "*" in host must by the only character or be followed by ".".
http*://mozilla.org/ "*" in scheme must be the only character.
file://* Empty path: this should be "file:///*".

Tests des modèles de correspondance

Lors de l'écriture des extensions, vous ne travaillez généralement pas directement avec les modèles de concordance : généralement vous passez une chaîne de motif de correspondance dans une API et l'API construit un modèle de correspondance et l'utilise pour tester les URLs. Toutefois, si vous essayez de déterminer le modèle de correspondance à utiliser ou le débogage d'un problème avec un, il peut être utile de créer et de tester des modèles de concordance directement. Cette section explique comment procéder.

Tout d'abord, ouvrez les paramètres de l'outil de développement et vérifiez le paramètre marqué "Activer le navigateur Chrome et les boîtes à outils de débogage de l'extension" :

Ensuite, ouvrez la "console du navigateur":

Cela vous donne une ligne de commande que vous pouvez utiliser pour exécuter les privilèges de JavaScript dans Firefox.

Parce que le code exécuté dans la Console du navigateur comporte des privilèges système, chaque fois que vous l'utilisez pour exécuter le code, vous devez comprendre exactement ce que le code fait. Cela inclut les exemples de code dans cet article.

Maintenant, collez ce code dans la ligne de commande et appuyez sur enter:

Cu.import("resource://gre/modules/MatchPattern.jsm");
Cu.import("resource://gre/modules/BrowserUtils.jsm");

Cela fait deux choses :

  • Importe "MatchPattern.jsm" : il s'agit du module système qui implémente les modèles de correspondance. Plus précisément, le module contient un constructeur pour les objets MatchPattern. Les objets MatchPattern  définissent une fonction appelée matches(), qui prend un URI et renvoie true ou false.
  • Importe "BrowserUtils.jsm" : cela inclut une fonction makeURI(), qui convertit une chaîne en un objet nsIURI. nsIURI est le type que matches() s'attends à recevoir.

Maintenant, vous pouvez construire des objets MatchPattern, construire des URI et vérifier si les URI correspondent :

var match = new MatchPattern("*://mozilla.org/");

var uri = BrowserUtils.makeURI("https://mozilla.org/");
match.matches(uri); //        < true

uri = BrowserUtils.makeURI("https://mozilla.org/path");
match.matches(uri); //        < false

Conversion des modèles de correspondance en expressions régulières

Tous les modèles de correspondance peuvent être représentés par des expressions régulières. Les expressions régulières peuvent être spécifiées lorsqu'une API WebExtension ou un fichier de configuration (par exemple manifest.json) nécessite un modèle de correspondance. Ce code convertit un motif de correspondance en une expression régulière :

/**
 * Transforms a valid match pattern into a regular expression
 * which matches all URLs included by that pattern.
 *
 * @param  {string}  pattern  The pattern to transform.
 * @return {RegExp}           The pattern's equivalent as a RegExp.
 * @throws {TypeError}        If the pattern is not a valid MatchPattern
 */

// matches all valid match patterns (except '<all_urls>')
// and extracts [ , scheme, host, path, ]
const matchPattern = (/^(?:(\*|http|https|file|ftp|app):\/\/(\*|(?:\*\.)?[^\/\*]+|)\/(.*))$/i);

function matchPatternToRegExp(pattern) {
  if (pattern === '<all_urls>') {
    return (/^(?:https?|file|ftp|app):\/\//);
  }
  const match = matchPattern.exec(pattern);
  if (!match) {
    throw new TypeError(`"${ pattern }" is not a valid MatchPattern`);
  }
  const [ , scheme, host, path, ] = match;
  return new RegExp('^(?:'
    + (scheme === '*' ? 'https?' : escape(scheme)) +':\/\/'
    + (host === '*' ? '[^\/]+?' : escape(host).replace(/^\\\*\\./g, '(?:[^\/]+?.)?'))
    + (path ? '\/'+ escape(path).replace(/\\\*/g, '.*') : '\/?')
  +')$');
}

Étiquettes et contributeurs liés au document

Étiquettes : 
 Contributeurs à cette page : hellosct1
 Dernière mise à jour par : hellosct1,