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

Note: Certains navigateurs ne prennent pas en charge certains schémas.
Consultez le tableau de compatibilité du navigateur pour plus de détails.

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" and in some browsers also "ws" et "wss".
Un des "http", "https", "ws", "wss", "ftp", "ftps" or "file". 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é

L'hôte ne doit pas inclure un numéro de port.

L'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", "ws", "wss", "ftp" and "file".

Exemples

Pattern Example matches Example non-matches

<all_urls>

Match all URLs.

http://example.org/

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

ws://sockets.somewhere.org/

wss://ws.example.com/stuff/

ftp://files.somewhere.org/

ftps://files.somewhere.org/

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

*://*/*

Match all HTTP, HTTPS and WebSocket URLs.

http://example.org/

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

ws://sockets.somewhere.org/

wss://ws.example.com/stuff/

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

ftps://ftp.example.org/
(unmatched scheme)

file:///a/
(unmatched scheme)

*://*.mozilla.org/*

Match all HTTP, HTTPS and WebSocket 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/

ws://ws.mozilla.org/

wss://secure.mozilla.org/something

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

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

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

*://mozilla.org/

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

http://mozilla.org/

https://mozilla.org/

ws://mozilla.org/

wss://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 be the only character or be followed by ".".
http*://mozilla.org/ "*" in scheme must be the only character.
https://mozilla.org:80/ Host must not include a port number.
*://* Empty path: this should be "*://*/*".
file://* Empty path: this should be "file:///*".

Compatibilité du navigateur

schéma

ChromeEdgeFirefoxFirefox for AndroidOpera
Wildcard * scheme Oui144848 Oui
* matches ws and wss Non ?5555 Non
http Oui144848 Oui
https Oui144848 Oui
ws Non ?5555 Non
wss Non ?5555 Non
ftp Oui144848 Oui
ftps Non Non Non1 Non1 Non
file Oui144848 Oui
data Non ?482482 Non

1. See bug 1463440

2. Doesn’t support injection of content scripts or stylesheets.

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
 */
function matchPatternToRegExp(pattern) {
    if (pattern === '') {
        return (/^(?:http|https|file|ftp|app):\/\//);
    }

    const schemeSegment = '(\\*|http|https|ws|wss|file|ftp)';
    const hostSegment = '(\\*|(?:\\*\\.)?(?:[^/*]+))?';
    const pathSegment = '(.*)';
    const matchPatternRegExp = new RegExp(
        `^${schemeSegment}://${hostSegment}/${pathSegment}$`
    );

    let match = matchPatternRegExp.exec(pattern);
    if (!match) {
         throw new TypeError(`"${pattern}" is not a valid MatchPattern`);
    }

    let [, scheme, host, path] = match;
    if (!host) {
        throw new TypeError(`"${pattern}" does not have a valid host`);
    }

    let regex = '^';

    if (scheme === '*') {
        regex += '(http|https)';
    } else {
        regex += scheme;
    }

    regex += '://';

    if (host && host === '*') {
        regex += '[^/]+?';
    } else if (host) {
        if (host.match(/^\*\./)) {
            regex += '[^/]*?';
            host = host.substring(2);
        }
        regex += host.replace(/\./g, '\\.');
    }

    if (path) {
        if (path === '*') {
            regex += '(/.*)?';
        } else if (path.charAt(0) !== '/') {
            regex += '/';
            regex += path.replace(/\./g, '\\.').replace(/\*/g, '.*?');
            regex += '/?';
        }
    }

    regex += '$';
    return new RegExp(regex);
}

Étiquettes et contributeurs liés au document

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