Chrome-Erweiterung – Implementierung einer Erweiterung

Im vorherigen Beitrag habe ich Ihnen gezeigt, wie Sie ein Chromium-Erweiterungsprojekt einrichten, damit es TypeScript und Autovervollständigung unterstützt, wo immer möglich, und einfach als Einstieg gut funktioniert. Jetzt zeige ich kurz die Implementierung meiner einfachen Page Audio-Erweiterung.

Einführung

Idee

Was ich von meiner Erweiterung wollte, war sehr einfach: Wenn ich eine bestimmte Website aufrufe, sollte sie mit der Wiedergabe vordefinierter Audiodaten beginnen. Hartcodierter Website-Name und Audio sind völlig in Ordnung.

Genauer gesagt: Die Audiowiedergabe sollte beginnen, wenn ich www.example.com öffne, stoppen, wenn ich zu einem anderen Tab wechsle, und fortfahren, wenn ich zu www.example.com zurückkehre. Wenn ich außerdem zwei (oder mehr) Tabs mit www.example.com geöffnet habe und zwischen ihnen wechsle, sollte die Audiowiedergabe ohne Neustart fortgesetzt werden. Mit anderen Worten: Audio sollte auf der gesamten Erweiterungsebene abgespielt werden, nicht auf einzelnen Registerkarten.

Allgemeiner technischer Ansatz

Kurz gesagt, wir müssen irgendwo HTMLAudioElement erstellen und es je nach Website im aktuellen Tab abspielen/anhalten.

Das ist mit Service-Worker- und Inhaltsskripten machbar – wir könnten ein Inhaltsskript haben, das auf jeder Seite ein HTMLAudioElement-Element erstellt, und einen Service-Worker verwenden, um die Wiedergabe zu koordinieren. Wenn der Tab den Fokus verliert, übergibt er den aktuellen Medienzeitrahmen an den Servicemitarbeiter. Wenn ein anderer Tab mit einer passenden URL den Fokus erhält, fragt er den Servicemitarbeiter nach dem Zeitrahmen und setzt die Wiedergabe von dort aus fort.

Ich denke jedoch, dass dieser Ansatz etwas kompliziert ist und möglicherweise fehleranfällig ist. Es wäre viel schöner, wenn wir nur ein HTMLAudioElement-Element hätten und es global abspielen/anhalten könnten, nicht über einzelne Registerkarten. Glücklicherweise gibt es eine interessante API, die uns sehr helfen wird – die Offscreen-API.

Mit der Offscreen-API kann die Erweiterung ein unsichtbares HTML-Dokument erstellen. Damit haben wir einen Platz, an dem wir unser HTMLAudioElement aufbewahren und es bei Bedarf einfach abspielen/anhalten können. Bedenken Sie, dass der Servicemitarbeiter immer noch keine DOM-Vorgänge ausführen kann. Daher benötigen wir ein Hilfsskript in unserem Offscreen-Dokument, um Servicemitarbeiternachrichten zu empfangen und den Player angemessen zu steuern.

Durchführung

Erforderliche Berechtigungen in manifest.json

Meine Erweiterung benötigt zwei Einträge im Berechtigungsarray:

• Tabs – es muss wissen, wann der Benutzer Tabs wechselt und/oder aktualisiert
• Offscreen – es muss in der Lage sein, ein Offscreen-Dokument zu erstellen, um den Ton von dort abzuspielen

Wenn Sie die Erweiterungsdetails im Browser öffnen, werden folgende Berechtigungen angezeigt:

Lesen Sie Ihren Browserverlauf

Es sieht vielleicht etwas beängstigend aus, aber das ist es, was das Hinzufügen der Tabs-Berechtigung bewirkt. Leider konnte ich keinen anderen Ansatz mit weniger Berechtigungen finden. Die anderen Ideen, die ich hatte, führten zu noch gruseligeren Berechtigungssätzen? In diesem Thread können Sie lesen, warum die Tabs-Berechtigung diesen Eintrag verursacht.

Offscreen-Dokumente verwalten

Wie ich bereits erwähnt habe, möchte ich nur ein HTMLAudioElement haben und das Audio davon abspielen. Um es tabulatorunabhängig zu machen, verwende ich die Offscreen-API, um ein Dokument zu erstellen, in dem es aufbewahrt und durch Nachrichten des Servicemitarbeiters gesteuert wird.

Ich habe Lust auf objektorientierte Programmierung, deshalb ist hier der OffscreenDoc-Kurs, der bei der Offscreen-Dokumentenverwaltung hilft. Im Wesentlichen wird nur das Offscreen-Dokument erstellt, wenn es noch nicht erstellt wurde.

// 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;
    }
}

Wie Sie sehen, ist die einzige öffentliche Methode „setup“ und benötigt beim Aufruf einen Pfad. Das ist ein Pfad zu einer HTML-Dokumentvorlage, die zum Erstellen unseres Offscreen-Dokuments verwendet wird. In unserem Fall wird es ganz einfach sein:

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

Im wahrsten Sinne des Wortes nur ein Skript-Tag. Dieses Skript wird verwendet, um Nachrichten von Servicemitarbeitern zu empfangen, HTMLAudioElement zu erstellen und die Musik abzuspielen/anzuhalten. Es hat auch type="module", da ich dort etwas importieren werde.

Aber um Nachrichten zu empfangen, sollten wir sie wahrscheinlich zuerst senden.

Nachrichtenschnittstelle

Es gibt keine strenge Schnittstelle für Nachrichten. Wir müssen nur sicherstellen, dass sie JSON-serialisierbar sind. Da ich jedoch möglichst typsicher sein möchte, habe ich eine einfache Schnittstelle für Nachrichten definiert, die in meiner Erweiterung übergeben werden:

// 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;
}

Sie werden gleich sehen, dass die sendMessage-Methode nicht so gut zum Tippen geeignet ist, aber es gibt einen einfachen Workaround, um dort trotzdem von der Typsicherheit zu profitieren.

Senden von Nachrichten vom Servicemitarbeiter

Der Servicemitarbeiter ist das „Gehirn“ unserer Nebenstelle, weiß, was wann passiert und soll bei Bedarf entsprechende Nachrichten senden. Aber wann genau ist es?

Wir sollten den Wiedergabestatus in drei Situationen ändern:

• Wenn ein neuer Tab aktiviert wird, wechselt der Benutzer einfach von Tab A zu Tab B,
• wenn die aktuelle Registerkarte aktualisiert wird, sodass sich ihre URL geändert hat, oder
• Wenn ein Tab geschlossen wird – das ist ein etwas kniffliger Fall, da es passieren kann, ohne dass einer der beiden oben genannten Fälle aufgerufen wird, wenn der Benutzer das letzte Inkognito-Fenster schließt, während die Audiowiedergabe läuft.

Alle Situationen bedeuten, dass wir uns möglicherweise auf der Website befinden, auf der der Ton abgespielt werden soll, oder dass wir sie gerade geschlossen/verlassen haben.

Ohne weitere Umschweife, hier ist das aktualisierte ts/background.ts-Skript, das auf die beiden Ereignisse reagiert:

// 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;
    }
}

Wie Sie sehen, ist hier die toggleAudio-Funktion am wichtigsten. Zunächst wird das Offscreen-Dokument eingerichtet. Es ist sicher, es mehrmals aufzurufen, da es einfach nichts bewirkt, wenn das Dokument bereits erstellt wurde. Anschließend wird abhängig von der URL des aktuellen Tabs entschieden, ob der Befehl „Play“ oder „Pause“ gesendet werden soll. Schließlich wird die Nachricht gesendet. Wie ich bereits erwähnt habe, gibt es für sendMessage keine generische Variante (sendMessage), daher ist es nicht trivial, den Nachrichtentyp anzugeben, aber TS hilft dabei, sicherzustellen, dass das von uns gesendete Objekt vom Typ AudioMessage ist.

Beachten Sie auch die beiden Konstanten oben – hier geben Sie an, welches Audio Sie abspielen möchten und auf welcher Website.

Empfangen der Nachrichten per Offscreen-Dokument

Endlich versenden wir die Nachrichten, also ist es jetzt an der Zeit, sie zu empfangen und etwas Musik abzuspielen?

Dazu müssen wir das von offscreen.html verwendete Skript implementieren. Es ist dist/offscreen.js, also sieht das entsprechende ts/offscreen.ts so aus:

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

Kurz gesagt: Wenn wir kein HTMLAudioElement erstellt haben, verwenden wir dafür die bereitgestellte Quelle und spielen/pausieren es dann. Die Rückgabe von undefiniert ist für Tippzwecke erforderlich. Wenn Sie an der Bedeutung der verschiedenen Rückgabewerte interessiert sind, schauen Sie sich die Dokumente an

Zusammenfassung

Probieren Sie es aus! Gehen Sie zu www.example.com (oder einer anderen Website, die Sie festgelegt haben) und prüfen Sie, ob der Ton abgespielt wird. Versuchen Sie, zwischen den Tabs hin und her zu wechseln, und prüfen Sie, ob der Vorgang ordnungsgemäß gestoppt und fortgesetzt wird.

Bedenken Sie, dass die Musik neu gestartet wird, wenn Sie sie länger als 30 Sekunden pausieren, da der Dienstmitarbeiter vom Browser beendet wird! Hier sind einige Dokumente dazu.

Um zusammenzufassen, was wir getan haben:

• Wir haben unsere manifest.json mit den erforderlichen Berechtigungen aktualisiert, um ein Offscreen-Dokument zu erstellen und Aktivitäten auf Registerkarten zu überwachen
• Wir haben den Servicemitarbeiter dazu gebracht, die Aktivität auf den Registerkarten zu beobachten und entsprechende Befehle an das Skript zu senden, das sich im Offscreen-Dokument befindet
• Wir haben mit der Audiowiedergabe über ein Skript begonnen, das Nachrichten vom Servicemitarbeiter empfängt und das DOM des Offscreen-Dokuments steuert

Ich hoffe, es war klar und leicht zu verstehen! Bei dieser Erweiterung handelt es sich um einen ganz natürlichen Fortschritt: Der Benutzer kann verschiedene Websites angeben und jeder davon unterschiedliche Audiodaten zuweisen. Hoffentlich füge ich das hinzu, wenn ich etwas Zeit habe, und schreibe einen weiteren Beitrag, in dem ich meinen Ansatz beschreibe.

Vorerst vielen Dank fürs Lesen!

Das obige ist der detaillierte Inhalt vonChrome-Erweiterung – Implementierung einer Erweiterung. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!