Extension Chrome - implémentation d'une extension

Dans l'article précédent, je vous ai montré comment configurer un projet d'extension Chromium, afin qu'il prenne en charge TypeScript, la saisie semi-automatique dans la mesure du possible et fonctionne bien comme point de départ. Maintenant, je vais brièvement montrer l'implémentation de ma simple extension Page Audio.

Introduction

Idée

Ce que je voulais de mon extension était très simple : lorsque je vais sur un site Web spécifique, il devrait commencer à lire un audio prédéfini. Le nom et l’audio du site Web codés en dur conviennent parfaitement.

De manière un peu plus détaillée, la lecture audio devrait commencer lorsque j'ouvre www.example.com, s'arrêter lorsque je passe à un autre onglet et reprendre lorsque je reviens sur www.example.com. De plus, si j'ai deux (ou plus) onglets avec www.example.com ouvert et que je bascule entre eux, l'audio devrait continuer à jouer sans redémarrer. En d'autres termes, l'audio doit être lu sur l'ensemble du niveau de l'extension, et non sur des onglets individuels.

Approche technique générale

En bref, nous devons créer HTMLAudioElement quelque part et le lire/mettre en pause en fonction du site Web dans l'onglet actuel.

C'est faisable avec un service Worker et des scripts de contenu - nous pourrions avoir un script de contenu créant un élément HTMLAudioElement sur chaque page et utiliser un Service Worker pour coordonner la lecture. Lorsque l'onglet perd le focus, il transmet la période multimédia actuelle au service worker et lorsqu'un autre onglet avec une URL correspondante obtient le focus, il demande au service worker la période et reprend la lecture à partir de là.

Cependant, je pense que cette approche est un peu alambiquée et pourrait être sujette à des erreurs. Ce serait beaucoup plus agréable si nous pouvions n'avoir qu'un seul élément HTMLAudioElement et le lire/mettre en pause globalement, et non à partir d'onglets individuels. Heureusement, il existe une API intéressante qui nous aidera grandement : l'API hors écran.

L'API hors écran permet à l'extension de créer un document HTML invisible. En l'utilisant, nous aurons un endroit pour conserver notre HTMLAudioElement et simplement le lire/mettre en pause en cas de besoin. Gardez à l'esprit que le service Worker ne peut toujours pas effectuer d'opérations DOM, nous aurons donc besoin d'un script d'assistance sur notre document hors écran pour recevoir les messages du Service Worker et contrôler correctement le lecteur.

Mise en œuvre

Autorisations nécessaires dans manifest.json

Mon extension a besoin de deux entrées dans le tableau des autorisations :

• onglets - il doit savoir quand l'utilisateur change et/ou met à jour les onglets
• hors écran - il doit pouvoir créer un document hors écran pour lire l'audio à partir de là

Si vous ouvrez les détails de l'extension dans le navigateur, vous verrez les autorisations décrites comme :

Lisez votre historique de navigation

Cela peut paraître un peu effrayant, mais c'est ce que provoque l'ajout d'autorisations d'onglets. Malheureusement, je n'ai pas pu trouver une approche différente avec des autorisations moins préoccupantes. Les autres idées que j'avais aboutissaient à des ensembles d'autorisations encore plus effrayants ? Dans ce fil de discussion, vous pouvez lire pourquoi l'autorisation des onglets provoque cette entrée.

Gestion des documents hors écran

Comme je l'ai mentionné, j'aimerais n'avoir qu'un seul HTMLAudioElement et en lire l'audio. Pour le rendre indépendant des onglets, j'utiliserai l'API hors écran pour créer un document où il sera conservé et contrôlé par les messages du service worker.

J'ai envie de programmation orientée objet, alors voici la classe OffscreenDoc qui m'aide à la gestion de documents hors écran. Essentiellement, il crée simplement le document hors écran s'il n'est pas encore créé.

// ts/offscreen-doc.ts
/**
 * Static class to manage the offscreen document
 */
export class OffscreenDoc {
    private static isCreating: Promise<boolean | void> | null;
    private constructor() {
        // private constructor to prevent instantiation
    }

    /**
     * Sets up the offscreen document if it doesn't exist
     * @param path - path to the offscreen document
     */
    static async setup(path: string) {
        if (!(await this.isDocumentCreated(path))) {
            await this.createOffscreenDocument(path);
        }
    }

    private static async createOffscreenDocument(path: string) {
        if (OffscreenDoc.isCreating) {
            await OffscreenDoc.isCreating;
        } else {
            OffscreenDoc.isCreating = chrome.offscreen.createDocument({
                url: path,
                reasons: ['AUDIO_PLAYBACK'],
                justification:
                    'Used to play audio independently from the opened tabs',
            });
            await OffscreenDoc.isCreating;
            OffscreenDoc.isCreating = null;
        }
    }

    private static async isDocumentCreated(path: string) {
        // Check all windows controlled by the service worker to see if one
        // of them is the offscreen document with the given path
        const offscreenUrl = chrome.runtime.getURL(path);
        const existingContexts = await chrome.runtime.getContexts({
            contextTypes: ['OFFSCREEN_DOCUMENT'],
            documentUrls: [offscreenUrl],
        });
        return existingContexts.length > 0;
    }
}

Comme vous pouvez le voir, la seule méthode publique est setup et elle nécessite un chemin lorsqu'elle est appelée. C'est un chemin vers un modèle de document HTML qui sera utilisé pour créer notre document hors écran. Ça va être super simple dans notre cas :

<!-- offscreen.html -->
<script src="dist/offscreen.js" type="module"></script>

Littéralement, une seule balise de script. Ce script sera utilisé pour recevoir les messages du service worker, créer HTMLAudioElement et lire/mettre en pause la musique. Il a également type="module" car j'y importerai quelque chose.

Mais pour recevoir des messages, nous devrions probablement les envoyer en premier.

Interface des messages

Il n'y a pas d'interface stricte pour les messages. Nous devons juste nous assurer qu'ils sont sérialisables en JSON. Cependant, j'aimerais être aussi sûr que possible, j'ai donc défini une interface simple pour les messages transmis dans mon extension :

// ts/audio-message.ts
export interface AudioMessage {
    /**
     * Command to be executed on the audio element.
     */
    command: 'play' | 'pause';
    /**
     * Source of the audio file.
     */
    source?: string;
}

Vous verrez dans un instant que la méthode sendMessage n'est pas très adaptée à la saisie, mais il existe une solution de contournement simple pour toujours bénéficier de la sécurité de frappe.

Envoi de messages du service worker

Le service worker est le « cerveau » de notre extension, sait ce qui se passe et quand, et doit envoyer les messages appropriés si nécessaire. Mais c'est quand exactement ?

Nous devons modifier l'état de lecture dans trois situations :

• Lorsqu'un nouvel onglet est activé, l'utilisateur passe simplement de l'onglet A à l'onglet B,
• lorsque l'onglet actuel est mis à jour, donc son URL a changé, ou
• quand un onglet est fermé - c'est un cas un peu délicat, car cela peut se produire sans invoquer aucun des deux cas ci-dessus lorsque l'utilisateur ferme la dernière fenêtre de navigation privée pendant la lecture audio.

Toutes les situations signifient que nous pouvons être sur le site Web sur lequel nous voulons que l'audio soit lu ou que nous venons de le fermer/quitter.

Sans plus tard, voici le script ts/background.ts mis à jour réagissant aux deux événements :

// ts/offscreen-doc.ts
/**
 * Static class to manage the offscreen document
 */
export class OffscreenDoc {
    private static isCreating: Promise<boolean | void> | null;
    private constructor() {
        // private constructor to prevent instantiation
    }

    /**
     * Sets up the offscreen document if it doesn't exist
     * @param path - path to the offscreen document
     */
    static async setup(path: string) {
        if (!(await this.isDocumentCreated(path))) {
            await this.createOffscreenDocument(path);
        }
    }

    private static async createOffscreenDocument(path: string) {
        if (OffscreenDoc.isCreating) {
            await OffscreenDoc.isCreating;
        } else {
            OffscreenDoc.isCreating = chrome.offscreen.createDocument({
                url: path,
                reasons: ['AUDIO_PLAYBACK'],
                justification:
                    'Used to play audio independently from the opened tabs',
            });
            await OffscreenDoc.isCreating;
            OffscreenDoc.isCreating = null;
        }
    }

    private static async isDocumentCreated(path: string) {
        // Check all windows controlled by the service worker to see if one
        // of them is the offscreen document with the given path
        const offscreenUrl = chrome.runtime.getURL(path);
        const existingContexts = await chrome.runtime.getContexts({
            contextTypes: ['OFFSCREEN_DOCUMENT'],
            documentUrls: [offscreenUrl],
        });
        return existingContexts.length > 0;
    }
}

Comme vous pouvez le constater, la fonction toggleAudio est ici la plus importante. Tout d'abord, il configure le document hors écran. Vous pouvez l'appeler plusieurs fois en toute sécurité, car cela ne fait rien si le document est déjà créé. Ensuite, il décide s'il doit envoyer la commande "play" ou "pause", en fonction de l'URL de l'onglet actuel. Enfin, il envoie le message. Comme je l'ai mentionné, sendMessage n'a pas de variante générique (sendMessage), il n'est donc pas trivial de spécifier le type de message, mais TS satisfait aide à s'assurer que l'objet que nous envoyons est de type AudioMessage.

Remarquez également les deux constantes en haut - vous spécifiez ici quel audio vous souhaitez lire et sur quel site Web.

Réception des messages par document hors écran

Enfin, nous envoyons les messages, alors maintenant il est temps de les recevoir et de mettre de la musique ?

Pour ce faire, nous devons implémenter le script utilisé par offscreen.html. C'est dist/offscreen.js, voici donc à quoi ressemble ts/offscreen.ts correspondant :

<!-- offscreen.html -->
<script src="dist/offscreen.js" type="module"></script>

En bref, si nous n'avons pas créé HTMLAudioElement, nous le faisons en utilisant la source fournie, puis nous le lisons/le mettons en pause. Le retour d'undefined est nécessaire à des fins de saisie. Si vous êtes intéressé par la signification des différentes valeurs de retour, consultez la documentation

Résumé

Essayez-le ! Accédez à www.example.com (ou à tout autre site Web que vous avez défini) et voyez si l'audio est en cours de lecture. Essayez de changer d'onglet d'avant en arrière et vérifiez s'il s'arrête et reprend correctement.

N'oubliez pas que si vous mettez la musique en pause pendant plus de 30 secondes, elle sera redémarrée, car le service worker sera arrêté par le navigateur !Voici quelques documents à ce sujet.

Pour résumer ce que nous avons fait :

• nous avons mis à jour notre manifest.json avec les autorisations requises pour créer un document hors écran et surveiller l'activité sur les onglets
• nous avons demandé au technicien de service d'observer l'activité sur les onglets et d'envoyer des commandes adéquates au script vivant dans le document hors écran
• nous avons commencé la lecture audio via un script qui reçoit les messages du service worker et contrôle le DOM du document hors écran

J'espère que c'était clair et facile à suivre ! Il y a une progression assez naturelle de cette extension : permettre à l'utilisateur de spécifier différents sites Web et d'attribuer un son différent à chacun d'eux. J'espère que j'ajouterai cela quand j'aurai un peu de temps et que j'écrirai un autre article décrivant mon approche.

Pour l'instant, merci d'avoir lu !

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!