Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Browseranmerkungen erweitern

Passe Auswahl, Kontext und Bedienelemente für Browseranmerkungen auf deiner Website an

Mit der Browser Annotation API legst du fest, was sich auf deiner Website auswählen lässt, welcher Kontext das Feedback begleitet und mit welchen Bedienelementen sich Änderungen in der Vorschau ansehen lassen, bevor jemand eine Anmerkung an ChatGPT sendet.

In Workspaces von ChatGPT Enterprise und ChatGPT Edu muss die Administration Anpassungen für Website-Anmerkungen in der Workspace-Richtlinie erlauben.

Browseranmerkungen funktionieren auf deiner Website ohne Codeänderungen. Wer die Website nutzt, kann einen Teil der Seite auswählen, einen Kommentar hinzufügen und beides über „Kontext“ an Codex oder ChatGPT Work senden.

Bei der Entwicklung kannst du mit der Browser Annotation API Kontext oder Bedienelemente bereitstellen, die zu deiner Anwendung passen. In der Vorschau eines Designsystems kannst du beispielsweise Ansichten verschiedener Komponentenvarianten anhängen. So sieht das Entwicklungsteam, wie es die Komponenten einer Website anpassen soll.

Die Beispiele verwenden TypeScript. Kopiere ein Beispiel, speichere es als annotations.ts und kompiliere es für den Browser.

npm install --save-dev esbuild
npx esbuild annotations.ts --format=esm --outfile=annotations.js

Füge die HTML-Elemente des Beispiels in deine Seite ein. Lade anschließend das kompilierte Modul.

<script type="module" src="./annotations.js"></script>

Wenn deine Anwendung TypeScript bereits kompiliert, nimm das Beispiel in den bestehenden Build auf.

Wenn du die Browser Annotation API kennenlernen oder Anmerkungen auf deiner Website unterstützen möchtest, hilft dir das Plugin Annotations Extensibility. Installiere es über die folgende Schaltfläche.

Plugin Annotations Extensibility installieren

Ausprobieren

Probiere die Browser Annotation API direkt in diesem Leitfaden aus.

  1. Öffne diese Seite im In-App-Browser von ChatGPT.
  2. Öffne den vorgeschlagenen Prompt, der in dieser Karte erscheint.
  3. Aktiviere den Anmerkungsmodus. Wähle dann die Tabelle unten oder ein Codebeispiel aus, um zwischen vordefinierten Layouts und Designs zu wechseln.
  4. Du kannst weiterhin jedes Element auf der Seite mit einer Anmerkung versehen und ausprobieren, wie Anmerkungen standardmäßig funktionieren.

Im Browser von ChatGPT öffnen

Passende Anpassung auswählen

Beginne mit der Integration, die zu deiner Website passt.

Ziel Integration
Eine Karte oder eine andere Gruppe von Elementen als einzelnes Objekt auswählbar machen Auswahlziele
Die Auswahl einzelner Wortgruppen oder Sätze ermöglichen Container für die Textauswahl
Zusätzlichen Kontext zur Auswahl mitgeben Metadaten zur Auswahl
Über eine eigene Schaltfläche eine Anmerkung mit einem vorgeschlagenen Kommentar öffnen Anmerkungen anfordern
Über die eigene Oberfläche Feedback zu einer bestimmten Textstelle anfordern Anmerkungen zu Textbereichen anfordern
Beim Öffnen einer Anmerkung erweiterte Bedienelemente anzeigen Standardmodus des Editors
Anwendungseigenschaften in der Vorschau anzeigen oder eine Auswahl erfassen Eigene Bedienelemente
Einzelne Objekte innerhalb eines Canvas auswählen Anmerkungsflächen
Den Anmerkungsmodus über die Website ein- oder ausschalten Anmerkungsmodus steuern

Dieser Leitfaden gilt für die zum DevDay 2026 veröffentlichte Version der ChatGPT-Desktop-App und alle neueren Versionen. Im In-App-Browser ist die JavaScript-API über document.oai.annotation auf sicheren Seiten der obersten Ebene verfügbar, etwa über HTTPS oder auf localhost. Wenn die API aktiviert ist, stellt der Browser sie bereit, bevor die Skripte deiner Seite ausgeführt werden. Prüfe bei jeder Methode, ob sie verfügbar ist, damit deine Website auch in älteren Browsern und in Browsern ohne API-Unterstützung funktioniert. Initialisiere die Integration, sobald ihre DOM-Elemente vorhanden sind. Dafür brauchst du weder ein Bereitschaftsereignis noch Polling.

Die API-Methoden kehren synchron zurück. Die zurückgegebenen Registrierungsobjekte kannst du sofort verwenden. Der Browser kann den Anmerkungseditor anschließend fertig laden. Der hitTest-Callback einer Anmerkungsfläche kann ein Promise zurückgeben.

Auswahlziele anpassen

Im Anmerkungsmodus wählt der Browser standardmäßig Elemente aus dem DOM der Seite aus, bevorzugt Texte, Bilder und Bedienelemente. Soll sich ein größeres Objekt auswählen lassen, kennzeichne den umgebenden Bereich mit oai-annotation-container und die darin auswählbaren Elemente mit oai-annotatable.

In diesem Beispiel lässt sich eine Karte mit einem Diagramm als einzelnes Objekt auswählen.

<section oai-annotation-container>
  <article id="chart-card" oai-annotatable="Q3 Revenue">
    <h2>Q3 Revenue</h2>
    <p>$120,000 this quarter</p>
    <button type="button">More info</button>
  </article>
</section>

Sobald der Mauszeiger über einer beliebigen Stelle der Karte steht, wird die gesamte Karte hervorgehoben. Mit dem optionalen Wert von oai-annotatable gibst du dem Objekt einen Namen, den sowohl die Person als auch das Modell sehen. Wähle Namen, anhand derer sich benachbarte Objekte unterscheiden lassen, oder lass den Wert weg.

Der Container legt fest, wo diese Auswahlregeln gelten. Das Attribut oai-annotatable allein ändert das Auswahlverhalten nicht. Innerhalb eines Containers wählt der Browser das nächstgelegene gekennzeichnete Ziel aus, das das Element unter dem Mauszeiger enthält. Bei verschachtelten Containern ist der nächstgelegene Container maßgeblich. Wer einen nicht gekennzeichneten Bereich innerhalb eines Containers auswählt, erstellt eine Anmerkung zur Webseite. Außerhalb aller Container gilt das Standardverhalten.

Textauswahl ermöglichen

Füge einem Bereich oai-annotation-container-text hinzu, damit sich im Anmerkungsmodus Text durch Ziehen auswählen lässt. Das Attribut benötigt keinen Wert.

<article oai-annotation-container-text>
  <h2>Design guidelines</h2>
  <p>Use consistent spacing between related components.</p>
  <p>Leave more space between separate groups.</p>
</article>

Wenn du nach der Auswahl von Text loslässt, öffnet sich der Editor für Textanmerkungen mit dem ausgewählten Bereich und seinem Kontext. Ein Klick ohne Textauswahl erstellt keine Anmerkung. Drückst du Escape oder brichst du die Geste ab, wird die Auswahl verworfen.

Der nächstgelegene Container für die Text- oder DOM-Auswahl bestimmt, wie die Geste beginnt. Textcontainer verwenden oai-annotatable nicht zur Auswahl einzelner Elemente. Verschachtle einen oai-annotation-container, um darin wieder einzelne Elemente auswählbar zu machen, oder einen Textcontainer, um darin wieder Textauswahl zu ermöglichen. Hat ein Element beide Attribute, hat die Textauswahl Vorrang.

Die Textauswahl folgt den üblichen Auswahlregeln der Seite und kann über den Container hinausreichen, in dem sie beginnt. Ein Container begrenzt den ausgewählten Bereich nicht und ermöglicht keine Auswahl innerhalb eines Iframes. Textfelder bleiben auswählbar. Normale Klicks auf der Seite und native Aktionen von Bedienelementen sind im Anmerkungsmodus weiterhin gesperrt. Explizite Aufrufe von request() verhalten sich wie bisher.

Container für die Textauswahl wirken nur im Anmerkungsmodus und nur dann, wenn sowohl die Funktion für Website-Anmerkungen als auch die Einstellung für die jeweilige Website aktiviert sind.

Kontext zu einer Auswahl hinzufügen

Füge einem gekennzeichneten Ziel oai-annotation-metadata hinzu, um Kontext mitzugeben, der auf der Seite möglicherweise nicht sichtbar ist. Eine Zeile mit fiktiven Kontaktdaten kann beispielsweise eine E-Mail-Adresse enthalten, die beim Anfordern eines E-Mail-Entwurfs mitgegeben wird.

<section oai-annotation-container>
  <div
    id="contact-row"
    oai-annotatable="Alex Morgan"
    oai-annotation-metadata='{"email":"alex@example.com"}'
  >
    <div>Alex Morgan</div>
    <div>Project lead</div>
  </div>
</section>

Ob du den Namen oder die Position auswählst, in beiden Fällen wird der gesamte Kontakteintrag ausgewählt. Die Metadaten erscheinen in der Anmerkung und werden mit ihr im Gespräch übermittelt. Gib nur Kontext mit, den du sowohl mit der Person als auch mit dem Modell teilen möchtest. Zum Senden einer E-Mail wäre weiterhin ein verbundenes E-Mail-Tool erforderlich.

Verwende ein kleines, flaches JSON-Objekt und beachte folgende Grenzen.

  • Bis zu sechs Eigenschaften mit Zeichenfolgen, endlichen Zahlen, booleschen Werten oder null als Wert.
  • Bis zu 64 Zeichen pro Schlüssel und bis zu 256 Zeichen pro Zeichenfolgenwert.
  • Bis zu 2.048 Byte für das serialisierte Objekt.

Schlüssel müssen mit einem ASCII-Buchstaben beginnen und dürfen nur ASCII-Buchstaben, Ziffern, Leerzeichen, Unterstriche oder Bindestriche enthalten. Trenne Wörter durch jeweils ein Leerzeichen. Verschachtelte Objekte und Arrays werden nicht unterstützt. Der Browser ignoriert ungültige Metadaten.

Du kannst Metadaten auch über request() oder über das Ergebnis von hitTest für eine Anmerkungsfläche bereitstellen.

Eine Anmerkung über deine Website öffnen

Rufe document.oai.annotation.request(target, options) direkt während einer Nutzerinteraktion auf, etwa beim Klick auf eine Schaltfläche. Als Ziel eignet sich ein in das aktuelle Dokument eingebundenes HTML-Element im sichtbaren Bereich oder ein DOM-Bereich vom Typ Range. Das Ziel benötigt keine Anmerkungsattribute. IDs virtueller Objekte werden nicht unterstützt.

Wenn die Website eine Anmerkung anfordert, muss die Person dies möglicherweise erst erlauben. Unter Website-Tools > Anmerkungsfunktionen kann sie gesperrte Anmerkungsfunktionen wieder aktivieren.

Dieses Beispiel öffnet eine Anmerkung zu einem Absatz ohne Auswahlattribute. Führe das Skript aus, sobald beide Elemente vorhanden sind.

<p id="delivery-summary">
  Standard delivery takes three to five business days.
</p>
<button id="discuss-delivery" type="button" hidden>Explain more</button>
const summary = document.getElementById("delivery-summary") as HTMLElement;
const button = document.getElementById("discuss-delivery") as HTMLButtonElement;

button.hidden = typeof document.oai?.annotation?.request !== "function";

button.addEventListener("click", () => {
  const annotation = document.oai?.annotation;
  if (typeof annotation?.request !== "function") return;

  annotation.request(summary, {
    initialComment: "Explain this delivery estimate.",
  });
});

Ein Klick auf Näher erläutern fordert den Browser auf, eine Anmerkung mit dem ausgewählten Absatz und einem bearbeitbaren Kommentar zu öffnen. Die Person kann die Anmerkung bearbeiten, speichern und mit ihrer Nachricht senden. Beim Öffnen geht noch keine Nachricht an ChatGPT. Nur die Person selbst kann sie absenden.

Führe den Aufruf während der laufenden Interaktion aus. Wartest du zuerst auf eine Netzwerkanfrage, kann der Browser den Aufruf möglicherweise nicht mehr der Interaktion zuordnen.

Das optionale zweite Argument unterstützt folgende Felder.

Option Verhalten
mode Mit "advanced" öffnest du die erweiterten Bedienelemente für ein Element. Mit "default" verwendest du das Standardverhalten des Editors. Der Standardwert ist "default". Eigene Bedienelemente können sich auch mit "default" öffnen. Mehr dazu unter Standardmodus des Editors. Textbereiche unterstützen ausschließlich "default".
enterAnnotationMode Setze den Wert auf true, um den Anmerkungsmodus zu aktivieren und nach dem Abbrechen oder Senden der Anmerkung in diesem Modus zu bleiben.
omitScreenshot Setze den Wert auf true, um den automatischen Screenshot für diese Anmerkung wegzulassen. Beim Standardwert false erstellt der Browser Screenshots wie gewohnt. Die Option gilt für Anfragen zu Elementen und zu Textbereichen.
metadata Gültige, nicht leere Metadaten ersetzen für diese Anfrage die HTML-Metadaten des Ziels. Bei Textbereichen und bei Zielelementen innerhalb eines Shadow DOM ignoriert der Browser diese Option.
initialComment Gibt einen bearbeitbaren Kommentar mit bis zu 240 UTF-16-Codeeinheiten vor.

request() gibt ein Objekt mit dem booleschen Feld accepted zurück. Prüfe result.accepted statt des Ergebnisobjekts selbst, um festzustellen, ob der Browser die Anfrage empfangen und validiert hat. Daraus geht weder hervor, ob sich der Editor geöffnet hat, noch ob die Person eine Anmerkung gespeichert oder gesendet hat.

Während der Editor lädt, kann der Browser eine angenommene Anfrage vormerken. Eine weitere Anfrage kann er ablehnen, solange eine Anfrage aussteht, ein Editor geöffnet ist oder ChatGPT den Browser steuert.

Eine Anmerkung zu einem Textbereich anfordern

Übergib einen DOM-Bereich vom Typ Range, um Feedback zu einer Textstelle anzufordern, ohne die Textauswahl des Browsers zu ändern. Dieses Beispiel wählt nur die hervorgehobenen Wörter aus. Dafür ist kein oai-annotation-container-text-Attribut erforderlich.

<p>
  Your trial includes full access for <mark id="draft-passage">14 days</mark>.
</p>
<button id="discuss-passage" type="button" hidden>
  Ask about highlighted text
</button>

Führe dieses Skript aus, sobald beide Elemente vorhanden sind.

const passage = document.getElementById("draft-passage") as HTMLElement;
const button = document.getElementById("discuss-passage") as HTMLButtonElement;

button.hidden = typeof document.oai?.annotation?.request !== "function";

button.addEventListener("click", () => {
  const annotation = document.oai?.annotation;
  if (typeof annotation?.request !== "function") return;

  const range = document.createRange();
  range.selectNodeContents(passage);
  annotation.request(range, {
    initialComment: "Explain when this trial ends.",
  });
});

Der Bereich muss sichtbaren, nicht leeren Text im aktuellen Dokument enthalten. Mindestens ein Teil der Auswahl muss im sichtbaren Seitenbereich liegen. Der Bereich darf höchstens 20.000 UTF-16-Codeeinheiten umfassen. Nicht unterstützt werden auf einen Punkt reduzierte Bereiche, Text ausschließlich aus Leerraumzeichen, ausgeblendeter ausgewählter Text und Bereiche in geschlossenen Shadow Roots.

Anfragen zu Textbereichen verwenden ausschließlich den Standard-Texteditor. Der Browser lehnt Anfragen mit mode: "advanced" ab und ignoriert Metadaten der Anfrage. Halte den Zieltext verfügbar, solange eine angenommene Anfrage auf den Editor wartet. Der Browser prüft den Bereich vor dem Öffnen erneut. Unabhängig davon ermöglichen Container für die Textauswahl, Text im Anmerkungsmodus durch Ziehen auszuwählen.

Standardmodus des Editors festlegen

Sollen die erweiterten Bedienelemente sofort erscheinen, wenn jemand über die Auswahlfunktion des Browsers eine Anmerkung öffnet, füge dieses Tag in den <head> deiner Seite ein.

<meta name="oai-annotation-editor-default-mode" content="advanced" />

Für Anmerkungen, die du über deine eigene Oberfläche öffnest, übergib { mode: "advanced" } an request(). Für das Standardverhalten des Editors verwende mode: "default" oder lass die Option weg. Die Meta-Einstellung der Seite überschreibt diese Anfrageoption nicht. Auch im Standardmodus kann der Editor mehr als ein Kommentarfeld anzeigen. Eigene Bedienelemente mit vorgeschlagenen Anfangswerten oder ohne currentValue können den Editor mit Bedienelementen öffnen.

Die manuellen Funktionen zum Anpassen, zum Einklappen und zum Klicken mit gedrückter Wahltaste sind nur in Codex oder auf localhost verfügbar. Auf gehosteten Websites in ChatGPT erscheinen registrierte eigene Bedienelemente automatisch. Es gibt dort weder die Schaltfläche Anpassen noch eine Schaltfläche zum Einklappen. Die Seite kann den erweiterten Modus dort weiterhin anfordern.

Eigene Bedienelemente hinzufügen

Mit registerControls() ordnest du einem oder mehreren DOM-Elementen Bedienelemente für Anmerkungen zu. Damit kannst du Anwendungseigenschaften wie ein Token für Abstände in der Vorschau anzeigen. Du kannst damit auch eine Auswahl erfassen und mit einer Anfrage übermitteln, etwa den gewünschten Ton einer E-Mail.

Ein gemeinsames Abstandstoken in der Vorschau testen

Beide Karten in diesem Beispiel verwenden dieselbe CSS-Eigenschaft. Registriere die Bedienelemente direkt für die Karten. Auswahlattribute sind dafür nicht erforderlich.

<style>
  #component-preview {
    --card-padding: 16px;
  }

  .preview-card {
    padding: var(--card-padding);
    border: 1px solid #d1d5db;
  }
</style>

<section id="component-preview">
  <article class="preview-card">Profile card</article>
  <article class="preview-card">Summary card</article>
</section>

Führe dieses Skript aus, nachdem du die Vorschau erstellt hast.

const preview = document.getElementById("component-preview") as HTMLElement;
const annotation = document.oai?.annotation;

function previewSpacing(event: Event) {
  const { callback, value } = (
    event as CustomEvent<{ callback: string; value: number | string }>
  ).detail;
  if (callback === "setCardPadding") {
    preview.style.setProperty("--card-padding", `${value}px`);
  }
}

let registration: { dispose(): void } | undefined;
if (typeof annotation?.registerControls === "function") {
  preview.addEventListener("oaiannotationcontrolchange", previewSpacing);
  registration = annotation.registerControls({
    targets: preview.querySelectorAll(".preview-card"),
    controlsHeading: "Card spacing",
    controlsMode: "replace",
    controls: [
      {
        type: "range",
        label: "Card padding (pixels)",
        callback: "setCardPadding",
        reference: "--card-padding",
        min: 8,
        max: 32,
        step: 4,
        currentValue: 16,
      },
    ],
  });
}

function disposeAnnotationControls() {
  preview.style.removeProperty("--card-padding");
  registration?.dispose();
  preview.removeEventListener("oaiannotationcontrolchange", previewSpacing);
}

Öffne eine Anmerkung zu einer der Karten und ändere den Wert für Innenabstand der Karten (Pixel) von 16 auf 24. Auf gehosteten Websites in ChatGPT erscheinen die Bedienelemente automatisch. In Codex oder auf localhost wählst du bei Bedarf Anpassen. Beide Karten ändern sich. Die Anmerkung erfasst die Beschriftung, die Referenz sowie den alten und den neuen Wert. Wenn du die Vorschau zurücksetzt, wird der ursprüngliche Innenabstand wiederhergestellt. Rufe disposeAnnotationControls() auf, wenn du die Komponente entfernst.

Eine Auswahl ohne Vorschau erfassen

In diesem Beispiel kannst du für einen einfachen Absatz den Ton einer E-Mail auswählen. Dafür brauchst du weder Auswahlattribute noch Metadaten. Führe das Skript aus, sobald der Absatz vorhanden ist.

<p id="email-draft">Draft a follow-up email about the project timeline.</p>
const draft = document.getElementById("email-draft") as HTMLElement;
const registration = document.oai?.annotation?.registerControls?.({
  targets: draft,
  controlsHeading: "Email options",
  controlsMode: "replace",
  controls: [
    {
      type: "select",
      label: "Email tone",
      callback: "emailTone",
      options: [
        { label: "Professional", value: "professional" },
        { label: "Friendly", value: "friendly" },
        { label: "Direct", value: "direct" },
      ],
      defaultValue: "professional",
    },
  ],
});

Dieses Bedienelement benötigt keinen Event-Handler, weil es keine Änderung an der Seite in einer Vorschau anzeigt. Lässt du currentValue weg, übernimmt der Browser den ausgewählten Ton auch dann in die Anmerkung, wenn die Person die anfängliche Auswahl beibehält. Rufe registration?.dispose() auf, wenn du den Absatz entfernst.

Bei Auswahlfeldern erhalten die Vorschau-Callbacks option.value, etwa "professional". Im Anmerkungsverlauf und in ChatGPT erscheint für die vorherige und die ausgewählte Option jeweils die sichtbare Beschriftung option.label, etwa "Professional". Verwende Beschriftungen, die jede Option verständlich machen. Interne IDs in value werden nicht als Text der Auswahl gesendet.

Bedienelemente und Anfangswerte konfigurieren

Mit controlsMode: "replace" zeigst du für die registrierten Ziele ausschließlich deine eigenen Bedienelemente an. Mit "extend" erscheinen sie neben den integrierten Bedienelementen. Über controlsHeading kannst du dem Bereich eine Überschrift geben. Der Browser entfernt führende und nachgestellte Leerraumzeichen und akzeptiert dann 1–80 Zeichen. Ohne Überschrift zeigt der Bereich das HTML-Tag des Elements an. Die Überschrift gehört nicht zum Kontext, der an ChatGPT gesendet wird.

Eine Registrierung unterstützt bis zu zwölf Bedienelemente. Jedes benötigt einen Typ (type), eine sichtbare Beschriftung (label) und eine Kennung (callback).

Benenne Bedienelemente nach der Eigenschaft, die sie ändern. Verwende eine beständige Bezeichnung für die Eigenschaft oder ihre Funktion im Design, etwa „Seitenhintergrund“, „Primäre Markenfarbe“ oder „Akzentfarbe“. Bezeichnungen wie „Warmes Elfenbein“ oder „Dunkles Waldgrün“ beschreiben lediglich den aktuellen Wert. Die Beschriftung sollte auch nach einer Wertänderung aussagekräftig bleiben. Gib mit currentValue den aktuellen Wert an und mit reference das zugrunde liegende Token oder die Eigenschaft.

In dieser Definition bleibt die Beschriftung unabhängig von der Farbe.

const pageBackgroundControl = {
  type: "color",
  label: "Page background",
  callback: "setPageBackground",
  reference: "--color-background",
  currentValue: "#f6f3ec",
};

Folgende Typen von Bedienelementen werden unterstützt.

Typ Wert Zusätzliche Felder
color Hexadezimaler Farbwert, etwa "#2563eb" Keine
range Zahl min, max und step
select Zeichenfolge options, ein Array aus Objekten der Form { label, value }
toggle Boolescher Wert Keine

callback enthält eine Kennung als Zeichenfolge, keine JavaScript-Funktion. Die Kennung muss innerhalb der Registrierung eindeutig sein, mit einem ASCII-Buchstaben beginnen und darf nur ASCII-Buchstaben, Ziffern, Unterstriche oder Bindestriche enthalten. Mit reference kannst du die zu ändernde Eigenschaft angeben. Diese Referenz erscheint zusammen mit Beschriftung und Wert in der Anmerkung.

Setze currentValue auf den gültigen Wert, den die Eigenschaft außerhalb der Vorschau hat. Berücksichtige dabei auch ungespeicherte Änderungen. Verwende weder den Vorschauzustand noch unvollständige Eingaben als Ausgangswert. Der Browser benötigt den Ausgangswert für Vorher-nachher-Vergleiche und zum Zurücksetzen. Ändert sich der Anwendungszustand, aktualisiere mit registration.update({ controls }) die Werte von currentValue für die Bedienelemente. Aktualisierungen gelten für künftige Anmerkungen. Bestehende Anmerkungen behalten die zuvor erfassten Werte.

Mit defaultValue schlägst du einen Anfangswert vor. Beim Initialisieren des Bedienelements hat er Vorrang vor currentValue. Lässt du beide weg, beginnt ein Farbfeld mit Weiß, ein Schieberegler mit dem Mindestwert, ein Auswahlfeld mit der ersten Option und ein Umschalter mit false.

Verwalte vorgeschlagene Werte getrennt von regulären Entwürfen. Löst eine Aktualisierung eine Ausnahme aus, schlägt eine Anfrage fehl oder gibt sie accepted: false zurück, verwirf den neuen Vorschlag. Stelle die vorherigen Bedienelemente und den vorherigen Stand der Vorschläge wieder her. Behalte Vorschläge bei, wenn der Browser die Anfrage annimmt. Er kann die Anfrage vormerken, bevor er die Bedienelemente erfasst.

Bedienelemente und Registrierungen validieren

Der Browser prüft Registrierungen und Aktualisierungen anhand folgender Grenzen.

Feld oder Ressource Einschränkung
Bedienelemente Bis zu zwölf pro Registrierung, jeweils mit eindeutiger callback-Kennung. Verwende nur die für den jeweiligen Typ definierten Felder.
Beschriftungen und Überschriften Beschriftungen von Bedienelementen und Optionen sowie controlsHeading müssen nach dem Entfernen führender und nachgestellter Leerraumzeichen mindestens eine UTF-16-Codeeinheit enthalten und dürfen höchstens 80 UTF-16-Codeeinheiten umfassen. Texte für Bedienelemente dürfen weder Steuerzeichen noch Zeichen enthalten, die die Schreibrichtung ändern.
Kennungen callback darf nach dem Entfernen führender und nachgestellter Leerraumzeichen höchstens 80 UTF-16-Codeeinheiten umfassen und muss dem oben beschriebenen Format entsprechen. reference muss 1–80 Zeichen umfassen. Erlaubt sind ASCII-Buchstaben, Ziffern und die Zeichen _ . / : @ $ # -, jedoch keine Leerzeichen.
Optionen in Auswahlfeldern 1–12 Optionen mit unterschiedlichen value-Zeichenfolgen von jeweils höchstens 512 UTF-16-Codeeinheiten. Wenn du currentValue oder defaultValue angibst, muss der jeweilige Wert mit dem Wert einer Option übereinstimmen.
Werte für Schieberegler min, max, currentValue und defaultValue müssen endliche Zahlen zwischen −10.000 und 10.000 sein. Es muss min < max gelten. Für step ist ein Wert von 0,001 bis 10.000 zulässig, der höchstens max - min beträgt. Die Anfangswerte müssen innerhalb des Bereichs liegen, aber nicht dem Raster von step entsprechen.
Farben und Umschalter Farbwerte müssen nach dem Zeichen # aus 3, 4, 6 oder 8 hexadezimalen Ziffern bestehen. Für Umschalter sind nur true und false zulässig.
Ziele Bei der Registrierung sind 1–128 Zieleinträge zulässig. Alle müssen Elemente im aktuellen Dokument sein. Bei einer Aktualisierung kannst du mit targets: [] die Zuordnung aufheben. Pro Dokument sind bis zu 64 Registrierungen für Bedienelemente und 1.024 Zuordnungen zwischen Registrierungen und Zielen möglich.
Serialisierte Bedienelemente Die JSON-Nutzdaten mit controls, controlsHeading und controlsMode dürfen insgesamt höchstens 16.384 UTF-16-Codeeinheiten umfassen. Verwende Daten, die sich als JSON kodieren lassen, ohne Funktionen, Symbole oder BigInts.

registerControls() und registration.update() können bei ungültigen Definitionen oder Zielen sowie beim Überschreiten der Grenzen synchron eine Ausnahme auslösen. Auch eine Aktualisierung nach dispose() löst eine Ausnahme aus. Bei einer abgelehnten Aktualisierung bleibt die vorherige Registrierung einschließlich ihrer Bedienelemente und Ziele erhalten. Behandle Fehler an der Aufrufstelle und sorge dafür, dass die reguläre Bearbeitung weiter funktioniert. Verwende deine Registrierungen erneut oder gib sie frei, um innerhalb der Grenzen zu bleiben.

Vorschau und Zurücksetzen verarbeiten

Das Ereignis oaiannotationcontrolchange steigt vom ausgewählten Element im DOM auf. Sein Feld detail enthält callback, value und action.

Aktion Zweck des übergebenen Werts
preview Die angeforderte Änderung anzeigen.
preview-original Zum Vergleich vorübergehend den ursprünglichen Zustand anzeigen.
reset Beim Zurücksetzen der Vorschau den ursprünglichen Zustand wiederherstellen.

Wende wie im Beispiel zum Innenabstand bei jeder Aktion den übergebenen Wert an. Gestalte die Handler so, dass ihre Änderungen umkehrbar sind und wiederholte Aufrufe sicher funktionieren. Vorschauereignisse fordern keine dauerhafte Änderung an. Verwende zum Speichern den üblichen Ablauf deiner Anwendung. Halte reguläre Entwürfe, unvollständige Eingaben und Vorschauen getrennt, damit andere Änderungen eine Vorschau nicht überschreiben. Bearbeitet jemand dieselbe Einstellung, ersetze deren Vorschau und aktualisiere den Ausgangswert für künftige Anmerkungen.

Bewahre das Registrierungsobjekt für Aktualisierungen und zum Aufräumen auf. update() akzeptiert jede Kombination aus targets, controls, controlsHeading und controlsMode. Nicht angegebene Felder behalten ihre bisherigen Werte. Verwende beispielsweise registration.update({ targets: newElement }), wenn du das DOM-Element einer Komponente ersetzt. Eine Zielsammlung erfasst nur die vorhandenen Elemente. Elemente, die erst später dem Selektor entsprechen, kommen nicht automatisch hinzu.

Übergib targets: [], um die Zuordnung der Registrierung zu ihren Zielen aufzuheben, oder controls: [], um ihre Bedienelemente zu entfernen. Wenn du die Integration entfernst, rufe dispose() auf und entferne die Event-Listener. Stelle beim Aufräumen auch die normale Darstellung wieder her. dispose() entfernt nur die Registrierung der Bedienelemente. Änderungen durch die Vorschau bleiben bestehen. Im Beispiel zum Innenabstand wird die Inline-Formatierung entfernt, damit wieder der ursprüngliche CSS-Wert gilt. Beide Methoden kehren synchron ohne Rückgabewert zurück. Aktualisierungen gelten für künftige Auswahlvorgänge. Gespeicherte Anmerkungen behalten ihre erfassten Bedienelemente und ihr Ziel.

Ereignisse von Bedienelementen richten sich an das Element, das die Anmerkung erfasst hat. Wenn du die Ziele einer Registrierung aktualisierst, behalten bestehende Anmerkungen ihr bisheriges Ziel. Ereignisse zum Zurücksetzen können auch an einem bereits entfernten Element ausgelöst werden. Ein Listener am früheren Elternelement empfängt sie dann nicht.

Objekte in einem Canvas auswählbar machen

Mit einer Anmerkungsfläche kann deine Anwendung einzelne Objekte identifizieren, die in einem Canvas gezeichnet sind. Registriere das Host-Element mit registerSurface() und stelle eine hitTest-Funktion bereit. Sie gibt bei einem Treffer ein Objekt mit einer stabilen id und für leere Flächen null zurück.

Der Host muss ein eingebundenes HTML-Element außerhalb des Shadow DOM in einem sicheren Dokument der obersten Ebene sein. Innerhalb eines Iframes lassen sich keine Anmerkungsflächen registrieren.

Objekte auswählen und identifizieren

Dieses Beispiel zeichnet einen Umsatzbalken. Für die Auswahl genügen hitTest und eine stabile Objekt-ID. Platziere das Skript hinter dem Canvas.

<canvas id="revenue-canvas" width="480" height="240">
  Revenue this quarter: $120,000.
</canvas>
const canvas = document.getElementById("revenue-canvas") as HTMLCanvasElement;
const context = canvas.getContext("2d") as CanvasRenderingContext2D;
const bar = { x: 40, y: 60, width: 320, height: 100 };

context.fillStyle = "#2563eb";
context.fillRect(bar.x, bar.y, bar.width, bar.height);

const surface = document.oai?.annotation?.registerSurface?.({
  element: canvas,
  hitTest({ clientX, clientY }) {
    const bounds = canvas.getBoundingClientRect();
    const scaleX = bounds.width / canvas.width;
    const scaleY = bounds.height / canvas.height;
    const rect = {
      x: bounds.left + bar.x * scaleX,
      y: bounds.top + bar.y * scaleY,
      width: bar.width * scaleX,
      height: bar.height * scaleY,
    };

    if (
      clientX < rect.x ||
      clientX > rect.x + rect.width ||
      clientY < rect.y ||
      clientY > rect.y + rect.height
    ) {
      return null;
    }

    return { id: "revenue-this-quarter" };
  },
});

Wenn du im Codebeispiel den Balken im Anmerkungsmodus auswählst, erhältst du die Kennung revenue-this-quarter. Verwende innerhalb einer Anmerkungsfläche stabile IDs. Für leere Flächen gibt das Beispiel null zurück.

hitTest kann ein Promise zurückgeben und erhält ein AbortSignal als signal, mit dem sich überholte Vorgänge abbrechen lassen. Der Browser wartet bis zu 250 Millisekunden und greift dann auf die DOM-Auswahl zurück. Dasselbe gilt bei Fehlern und ungültigen Ergebnissen. Gib ausdrücklich null zurück, wenn die Trefferprüfung erfolgreich abgeschlossen wurde, aber kein Objekt gefunden hat.

Auch bei einem Abbruch muss das zugehörige Promise erfüllt oder abgelehnt werden. Der Browser lässt jeweils nur einen laufenden hitTest-Callback zu. Er wartet auf den Abschluss des Promise, auch nach einem Abbruch oder einer Zeitüberschreitung. Übernimmt ein Worker die Trefferprüfung, schließe das ausstehende Promise ab, wenn seine Arbeit abgebrochen wird. Verwirfst du die Antwort des Workers nach einem Abbruch einfach, kann das spätere Auswahlen im Canvas blockieren.

Rufe surface?.invalidate() auf, nachdem du Objekte verschoben oder den Zoom geändert hast. Rufe surface?.dispose() auf, wenn du die Integration entfernst. Beide Methoden kehren synchron ohne Rückgabewert zurück.

Optionalen Kontext zum Objekt hinzufügen

Die id genügt, um das Objekt zu identifizieren. Möchtest du einen Anzeigenamen, eine semantische Rolle, nicht sichtbaren Kontext oder die Abmessungen und Position der Auswahl mitgeben, ersetze die Rückgabe für einen Treffer im vorangehenden hitTest-Callback durch folgenden Code.

return {
  id: "revenue-this-quarter",
  name: "Revenue this quarter",
  role: "chart-bar",
  metadata: { metricId: "quarterly-revenue" },
  rect,
};

Der optionale name wird der Person angezeigt. Mit role beschreibst du kurz die Bedeutung des Objekts. Füge Metadaten nur hinzu, wenn sie Kontext liefern, der noch nicht sichtbar ist. Das optionale rect verwendet CSS-Pixel relativ zum sichtbaren Seitenbereich, passend zu clientX und clientY. Das Beispiel zur Objektauswahl berechnet dieses Rechteck bereits. Rechne Szenenkoordinaten entsprechend um und berücksichtige dabei Skalierung, Verschiebung und Zoom.

Die Auswahl optional hervorheben

Mit dem optionalen Callback renderSelection kannst du selbst zeichnen, wie Objekte unter dem Mauszeiger oder bei der Auswahl hervorgehoben werden. Die optionalen Kontextfelder brauchst du dafür nicht.

Definiere für den Canvas aus dem Beispiel die folgende Funktion und füge renderSelection: renderRevenueSelection zu den Optionen von registerSurface() hinzu.

function renderRevenueSelection({
  hoveredId,
  selectedId,
}: {
  hoveredId: string | null;
  selectedId: string | null;
}) {
  context.clearRect(0, 0, canvas.width, canvas.height);
  context.fillStyle = "#2563eb";
  context.fillRect(bar.x, bar.y, bar.width, bar.height);

  if (
    hoveredId === "revenue-this-quarter" ||
    selectedId === "revenue-this-quarter"
  ) {
    context.strokeStyle = "#111827";
    context.lineWidth = 3;
    context.strokeRect(bar.x, bar.y, bar.width, bar.height);
  }
}

Der Callback zeichnet den Balken mit einer Umrandung, solange der Mauszeiger darüber steht oder der Balken ausgewählt ist. Haben beide IDs den Wert null, zeichnet er den Balken ohne Umrandung neu.

Bedienelemente zu Canvas-Objekten hinzufügen

Registriere eigene Bedienelemente für das DOM-Element der Anmerkungsfläche. Gezeichnete Objekte heißen in der API virtuelle Objekte. Sie verwenden deine eigenen Bedienelemente. Die integrierten CSS- und Textbedienelemente sind für sie nicht verfügbar.

Bei mehreren Objekten aktualisierst du mit renderSelection die Bedienelemente des Hosts, sobald sich selectedId ändert und bevor der Browser die Anmerkung erfasst. Ereignisse von Bedienelementen enthalten detail.virtualTarget: { surfaceId, targetId }. Ordne jedes Ereignis anhand dieser erfassten Kennungen und seines callback zu, unabhängig von der aktuellen Auswahl. targetId entspricht der id aus hitTest. surfaceId bezeichnet die Registrierung der Anmerkungsfläche im Browser. Normale DOM-Ereignisse enthalten kein virtualTarget.

Ereignisse für Vorschau, Vergleich und Zurücksetzen bleiben dem ursprünglichen Objekt zugeordnet, auch wenn inzwischen ein anderes Objekt ausgewählt wurde. Beim erneuten Öffnen einer gespeicherten Anmerkung führt der Browser keine neue Trefferprüfung durch, um das erfasste Objekt oder dessen Metadaten zu ersetzen.

Anmerkungsmodus steuern

Fordere mit toggle() einen Moduswechsel an, lies mit isActive() den bestätigten Zustand aus und halte deine Oberfläche über das Dokumentereignis oaiannotationmodechange synchron. Prüfe für ältere Browser und Browser ohne API-Unterstützung, ob beide Methoden verfügbar sind. Füge die folgende Schaltfläche hinzu und führe das Skript aus, sobald sie vorhanden ist.

<button id="toggle-annotations" type="button" hidden>
  Enter annotation mode
</button>
const button = document.getElementById(
  "toggle-annotations"
) as HTMLButtonElement;
const annotation = document.oai?.annotation;

function renderMode(active: boolean) {
  button.textContent = active
    ? "Exit annotation mode"
    : "Enter annotation mode";
}

const onModeChange = (event: Event) =>
  renderMode((event as CustomEvent<{ active: boolean }>).detail.active);
const onClick = () => annotation?.toggle(!annotation.isActive());

if (
  typeof annotation?.toggle === "function" &&
  typeof annotation?.isActive === "function"
) {
  document.addEventListener("oaiannotationmodechange", onModeChange);
  button.addEventListener("click", onClick);
  renderMode(annotation.isActive());
  button.hidden = false;
}

function cleanupAnnotationButton() {
  document.removeEventListener("oaiannotationmodechange", onModeChange);
  button.removeEventListener("click", onClick);
  button.hidden = true;
}

toggle() schaltet den Modus um. Übergib true, um ihn gezielt einzuschalten, oder false, um ihn auszuschalten. Wiederholte Anfragen mit demselben booleschen Wert sind idempotent. Bei true bleibt ein aktiver Editor geöffnet und eine ausstehende Aktivierung erhalten. Bei false wird eine ausstehende Aktivierung abgebrochen und der Modus auf dem üblichen Weg beendet.

Rufe toggle() während einer laufenden Nutzerinteraktion auf. Das synchrone Ergebnis { accepted } gibt an, ob der Browser die Anfrage angenommen hat. Der Browser prüft noch, ob der Moduswechsel zulässig ist, und kann ihn verhindern. Lies den Zustand wie im Beispiel über isActive() und das Ereignis aus.

isActive() erfordert keine Nutzergeste. Der Browser aktualisiert den Zustand, bevor er oaiannotationmodechange auslöst. Dessen event.detail.active ist ein boolescher Wert. Der Browser sendet weder ein Anfangsereignis noch ein weiteres Ereignis, wenn der ausdrücklich angeforderte Zustand bereits besteht. Initialisiere deine Oberfläche daher mit dem Wert aus dem Getter. Wird der Zugriff bei aktivem Modus entzogen, meldet ein letztes Ereignis active: false. Ein zuvor gespeicherter Getter gibt dann false zurück.

Der Anmerkungsmodus fängt Klicks auf der Seite ab. Halte die Leertaste gedrückt, um die Bedienelemente der Seite zu nutzen, auch deine Schaltfläche zum Beenden. Alternativ kannst du den Modus über die Anmerkungsoberfläche des Browsers verlassen. Solange du nur die Leertaste gedrückt hältst, liefert isActive() weiterhin den Wert true. Die API unterstützt weder oai-annotation-ignore noch ein anderes Attribut, das Klicks durchlässt.

Beim Beenden schließt sich der Editor. Gespeicherte Anmerkungen bleiben erhalten. Sie werden weder gesendet noch in den Nachrichteneditor übernommen. Rufe cleanupAnnotationButton() auf, wenn du die Komponente entfernst. Dank der gespeicherten API-Referenz lassen sich die Listener beim Aufräumen auch dann entfernen, wenn der Namespace nicht mehr vorhanden ist.

Integration testen

Öffne deine Website im In-App-Browser der Desktop-App und teste die hinzugefügten Funktionen.

  1. Aktiviere den Anmerkungsmodus und wähle Objekte und Text aus. Prüfe, ob Hervorhebungen, Namen, Textbereiche und Metadaten den vorgesehenen Zielen entsprechen.
  2. Öffne eine Anmerkung über die Schaltfläche deiner Website. Prüfe das ausgewählte Element oder den Textbereich, den vorgegebenen Kommentar und den Modus des Editors.
  3. Ändere den Wert eines eigenen Bedienelements, vergleiche die Vorschau mit dem Original und setze sie zurück. Prüfe, ob deine Anwendung den ursprünglichen Zustand wiederherstellt.
  4. Teste bei Canvas-Inhalten leere Flächen, Größenänderungen und Änderungen an der Szene. Wechsle zwischen Objekten und prüfe, ob Ereignisse von Bedienelementen weiterhin das ursprünglich erfasste Ziel aktualisieren. Brich eine asynchrone Trefferprüfung ab und prüfe, ob sich danach weiterhin Objekte auswählen lassen.
  5. Speichere eine Anmerkung, öffne sie erneut über die Vorschau des Anhangs im Nachrichteneditor und bearbeite sie. Prüfe, ob sie ihre Bedienelemente und ihr Ziel behält und ob beim Entfernen der Anmerkung auch jede zugehörige Vorschau zurückgesetzt wird.
  6. Sende eine Anmerkung zusammen mit einer Nachricht. Prüfe, ob ChatGPT die ausgewählten Inhalte, die Metadaten und die angeforderten Werte erhält. Dazu gehören die sichtbaren Beschriftungen der ausgewählten Optionen und die beibehaltenen Anfangswerte bei Bedienelementen ohne currentValue.
  7. Öffne die Website in einem Browser ohne die API und prüfe, ob die üblichen Interaktionen weiterhin funktionieren.

Um Aktionen bereitzustellen, die ChatGPT auf deiner Website ausführen kann, füge Website-Tools (WebMCP) hinzu. Anmerkungen bringen die Auswahl und das Feedback der Person in das Gespräch ein. Mit Website-Tools kann der Agent auf Grundlage dieses Kontexts die vorhandenen Funktionen deiner Anwendung nutzen.