Ek açıklamaların genişletilebilirliği

Browser Annotation API, web sitenizde kullanıcıların neleri seçebileceğini, geri bildirimlerine hangi bağlamın eşlik edeceğini ve ChatGPT'ye ek açıklama göndermeden önce değişiklikleri önizlemek için hangi denetimleri kullanacaklarını özelleştirmenizi sağlar.

Tarayıcı ek açıklamaları, herhangi bir kod değişikliği olmadan sitenizde çalışır. Kullanıcılar sayfanın bir bölümünü seçebilir, yorum ekleyebilir ve bunu Bağlam içinde Codex'e veya ChatGPT Work'e gönderebilir.

Geliştirici olarak Browser Annotation API'yi kullanarak uygulamanıza özgü bağlam veya denetimler sağlayabilirsiniz. Örneğin, geliştiricilerin bir web sitesindeki bileşenleri nasıl güncelleyeceklerini bilmeleri için bir tasarım sistemi önizlemesine bileşen varyantlarının önizlemelerini ekleyebilirsiniz.

Browser Annotation API'yi anlamak veya web sitenize ek açıklama desteği eklemek için yardım almak üzere Annotations Extensibility eklentisini yükleyin.

Annotations Extensibility eklentisini yükleyin

Deneyin

Browser Annotation API'nin nasıl çalıştığını bu kılavuzda görün.

1. Bu sayfayı ChatGPT'nin yerleşik tarayıcısında açın.
2. Bu kartta görünecek önerilen prompt'ı açmayı deneyin.
3. Ek açıklama moduna girin, ardından önceden tanımlanmış düzenler ve temalar arasında geçiş yapmak için aşağıdaki tabloyu veya bir kod örneğini seçin.
4. Sayfadaki herhangi bir öğeye ek açıklama eklemeye devam edebilir ve varsayılan ek açıklama davranışını görebilirsiniz.

ChatGPT'nin tarayıcısında açın

Neyi özelleştireceğinizi seçin

Web sitenize uygun entegrasyonla başlayın:

Bu kılavuz, ChatGPT masaüstü uygulamasının DevDay 2026 sürümünü ve sonrasını hedefler. JavaScript API, uygulamanın yerleşik tarayıcısında document.oai.annotation üzerinden, HTTPS veya localhost gibi güvenli, üst düzey sayfalarda kullanılabilir. Etkinleştirildiğinde tarayıcı, sayfanızın betikleri çalışmadan önce API'yi yükler. Eski veya desteklenmeyen tarayıcıları desteklemek için her yöntemin kullanılabilirliğini kontrol edin, ardından DOM öğeleri oluştuktan sonra entegrasyonunuzu başlatın. Hazır olma olayı veya periyodik sorgulama gerekmez.

API yöntemleri eşzamanlı olarak döner ve kayıt tanıtıcıları hemen kullanılabilir. Tarayıcı, ek açıklama düzenleyicisini yüklemeyi daha sonra tamamlayabilir. Bir yüzeyin hitTest geri çağırma işlevi bir promise döndürebilir.

Seçim hedeflerini özelleştirin

Varsayılan olarak Ek açıklama modu, sayfanın DOM'undan öğeler seçerken metin, resim ve denetim gibi hedeflere öncelik verir. Daha büyük bir nesneyi seçilebilir hâle getirmek için onu içeren bölgeyi oai-annotation-container ile, seçilebilir alt öğelerini ise oai-annotatable ile işaretleyin.

Bu örnek, bir grafik kartını tek bir nesne olarak seçilebilir hâle getirir:

<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>

İşaretçiyi kartın herhangi bir yerine getirmek kartın tamamını vurgular. İsteğe bağlı oai-annotatable değeri, nesneye kullanıcıya ve modele gösterilen bir ad verir. Yakındaki nesneleri birbirinden ayıran adlar seçin veya değeri belirtmeyin.

Kapsayıcı, bu seçim kurallarının nerede geçerli olduğunu tanımlar. oai-annotatable özniteliği tek başına seçim davranışını değiştirmez. Tarayıcı, bir kapsayıcı içinde işaretçinin altındaki öğeyi içeren en yakın işaretli hedefi seçer. İç içe kapsayıcılarda en yakın kapsayıcı kullanılır. Kapsayıcı içindeki işaretlenmemiş alanlar bir web sayfası ek açıklaması oluşturur; tüm kapsayıcıların dışındaki alanlar varsayılan davranışı korur.

Metin seçimini etkinleştirin

Kullanıcıların Ek açıklama modunda sürükleyerek metin seçebilmesi için bir bölgeye oai-annotation-container-text ekleyin. Özniteliğe değer vermeniz gerekmez:

<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>

Boş olmayan bir seçimin ardından işaretçiyi bırakmak, seçilen aralık ve bağlamıyla birlikte metin ek açıklaması düzenleyicisini açar. Metin seçmeden tıklamak bir ek açıklama oluşturmaz. Escape tuşu veya iptal edilen bir hareket, seçimi iptal eder.

Bir hareketin nasıl başlayacağını en yakın metin veya DOM seçimi kapsayıcısı belirler. Metin kapsayıcıları, öğe seçimi için oai-annotatable işaretleyicilerini kullanmaz. Öğe seçimini geri getirmek için bir oai-annotation-container, metin seçimini geri getirmek için ise bir metin kapsayıcısını iç içe yerleştirin. Her iki öznitelik de aynı öğede bulunuyorsa metin seçimi önceliklidir.

Metin seçimi, sayfanın normal seçim kurallarına uyar ve başlangıç kapsayıcısının dışına uzanabilir. Kapsayıcı, aralığı kırpmaz veya bir iframe içinde seçimi etkinleştirmez. Metin alanları seçilebilir kalır; ancak Ek açıklama modunda normal sayfa tıklamaları ve denetimlerdeki yerel eylemler engellenmeye devam eder. Açıkça yapılan request() çağrıları mevcut davranışlarını korur.

Bir seçime bağlam ekleyin

Sayfada görünmeyebilecek bağlamı dahil etmek için işaretli bir hedefe oai-annotation-metadata ekleyin. Örneğin, kurgusal bir kişi satırı, bir e-posta taslağı hazırlama isteği için e-posta adresi içerebilir:

<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>

Satırlardan herhangi birini seçmek, kişi satırının tamamını seçer. Meta veriler ek açıklamayla birlikte görünür ve konuşmada ona eşlik eder. Yalnızca hem kullanıcıyla hem de modelle paylaşmayı amaçladığınız bağlamı dahil edin. E-posta göndermek için yine de bağlı bir e-posta aracı gerekir.

Şu sınırlara uyan küçük, düz bir JSON nesnesi kullanın:

• Dize, sonlu sayı, boolean veya null değerlerine sahip en fazla altı özellik.
• En fazla 64 karakterlik anahtarlar ve en fazla 256 karakterlik dize değerleri.
• Serileştirilmiş nesne için en fazla 2.048 bayt.

Anahtarlar bir ASCII harfiyle başlamalı ve yalnızca ASCII harfleri, rakamlar, boşluklar, alt çizgiler veya kısa çizgiler içermelidir. Sözcükler arasında tek boşluk kullanın. İç içe nesneler ve diziler desteklenmez. Tarayıcı geçersiz meta verileri yok sayar.

Meta verileri request() veya bir yüzeyin hitTest sonucu aracılığıyla da sağlayabilirsiniz.

Web sitenizden bir ek açıklama açın

document.oai.annotation.request(target, options) çağrısını, düğmeye basma gibi bir kullanıcı etkileşiminden doğrudan yapın. Hedef, mevcut belgenin görünür alanında yer alan, belgeye bağlı bir HTML öğesi veya bir DOM Range olabilir. Ek açıklama öznitelikleri gerekmez. Sanal nesne kimlikleri desteklenmez.

Sitenin başlattığı istekler kullanıcı izni gerektirebilir; kullanıcılar engellenen ek açıklama özelliklerini Site araçları > Ek açıklama özellikleri altından yeniden etkinleştirebilir.

Bu düğmeyi seçim örneğindeki grafik kartının yanına ekleyin, ardından her iki öğe de oluştuktan sonra betiği çalıştırın:

<button id="discuss-chart" type="button" hidden>Explain more</button>

const card = document.getElementById("chart-card");
const button = document.getElementById("discuss-chart");

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

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

  annotation.request(card, {
    initialComment: "Explain the latest trend in this graph.",
  });
});

Daha fazla açıkla seçeneğini seçmek, tarayıcıdan kartın seçili olduğu ve düzenlenebilir bir yorum içeren bir ek açıklama açmasını ister. Kullanıcı bunu düzenleyebilir, kaydedebilir ve mesajıyla birlikte gönderebilir. Ek açıklama açmak ChatGPT'ye mesaj göndermez; yalnızca kullanıcı bunu gönderebilir.

Çağrıyı etkin kullanıcı etkileşimi içinde tutun. Önce bir ağ isteğinin tamamlanmasını beklemek, bu etkileşimin kaybolmasına neden olabilir.

İsteğe bağlı ikinci bağımsız değişken şu alanları destekler:

request(), accepted boolean değeri içeren bir nesne döndürür. Tarayıcının isteği alıp doğruladığını görmek için sonuç nesnesi yerine result.accepted değerini kontrol edin. Bu değer, düzenleyicinin açıldığını veya kullanıcının bir ek açıklamayı kaydettiğini ya da gönderdiğini doğrulamaz.

Düzenleyici yüklenirken tarayıcı, kabul edilmiş bir isteği bekletebilir. Bir istek beklemedeyken, bir düzenleyici açıkken veya ChatGPT tarayıcıyı kontrol ederken başka bir isteği reddedebilir.

Bir metin aralığı için ek açıklama isteyin

Tarayıcının metin seçimini değiştirmeden bir metin bölümü hakkında geri bildirim istemek için bir DOM Range geçirin. Bu örnek paragrafın içeriğini seçer; oai-annotation-container-text özniteliğine gerek duymaz:

<p id="draft-passage">Leave more space between separate groups.</p>
<button id="discuss-passage" type="button" hidden>Discuss this passage</button>

Her iki öğe de oluştuktan sonra bu betiği çalıştırın:

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

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: "Suggest a clearer version of this guidance.",
  });
});

Aralık, mevcut belgede boş olmayan görünür metin içermeli ve seçimin en az bir bölümü sayfanın görünür alanında olmalıdır. En fazla 20.000 UTF-16 kod birimi içerebilir. Daraltılmış aralıklar, yalnızca boşluk içeren metin, seçili gizli metin ve kapalı shadow root içindeki aralıklar desteklenmez.

Metin aralığı istekleri yalnızca varsayılan metin düzenleyicisini kullanır. mode: "advanced" içeren bir istek reddedilir ve istek meta verileri yok sayılır. Kabul edilmiş bir istek düzenleyiciyi beklerken hedef metni erişilebilir tutun: tarayıcı, düzenleyiciyi açmadan önce aralığı yeniden kontrol eder. Metin seçimi kapsayıcıları ise kullanıcıların Ek açıklama modunda sürükleyerek metin seçmesini sağlar.

Düzenleyicinin varsayılan modunu seçin

Tarayıcının seçim arayüzü üzerinden açılan ek açıklamalarda gelişmiş denetimleri hemen göstermek için sayfanızın <head> bölümüne şu etiketi ekleyin:

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

Kendi arayüzünüzden açılan ek açıklamalar için { mode: "advanced" } değerini request() çağrısına geçirin. Varsayılan düzenleyici davranışı için mode: "default" kullanın veya bu değeri belirtmeyin. Sayfanın meta ayarı bu istek seçeneğini geçersiz kılmaz. Varsayılan mod, yalnızca yorum içeren bir düzenleyiciyi garanti etmez: önerilen başlangıç değerlerine sahip özel denetimler veya currentValue belirtmeyen denetimler, denetim düzenleyicisini açabilir.

Manuel Ayarla, daraltma ve Option tuşuyla tıklama denetimleri yalnızca Codex'te veya localhost üzerinde kullanılabilir. ChatGPT'de barındırılan sitelerde, kayıtlı özel denetimler Ayarla veya daraltma düğmesi olmadan otomatik olarak görünür. Sayfanın istediği gelişmiş mod burada da çalışır.

Özel denetimler ekleyin

Ek açıklama denetimlerini bir veya daha fazla DOM öğesiyle ilişkilendirmek için registerControls() kullanın. Denetimler, boşluk belirteci gibi uygulama özelliklerini önizleyebilir veya e-posta üslubu gibi, bir isteğe dahil edilecek tercihleri toplayabilir.

Ortak bir boşluk belirtecini önizleyin

Bu örnekteki her iki kart da aynı CSS özelliğini kullanır:

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

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

<section id="component-preview" oai-annotation-container>
  <article class="preview-card" oai-annotatable="Profile card">
    Profile card
  </article>
  <article class="preview-card" oai-annotatable="Summary card">
    Summary card
  </article>
</section>

Önizlemeyi oluşturduktan sonra bu betiği çalıştırın:

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

function previewSpacing(event) {
  const { callback, value } = event.detail;
  if (callback === "setCardPadding") {
    preview.style.setProperty("--card-padding", `${value}px`);
  }
}

let registration;
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);
}

Kartlardan birine ek açıklama ekleyin ve Kart iç boşluğu (piksel) değerini 16'dan 24'e değiştirin. ChatGPT'de barındırılan sitelerde denetimler otomatik olarak görünür; Codex'te veya localhost üzerinde gerekirse Ayarla seçeneğini seçin. Her iki kart da güncellenir. Ek açıklama etiketi, referansı, eski ve yeni değerleri kaydeder. Önizlemeyi temizlemek özgün iç boşluğu geri yükler. Bileşeni kaldırırken disposeAnnotationControls() çağrısını yapın.

Önizleme olmadan bir tercih toplayın

E-posta üslubu seçeneği sunmak için meta veri örneğindeki kişi satırını kullanın:

const contact = document.getElementById("contact-row");
const registration = document.oai?.annotation?.registerControls?.({
  targets: contact,
  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",
    },
  ],
});

Bu denetim, bir sayfa değişikliğini önizlemediği için olay işleyicisine gerek duymaz. currentValue değerini belirtmemek, kullanıcı başlangıç seçeneğini korusa bile tarayıcının seçili üslubu dahil etmesini sağlar. Satırı kaldırırken registration?.dispose() çağrısını yapın.

Seçim denetimlerinde, önizleme geri çağırma işlevleri option.value değerini alır; örneğin "professional". Ek açıklama geçmişi ve ChatGPT, hem önceki hem de seçili seçenek için görünür option.label değerini alır; örneğin "Professional". Her tercihi açıklayan etiketler kullanın; value içindeki dahili kimlikler, tercihin metni olarak gönderilmez.

Denetimleri ve başlangıç değerlerini yapılandırın

Kayıtlı hedefler için yalnızca kendi denetimlerinizi göstermek üzere controlsMode: "replace", bunları yerleşik denetimlerle birlikte göstermek üzere "extend" kullanın. İsteğe bağlı controlsHeading, paneli adlandırır. Tarayıcı, baştaki ve sondaki boşlukları kaldırır ve bir ile 80 karakter arasındaki değerleri kabul eder. Başlık yoksa panel öğenin HTML etiketini gösterir. Başlık, ChatGPT'ye gönderilen bağlama dahil edilmez.

Bir kayıt en fazla 12 denetimi destekler. Her denetim bir type, görünür label ve callback tanımlayıcısı gerektirir:

callback bir JavaScript işlevi değil, dize türünde bir tanımlayıcıdır. Kayıt içinde benzersiz olmasını sağlayın, bir ASCII harfiyle başlatın ve ASCII harfleri, rakamlar, alt çizgiler veya kısa çizgiler kullanın. İsteğe bağlı reference, değiştirilen özelliği tanımlar ve ek açıklamada etikete ve değere eşlik eder.

currentValue değerini, kaydedilmemiş düzenlemeler dahil olmak üzere özelliğin geçerli normal değerine ayarlayın. Temel değer olarak önizleme durumunu veya tamamlanmamış girdiyi kullanmayın. Tarayıcı bu değeri önceki ve sonraki değişiklikler ile sıfırlamalar için kullanır. Uygulama durumu değiştiğinde, denetimlerin currentValue değerlerini yenilemek için registration.update({ controls }) kullanın. Güncellemeler sonraki ek açıklamaları etkiler; mevcut ek açıklamalar yakalanan değerlerini korur.

Önerilen bir başlangıç değeri için defaultValue ayarlayın; denetimin başlangıç durumunda currentValue değerine göre önceliklidir. İkisini de belirtmezseniz denetim, renk için beyazla, aralık için en düşük değerle, seçim için ilk seçenekle veya açma-kapama denetimi için false değeriyle başlar.

Önerilen değerleri normal taslaklardan ayrı tutun. Bir güncelleme hata fırlatırsa veya bir istek başarısız olur ya da accepted: false döndürürse, uygulanmaya çalışılan öneriyi atın ve önceki denetimleri ve öneri durumunu geri yükleyin. Bir istek kabul edildiğinde önerileri koruyun: tarayıcı, denetimleri yakalamadan önce isteği kuyruğa alabilir.

Denetimleri ve kayıtları doğrulayın

Tarayıcı, kayıtları ve güncellemeleri şu sınırlara göre doğrular:

registerControls() ve registration.update(), geçersiz tanımlar, hedefler veya sınır aşımları için eşzamanlı olarak hata fırlatabilir. dispose() sonrasında yapılan bir güncelleme de hata fırlatır. Reddedilen bir güncelleme, denetimleri ve hedefleri dahil olmak üzere önceki kaydı korur. Hataları çağrı noktasında ele alın, normal düzenlemeyi kullanılabilir tutun ve sınırlar içinde kalmak için sahip olduğunuz kayıtları yeniden kullanın veya serbest bırakın.

Önizlemeleri ve sıfırlamaları işleyin

oaiannotationcontrolchange olayı seçili öğeden üst öğelere yayılır. detail alanı callback, value ve action içerir:

Boşluk örneğinde olduğu gibi, her eylem için sağlanan değeri uygulayın. İşleyicileri geri alınabilir ve tekrar tekrar çağrılması güvenli olacak şekilde hazırlayın. Önizleme olayları kalıcı bir değişiklik istemez; uygulamanızın normal kaydetme akışını kullanarak kaydedin. İlgisiz düzenlemelerin önizlemenin üzerine yazmaması için normal taslakları, tamamlanmamış girdileri ve önizlemeleri ayrı tutun. Birisi aynı ayarı düzenlediğinde, ayarın önizlemesini değiştirin ve sonraki ek açıklamalar için temel değerini güncelleyin.

Güncellemeler ve temizlik için kayıt tanıtıcısını saklayın. update(), targets, controls, controlsHeading ve controlsMode alanlarının herhangi bir birleşimini kabul eder. Belirtilmeyen alanlar önceki değerlerini korur. Örneğin, bir bileşenin DOM öğesini değiştirirken registration.update({ targets: newElement }) kullanın. Hedef koleksiyonları mevcut öğeleri yakalar ve gelecekteki seçici eşleşmelerini izlemez.

Kaydın bağlantısını kesmek için targets: [], denetimlerini temizlemek için controls: [] geçirin. Entegrasyonu kaldırırken dispose() çağrısını yapın ve olay dinleyicilerini kaldırın. Temizlik, normal görünümü de geri yüklemelidir: dispose() yalnızca denetim kaydını kaldırır ve önizleme değişikliklerinizi geri almaz. Boşluk örneği, özgün CSS değerini geri yüklemek için satır içi geçersiz kılmayı kaldırır. Her iki yöntem de bir değer döndürmeden eşzamanlı olarak tamamlanır. Güncellemeler sonraki seçimleri etkiler; kaydedilmiş ek açıklamalar, yakalanan denetimlerini ve hedeflerini korur.

Denetim olayları, ek açıklamanın yakaladığı öğeyi hedefler. Bir kaydın hedeflerini güncellemek mevcut ek açıklamaları yeniden yönlendirmez. Sıfırlama olayları, kaldırılmış bir öğede yine de tetiklenebilir; bu nedenle öğenin eski üst öğesindeki bir dinleyici bu olayları almaz.

Tuval nesnelerini seçilebilir hâle getirin

Ek açıklama yüzeyi, uygulamanızın bir tuval içinde çizilmiş nesneleri tek tek tanımlamasını sağlar. Ana öğeyi registerSurface() ile kaydedin ve sabit bir id içeren nesne veya boş alan için null döndüren bir hitTest işlevi sağlayın.

Ana öğe, güvenli ve üst düzey bir belgede, shadow DOM dışında bulunan, belgeye bağlı bir HTML öğesi olmalıdır. Bir iframe içinde yüzey kaydı desteklenmez.

Bu örnek bir gelir çubuğu çizer ve onu seçilebilir hâle getirir. Betiği tuvalden sonra yerleştirin:

<canvas id="revenue-canvas" width="480" height="240">
  Revenue this quarter: $120,000.
</canvas>

const canvas = document.getElementById("revenue-canvas");
const context = canvas.getContext("2d");
const bar = { x: 40, y: 60, width: 320, height: 100 };

function drawRevenue(highlighted = false) {
  context.clearRect(0, 0, canvas.width, canvas.height);
  context.fillStyle = "#2563eb";
  context.fillRect(bar.x, bar.y, bar.width, bar.height);
  if (highlighted) {
    context.strokeStyle = "#111827";
    context.lineWidth = 3;
    context.strokeRect(bar.x, bar.y, bar.width, bar.height);
  }
}

drawRevenue();

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",
      name: "Revenue this quarter",
      role: "chart-bar",
      metadata: { Metric: "Revenue", Value: 120000 },
      rect,
    };
  },
  renderSelection({ hoveredId, selectedId }) {
    drawRevenue(
      hoveredId === "revenue-this-quarter" ||
        selectedId === "revenue-this-quarter"
    );
  },
});

Ek açıklama modunda işaretçiyi çubuğun üzerine getirmek onu vurgular. Çubuğu seçmek, nesnenin adını, meta verilerini ve seçimin ekran görüntüsünü içeren bir ek açıklama açar.

Kimlikleri bir yüzey içinde sabit tutun. İsteğe bağlı name kullanıcıya görünür; role kısa bir anlamsal açıklama sağlar. İsteğe bağlı rect, sayfanın görünür alanına göre CSS piksellerini kullanır ve clientX ile clientY değerleriyle eşleşir. Ölçek, kaydırma ve yakınlaştırmayı dahil ederek sahne koordinatlarından dönüştürün.

hitTest bir promise döndürebilir ve yerini yeni bir işin aldığı çalışmayı iptal etmek için signal olarak bir AbortSignal alır. Tarayıcı, DOM seçimine geri dönmeden önce 250 milisaniye bekler. Hatalar ve geçersiz sonuçlar da bu geri dönüşe yol açar. Hiçbir nesne bulunmayan başarılı bir isabet testi için null değerini açıkça döndürün.

İptal edilen çalışma yine de promise sonucunu tamamlamalı veya reddetmelidir. Tarayıcı, aynı anda yalnızca bir hitTest geri çağırma işlevinin yürütülmesine izin verir ve iptal ya da zaman aşımından sonra bile promise sonuçlanana kadar bu yeri tutar. Seçimi bir worker yapıyorsa, çalışması durdurulduğunda bekleyen promise sonucunu tamamlayın; iptal edilmiş bir worker yanıtını yok saymak, sonraki tuval seçimlerini engelleyebilir.

Uygulamaya özgü geri bildirim için isteğe bağlı renderSelection geri çağırma işlevini kullanın. Her iki kimlik de null olduğunda geri bildirimi temizleyin. Nesneleri taşıdıktan veya yakınlaştırmayı değiştirdikten sonra surface?.invalidate(), entegrasyonu kaldırırken ise surface?.dispose() çağrısını yapın. Her ikisi de bir değer döndürmeden eşzamanlı olarak tamamlanır.

Tuval nesnelerine denetimler ekleyin

Özel denetimleri yüzeyin DOM öğesine kaydedin. API'de sanal nesneler olarak adlandırılan çizilmiş nesneler, özel denetimlerinizi kullanır; yerleşik CSS ve metin denetimleri bunlara uygulanmaz.

Birden fazla nesne için, tarayıcı ek açıklamayı yakalamadan önce, selectedId değiştiğinde ana öğenin denetimlerini güncellemek üzere renderSelection kullanın. Denetim olayları detail.virtualTarget: { surfaceId, targetId } içerir. Her olayı mevcut seçim yerine yakalanan bu kimliği ve onun callback değerini kullanarak yönlendirin. targetId, hitTest sonucundaki id ile eşleşir; surfaceId ise tarayıcının yüzey kaydını tanımlar. Normal DOM olayları virtualTarget içermez.

Önizleme, karşılaştırma ve sıfırlama olayları, başka bir nesne seçildikten sonra da özgün nesnenin kimliğini korur. Kaydedilmiş bir ek açıklamayı yeniden açmak, yakalanan nesnesini veya meta verilerini değiştirmek için isabet testini yeniden çalıştırmaz.

Ek açıklama modunu kontrol edin

Mod değişikliği istemek için toggle(), doğrulanmış durumu okumak için isActive() ve arayüzünüzü eşzamanlı tutmak için belgenin oaiannotationmodechange olayını kullanın. Eski veya desteklenmeyen tarayıcılar için her iki yöntemin kullanılabilirliğini kontrol edin. Bu düğmeyi ekleyin, ardından düğme oluştuktan sonra betiği çalıştırın:

<button id="toggle-annotations" type="button" hidden>
  Enter annotation mode
</button>

const button = document.getElementById("toggle-annotations");
const annotation = document.oai?.annotation;

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

const onModeChange = (event) => renderMode(event.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() modu tersine çevirir. Açık olduğundan emin olmak için true, kapalı olduğundan emin olmak için false geçirin. Aynı boolean değeriyle tekrarlanan istekler idempotenttir. true geçirmek etkin bir düzenleyiciyi veya bekleyen etkinleştirmeyi korur; false ise bekleyen etkinleştirmeyi iptal eder ve normal çıkış akışını kullanır.

toggle() çağrısını devam eden bir kullanıcı etkileşiminden yapın. Eşzamanlı { accepted } sonucu, doğrulanmış bir mod değişikliğini değil, isteğin alındığını bildirir. Tarayıcının uygunluk kontrolleri değişikliği yine de engelleyebilir. Örnekte olduğu gibi, durumu isActive() ve olay üzerinden okuyun.

isActive() bir kullanıcı hareketi gerektirmez. Tarayıcı, oaiannotationmodechange olayını göndermeden önce bu değeri günceller; olayın event.detail.active alanı bir boolean değeridir. Tarayıcı, başlangıç olayı veya durumu değiştirmeyen zorlanmış bir işlem için yinelenen olay göndermez; bu nedenle arayüzünüzü getter üzerinden başlatın. Mod etkinken erişim iptal edilirse, son bir olay active: false değerini bildirir ve saklanan getter false döndürür.

Ek açıklama modu, sayfa tıklamalarını yakalar. Çıkış düğmeniz dahil sayfa denetimlerini kullanmak için Boşluk tuşunu basılı tutun veya tarayıcının ek açıklama arayüzünden çıkın. Yalnızca Boşluk tuşunu basılı tutmak, isActive() değerini true olarak bırakır. API, oai-annotation-ignore veya tıklamaların geçmesine izin veren başka bir özniteliği desteklemez.

Çıkış, düzenleyiciyi kapatır ve kaydedilmiş ek açıklamaları göndermeden veya mesaj oluşturucuya taşımadan korur. Bileşeni kaldırırken cleanupAnnotationButton() çağrısını yapın. Saklanan API referansı, ad alanı kaybolmuş olsa bile temizlik sırasında dinleyicilerin kaldırılmasını sağlar.

Entegrasyonunuzu test edin

Web sitenizi masaüstü uygulamasının yerleşik tarayıcısında açın ve eklediğiniz özellikleri test edin:

1. Ek açıklama moduna girin ve nesneleri ve metni seçin. Vurguların, adların, aralıkların ve meta verilerin amaçlanan hedeflerle eşleştiğini kontrol edin.
2. Sitenizin düğmesinden bir ek açıklama açın. Seçili öğeyi veya metin aralığını, başlangıç yorumunu ve düzenleyici modunu kontrol edin.
3. Bir özel denetimi değiştirin, özgün hâliyle karşılaştırın ve önizlemeyi temizleyin. Uygulamanızın özgün durumu geri yüklediğini kontrol edin.
4. Tuval içeriği için boş alanı, yeniden boyutlandırmayı ve sahne değişikliklerini test edin. Nesneler arasında geçiş yapın ve denetim olaylarının yakalanan hedefi güncellemeye devam ettiğini doğrulayın. Eşzamansız bir isabet testini iptal edin ve sonraki seçimlerin hâlâ çalıştığını doğrulayın.
5. Bir ek açıklamayı kaydedin, mesaj oluşturucunun ek önizlemesinden yeniden açın ve düzenleyin. Denetimlerini ve hedefini koruduğunu, ayrıca kaldırıldığında tüm önizlemelerin temizlendiğini kontrol edin.
6. Bir mesajla birlikte ek açıklama gönderin. ChatGPT'nin seçili içeriği, meta verileri ve istenen değerleri aldığını doğrulayın; bunlara görünür seçim etiketleri ve currentValue belirtmeyen denetimlerdeki değişmemiş tercihler de dahildir.
7. Siteyi API'nin bulunmadığı bir tarayıcıda açın ve normal etkileşimlerin çalışmaya devam ettiğini doğrulayın.

ChatGPT'nin web sitenizde gerçekleştirebileceği eylemleri kullanıma sunmak için Site araçlarını (WebMCP) ekleyin. Ek açıklamalar, kullanıcının seçimini ve geri bildirimini konuşmaya taşır; site araçları ise ajanın uygulamanızın mevcut yetenekleri aracılığıyla bu bağlama göre hareket etmesini sağlar.