透過瀏覽器註解 API,你可以自訂使用者在網站上能選取哪些內容、意見回饋會附帶哪些上下文,以及使用者在將註解傳送給 ChatGPT 前,可以用哪些控制項預覽變更。
在 ChatGPT Enterprise 和 ChatGPT Edu 工作區中,管理員必須透過工作區政策允許自訂網站註解。
你的網站無須修改程式碼,就能使用瀏覽器註解。使用者可以選取頁面的一部分、加上留言,再將註解放入上下文,傳送給 Codex 或 ChatGPT 工作。
開發人員可以透過瀏覽器註解 API,提供應用程式專屬的上下文或控制項。例如,你可以在設計系統的預覽頁面中附上各種元件變體的預覽,讓開發人員知道如何更新網站上的元件。
本指南的範例使用 TypeScript。請複製範例程式碼,存成 annotations.ts,再將它編譯成瀏覽器可執行的 JavaScript:
npm install --save-dev esbuild
npx esbuild annotations.ts --format=esm --outfile=annotations.js先將範例中的 HTML 元素加入頁面,再載入編譯好的模組:
<script type="module" src="./annotations.js"></script>如果應用程式已有 TypeScript 建置流程,直接將範例納入現有流程即可。
如果你想瞭解瀏覽器註解 API,或需要協助為網站加入註解功能,可以安裝「註解擴充」外掛程式。
安裝註解擴充外掛程式
在這份指南中實際體驗瀏覽器註解 API。
- 在 ChatGPT 的內建瀏覽器中開啟此頁面。
- 試著開啟這張卡片上顯示的建議提示詞。
- 進入註解模式,然後選取下方的表格或程式碼範例,即可切換預設版面配置和佈景主題。
- 你仍然可以為頁面上的任何項目加上註解,查看註解的預設行為。
選擇要自訂的功能
從適合你網站的整合方式開始:
本指南適用於 DevDay 2026 發布的 ChatGPT 桌面應用程式及後續版本。在應用程式的內建瀏覽器中,安全的頂層頁面(例如 HTTPS 或 localhost 頁面)可以透過 document.oai.annotation 存取 JavaScript API。啟用這項功能後,瀏覽器會在頁面指令碼執行前安裝 API。為了相容於舊版或不支援此 API 的瀏覽器,請先偵測各個方法是否可用,等整合功能所需的 DOM 元素建立後再初始化。無須等待就緒事件或輪詢。
API 方法會同步回傳,回傳的註冊控制代碼可立即使用。瀏覽器可以稍後再完成註解編輯器的載入。註解表面的 hitTest 回呼可以回傳 Promise。
自訂選取目標
註解模式預設會從頁面的 DOM 選取元素,優先選取文字、圖片和控制項等目標。若要讓使用者能選取較大的物件,請用 oai-annotation-container 標記物件所在的區域,再用 oai-annotatable 標記其中可選取的後代元素。
以下範例讓使用者能將整張圖表卡片當作單一物件選取:
<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>將指標移到卡片內任一位置,整張卡片就會反白顯示。你可以為 oai-annotatable 指定值,作為使用者和模型看到的物件名稱。請選用能區分鄰近物件的名稱,也可以省略這個值。
容器界定了這些選取規則的適用範圍。單獨使用 oai-annotatable 屬性不會改變選取行為。在容器內,瀏覽器會從包含指標下方元素的已標記目標中,選取最接近該元素的目標。容器有巢狀結構時,以最近一層容器為準。在容器內未標記的區域會建立網頁註解,在所有容器之外則維持預設行為。
啟用文字選取
在區域上加上 oai-annotation-container-text,使用者就能在註解模式中拖曳選取文字。這個屬性無須指定值:
<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>選取文字後放開指標,就會開啟文字註解編輯器,並帶入選取範圍及其上下文。如果只點擊而未選取文字,就不會建立註解。按下 Escape 或取消手勢都會取消選取。
手勢開始時的行為取決於最近一層文字或 DOM 選取容器。文字容器不會依據 oai-annotatable 標記選取元素。在容器內嵌入 oai-annotation-container,即可在內層恢復元素選取,嵌入文字容器則可恢復文字選取。如果同一元素具有這兩種容器屬性,則優先採用文字選取。
文字選取遵循頁面原有的選取規則,選取範圍可以延伸到起始容器之外。容器不會截斷選取範圍,也不會啟用 iframe 內的選取功能。在註解模式中,使用者仍可選取文字欄位中的文字,但一般的頁面點擊和控制項的原生操作仍會遭到攔截。明確呼叫 request() 時,行為維持不變。
必須同時啟用網站註解功能和個別網站的設定,文字選取容器才會在註解模式中生效。
為選取內容加入上下文
在已標記的目標上加上 oai-annotation-metadata,就能附上頁面上不一定看得到的上下文。例如,虛構的聯絡人資料列可以附上電子郵件地址,供要求草擬電子郵件時使用:
<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>在註解模式中選取聯絡人,即可在上下文中看到隨附的電子郵件地址。
選取其中任一行,都會選取整筆聯絡人資料。中繼資料會顯示在註解中,並隨註解一併帶入對話。請只附上你打算同時與使用者和模型分享的上下文。若要實際寄出電子郵件,仍須連接電子郵件工具。
請使用小型、無巢狀結構的 JSON 物件,並遵守下列限制:
- 最多六個屬性,值可以是字串、有限數值、布林值或
null。 - 鍵名最多 64 個字元,字串值最多 256 個字元。
- 物件序列化後最多 2,048 位元組。
鍵名必須以 ASCII 字母開頭,且只能包含 ASCII 字母、數字、空格、底線或連字號。單字之間請使用一個空格。不支援巢狀物件和陣列。瀏覽器會忽略無效的中繼資料。
你也可以透過 request() 或註解表面的 hitTest 結果提供中繼資料。
從網站開啟註解
請在使用者互動期間(例如按下按鈕時)直接呼叫 document.oai.annotation.request(target, options)。目標可以是已連接至目前文件且位於可視區域內的 HTML 元素,也可以是 DOM Range。目標不需要註解屬性。不支援虛擬物件 ID。
網站發起的請求可能需要使用者授權。使用者可以前往網站工具 > 註解功能,重新啟用已封鎖的註解功能。
以下範例會針對未設定選取屬性的段落開啟註解。請等兩個元素都建立後再執行指令碼:
<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.",
});
});選取詳細說明會要求瀏覽器開啟註解,其中已選取該段落,並附有可編輯的留言。使用者可以編輯並儲存註解,再隨訊息一併傳送。開啟註解不會向 ChatGPT 傳送訊息,只有使用者能送出訊息。
標準配送需要三至五個工作天。
務必在使用者互動仍有效時呼叫這個方法。如果先等待網路請求完成,屆時這次互動可能已失效。
第二個引數為選用,可包含以下欄位:
| 選項 | 行為 |
|---|---|
mode |
使用 "advanced" 開啟元素的進階控制項,或使用 "default" 採用編輯器的預設行為。預設值為 "default"。即使設為 "default",仍可能開啟自訂控制項,詳見編輯器預設模式。文字範圍僅支援 "default"。 |
enterAnnotationMode |
設為 true 會進入註解模式,並在取消或傳送註解後繼續停留在此模式。 |
omitScreenshot |
設為 true 時,這則註解不會附上自動擷取的螢幕截圖。預設值為 false,會維持原有的截圖行為。此選項適用於元素請求和文字範圍請求。 |
metadata |
有效且非空的中繼資料會在此次請求中取代目標的 HTML 中繼資料。如果目標是文字範圍,或目標元素位於 shadow DOM 內,則會忽略此選項。 |
initialComment |
提供可編輯的留言,最多 240 個 UTF-16 碼元。 |
request() 會回傳一個物件,其中包含布林值 accepted。若要確認瀏覽器是否已收到並驗證請求,請檢查 result.accepted,不要只檢查結果物件本身。這個值無法確認編輯器是否已開啟,也無法確認使用者是否已儲存或傳送註解。
編輯器載入期間,瀏覽器可以暫存一個已接受的請求。若有請求正在等候處理、編輯器已開啟,或 ChatGPT 正在控制瀏覽器,瀏覽器可能會拒絕另一個請求。
針對文字範圍請求註解
傳入 DOM Range,就能請使用者針對特定段落提供意見,而不必改變瀏覽器目前選取的文字。以下範例只選取醒目標示的詞組,不需要 oai-annotation-container-text 屬性:
<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>請等兩個元素都建立後再執行這段指令碼:
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.",
});
});試用期間享有完整存取權,為期 14 天。
只針對醒目標示的文字開啟註解。
範圍必須包含目前文件中非空且可見的文字,選取內容至少有一部分必須位於頁面的可視區域內。範圍最多可包含 20,000 個 UTF-16 碼元。不支援起點與終點重合的範圍、只含空白字元的文字、選取的隱藏文字,以及封閉式 shadow root 中的範圍。
文字範圍請求只使用預設文字編輯器。設定 mode: "advanced" 的請求會遭到拒絕。瀏覽器會忽略文字範圍請求中的中繼資料。已接受的請求等候編輯器期間,請讓目標文字保持可用,因為瀏覽器會在開啟編輯器前再次檢查範圍。文字選取容器則是另一項功能,可讓使用者在註解模式中拖曳選取文字。
選擇編輯器的預設模式
如果希望使用者透過瀏覽器的選取介面開啟註解時立即看到進階控制項,請在頁面的 <head> 中加入以下標籤:
<meta name="oai-annotation-editor-default-mode" content="advanced" />如果是透過網站自己的介面開啟註解,請將 { mode: "advanced" } 傳給 request()。若要採用編輯器的預設行為,請使用 mode: "default" 或省略此選項。頁面的 meta 設定不會覆寫這個請求選項。預設模式不一定只會顯示留言編輯器:如果自訂控制項提供了建議起始值,或省略了 currentValue,就可能開啟控制項編輯器。
只有在 Codex 或 localhost 上,才能手動使用調整、收合及按住 Option 鍵並點擊等操作。在 ChatGPT 中開啟已部署的網站時,已註冊的自訂控制項會自動顯示,介面上沒有調整或收合按鈕。頁面仍可請求使用進階模式。
新增自訂控制項
使用 registerControls() 將註解控制項與一個或多個 DOM 元素建立關聯。控制項可以用來預覽應用程式屬性的變更,例如調整間距設計代碼,也可以記錄使用者的選擇(例如電子郵件語氣),隨請求一併傳送。
預覽共用的間距設計代碼
以下範例中的兩張卡片使用同一個 CSS 屬性。直接在卡片上註冊控制項即可,不需要選取屬性:
<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>建立預覽後,執行這段指令碼:
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);
}個人資料卡片
摘要卡片
在註解模式中選取任一張卡片,然後變更「卡片內距(像素)」。視需要選取「調整」。兩張卡片會同步更新。
為任一張卡片加上註解,並將 卡片內距(像素) 從 16 改為 24。在 ChatGPT 中開啟已部署的網站時,控制項會自動顯示。在 Codex 或 localhost 上,請視需要選取調整。兩張卡片都會更新。註解會記錄標籤、參照,以及變更前後的值。清除預覽會還原原本的內距。移除元件時,請呼叫 disposeAnnotationControls()。
記錄使用者的選擇而不顯示預覽
以下範例讓使用者能針對一般段落選擇電子郵件的語氣,不需要選取屬性或中繼資料。請在段落建立後執行指令碼:
<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",
},
],
});這個控制項不會預覽頁面變更,因此不需要事件處理常式。省略 currentValue 後,即使使用者保留初始選項,瀏覽器也會將所選語氣納入註解。移除段落時,請呼叫 registration?.dispose()。
對於選單控制項,預覽回呼收到的是 option.value,例如 "professional"。註解記錄和 ChatGPT 收到的則是使用者看得到的 option.label,例如 "Professional"。原先的選項和新選取的選項都是如此。請使用能說明各選項意義的標籤,因為 value 中的內部 ID 不會作為選項文字傳送。
設定控制項和起始值
使用 controlsMode: "replace" 可讓已註冊的目標只顯示你的控制項,使用 "extend" 則會同時顯示你的控制項和內建控制項。你可以用 controlsHeading 指定面板標題。瀏覽器會去除標題首尾的空白,處理後的長度必須介於 1 到 80 個字元之間。如果沒有標題,面板會顯示元素的 HTML 標籤。傳送給 ChatGPT 的上下文不會包含面板標題。
每筆註冊最多支援 12 個控制項。每個控制項都必須有 type、使用者看得到的 label,以及 callback 識別碼。
依控制項變更的項目命名。 標籤應描述固定的屬性或設計用途,例如「頁面背景」、「品牌主色」或「強調色」。請避免以目前的值命名,例如「暖象牙白」或「深森林綠」。即使值改變,標籤仍應能說明控制項的用途。使用 currentValue 指定現有值,並用 reference 指定對應的設計代碼或屬性。
例如,下列控制項定義將標籤和色值分開設定:
const pageBackgroundControl = {
type: "color",
label: "Page background",
callback: "setPageBackground",
reference: "--color-background",
currentValue: "#f6f3ec",
};在註解模式中選取預覽區域,然後變更「頁面背景」。視需要選取「調整」。變更顏色時,標籤會維持不變。
支援的控制項類型如下:
| 類型 | 值 | 其他欄位 |
|---|---|---|
color |
十六進位色碼,例如 "#2563eb" |
無 |
range |
數值 | min、max 和 step |
select |
字串 | options,由 { label, value } 物件組成的陣列 |
toggle |
布林值 | 無 |
callback 是字串識別碼,而非 JavaScript 函式。同一筆註冊中的識別碼不可重複。識別碼必須以 ASCII 字母開頭,且只能使用 ASCII 字母、數字、底線或連字號。選用的 reference 用來識別要變更的屬性,並會與標籤和值一併納入註解。
請將 currentValue 設為屬性在正常編輯狀態下的有效值,包括尚未儲存的編輯。請勿以預覽狀態或尚未輸入完成的內容作為基準。瀏覽器會以此值比對變更前後的差異,並在重設時還原。應用程式狀態變更時,請使用 registration.update({ controls }) 更新控制項的 currentValue。更新會影響之後建立的註解,既有註解會保留先前記錄的值。
若要提供建議起始值,請設定 defaultValue。控制項初始化時,這個值的優先順序高於 currentValue。如果兩者都省略,顏色控制項會以白色開始,範圍控制項會使用最小值,選單會使用第一個選項,開關則會使用 false。
請將建議值與一般草稿分開管理。如果更新時擲出例外、請求失敗,或請求回傳 accepted: false,請捨棄這次嘗試套用的建議值,並還原先前的控制項和建議值狀態。如果請求已獲接受,請保留建議值,因為瀏覽器可能會先將請求加入佇列,稍後才擷取控制項。
驗證控制項與註冊資料
瀏覽器會依據下列限制驗證註冊和更新內容:
| 欄位或資源 | 限制 |
|---|---|
| 控制項 | 每筆註冊最多 12 個控制項,且 callback 識別碼不可重複。只能使用該控制項類型定義的欄位。 |
| 標籤和標題 | 控制項標籤、選項標籤和 controlsHeading 在去除首尾空白後不得為空,且最多 80 個 UTF-16 碼元。控制項文字不得包含控制字元或改變文字方向的字元。 |
| 識別碼 | callback 在去除首尾空白後最多 80 個 UTF-16 碼元,並須符合上述格式。reference 的長度為 1 至 80 個字元,可使用 ASCII 字母、數字及 _ . / : @ $ # -,不得包含空格。 |
| 選單選項 | 可提供 1 至 12 個選項,各選項的 value 字串不得重複,每個字串最多 512 個 UTF-16 碼元。凡有指定 currentValue 或 defaultValue,其值都必須符合其中一個選項的值。 |
| 範圍值 | min、max、currentValue 和 defaultValue 都必須是介於 −10,000 到 10,000 之間的有限數值。必須符合 min < max,且 step 必須介於 0.001 到 10,000 之間,不得大於 max - min。起始值必須在範圍內,但不必落在 step 定義的刻度上。 |
| 顏色和開關 | 色碼必須在 # 後接 3、4、6 或 8 個十六進位數字。開關值必須為 true 或 false。 |
| 目標 | 註冊時須提供 1 至 128 個目標,且都必須是目前文件中的元素。更新時可傳入 targets: [] 解除關聯。每份文件最多支援 64 筆控制項註冊,以及 1,024 組註冊與目標之間的關聯。 |
| 序列化後的控制項 | 包含 controls、controlsHeading 和 controlsMode 的 JSON 資料不得超過 16,384 個 UTF-16 碼元。請使用可編碼為 JSON 的資料,不得包含函式、Symbol 或大整數。 |
如果定義或目標無效,或超過限制,registerControls() 和 registration.update() 都可能同步擲出例外。在 dispose() 之後執行更新也會擲出例外。如果更新遭到拒絕,先前的註冊資料會保留下來,包括控制項和目標。請在呼叫這些方法的位置處理錯誤,讓一般編輯功能仍可使用,並重複使用或釋放你所管理的註冊,以免超過限制。
處理預覽與重設
oaiannotationcontrolchange 事件會從選取的元素向上冒泡。事件的 detail 包含 callback、value 和 action:
| 動作 | 套用所提供值的用途 |
|---|---|
preview |
顯示請求的變更。 |
preview-original |
暫時顯示原始狀態以供比較。 |
reset |
清除預覽時還原原始狀態。 |
請像間距範例一樣,對每個動作套用事件提供的值。事件處理常式所做的變更應可還原,且重複呼叫時仍能安全執行。預覽事件不會要求永久變更,請透過應用程式原有的儲存流程儲存。請分開管理一般草稿、尚未輸入完成的內容和預覽,避免不相關的編輯覆寫預覽。當使用者編輯同一項設定時,請取代該設定的預覽,並更新之後建立註解時使用的基準值。
請保留註冊控制代碼,以便更新和清理。呼叫 update() 時,可以任意組合 targets、controls、controlsHeading 和 controlsMode。省略的欄位會保留原值。例如,替換元件的 DOM 元素時,可使用 registration.update({ targets: newElement })。目標集合只記錄當下已存在的元素,不會追蹤日後才符合選取器條件的元素。
傳入 targets: [] 可解除註冊與目標的關聯,傳入 controls: [] 則可清空該筆註冊的控制項。移除整合功能時,請呼叫 dispose() 並移除事件監聽器。清理時也必須還原正常的顯示狀態:dispose() 只會移除控制項註冊,不會復原你為了預覽所做的變更。間距範例會移除用來覆寫樣式的行內設定,以還原原始 CSS 值。這兩個方法都會同步返回,不回傳任何值。更新會影響之後的選取操作,已儲存的註解則會保留當時記錄的控制項和目標。
控制項事件會以註解當時記錄的元素為目標。即使更新註冊的目標,既有註解也不會改指向新目標。已移除的元素仍可能觸發重設事件,因此原本父元素上的監聽器不會收到這些事件。
讓畫布物件可供選取
註解表面可讓應用程式識別繪製在畫布上的個別物件。使用 registerSurface() 註冊承載元素,並提供 hitTest 函式。命中物件時,函式應回傳含有穩定 id 的物件。命中空白區域時,則應回傳 null。
承載元素必須是已連接至安全頂層文件的 HTML 元素,且位於 shadow DOM 之外。不支援在 iframe 內註冊註解表面。
先實作物件選取與識別
以下範例繪製代表營收的長條,只使用 hitTest 和穩定的物件 ID,就能讓使用者選取它。請將指令碼放在畫布元素之後:
<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" };
},
});進入註解模式後選取一個圖形,即可在註解中看到它的名稱、ID 和填滿色彩。圖形之間的空白區域無法選取。
在上述程式碼範例中,使用者在註解模式下選取長條時,系統會將它識別為 revenue-this-quarter。同一註解表面內的物件 ID 應維持穩定。範例會針對空白區域回傳 null。
hitTest 可以回傳 Promise,也會收到一個 AbortSignal,可透過 signal 參數取得,以便取消已被新操作取代的工作。瀏覽器最多會等候 250 毫秒,逾時就會改用 DOM 選取。發生錯誤或結果無效時,也會改用 DOM 選取。如果命中測試成功執行但未命中任何物件,請明確回傳 null。
即使工作已取消,仍必須讓其 Promise 成功完成或遭到拒絕。瀏覽器一次只允許一個 hitTest 回呼執行,在 Promise 確定結果前都不會執行下一個回呼,即使工作已取消或逾時也是如此。如果由 worker 處理物件選取,請在工作中止時一併讓待處理的 Promise 完成或遭到拒絕。直接丟棄已取消工作的 worker 回應,可能會使後續的畫布選取無法執行。
移動物件或變更縮放比例後,請呼叫 surface?.invalidate()。移除整合功能時,請呼叫 surface?.dispose()。兩個方法都會同步返回,不回傳任何值。
加入選用的物件上下文
只需 id 就能識別物件。如果要提供顯示名稱、語意角色、未顯示的上下文或選取邊界,請將前述 hitTest 回呼中命中物件時的回傳敘述改成:
return {
id: "revenue-this-quarter",
name: "Revenue this quarter",
role: "chart-bar",
metadata: { metricId: "quarterly-revenue" },
rect,
};使用者可以看到選用的 name,而 role 則簡短說明物件的語意角色。只有在中繼資料能補充畫面上看不到的上下文時才加入。選用的 rect 以 CSS 像素表示相對於頁面可視區域的位置,與 clientX 和 clientY 使用相同的座標系統。前述選取範例已計算出這個矩形。從場景座標換算時,請將比例、平移和縮放都納入計算。
加入選用的選取效果
使用選用的 renderSelection 回呼,可以自行繪製指標懸停及選取時的視覺效果。這個回呼不需要任何選用的上下文欄位。
若要在上述畫布使用這項功能,請定義以下函式,並將 renderSelection: renderRevenueSelection 加入 registerSurface() 的選項:
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);
}
}當指標停在長條上,或長條已被選取時,這個回呼會重繪長條並加上外框。當兩個 ID 都是 null 時,重繪的長條就不會有外框。
為畫布物件加入控制項
請在註解表面的 DOM 元素上註冊自訂控制項。繪製出的物件在 API 中稱為虛擬物件,會使用你的自訂控制項。內建的 CSS 和文字控制項不適用於虛擬物件。
如果有多個物件,請使用 renderSelection 在 selectedId 變更時更新承載元素的控制項,並在瀏覽器擷取註解之前完成更新。控制項事件會包含 detail.virtualTarget: { surfaceId, targetId }。請根據事件記錄的物件身分和 callback 將事件交給對應的處理常式,不要以目前選取的物件為準。targetId 對應物件的 id,也就是 hitTest 回傳結果中的識別碼。surfaceId 則識別瀏覽器中註解表面的註冊記錄。一般 DOM 事件不包含 virtualTarget。
選取另一個物件後,預覽、比較和重設事件仍會保留原始物件的身分。重新開啟已儲存的註解時,不會重新執行命中測試來取代先前記錄的物件或中繼資料。
控制註解模式
使用 toggle() 請求切換模式,使用 isActive() 讀取已確認的狀態,並透過文件的 oaiannotationmodechange 事件讓介面與模式狀態保持同步。為了相容於舊版或不支援此 API 的瀏覽器,請先偵測這兩個方法是否可用。加入下列按鈕,等按鈕建立後再執行指令碼:
<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() 會反轉目前的模式狀態。傳入 true 可指定開啟,傳入 false 可指定關閉。重複以相同布林值提出請求,效果與提出一次相同。傳入 true 會保留已開啟的編輯器或尚待完成的啟用操作。傳入 false 則會取消尚待完成的啟用操作,並執行正常的退出流程。
請在使用者互動仍有效時呼叫 toggle()。同步回傳的 { accepted } 結果只能確認請求是否已獲接受,無法確認模式已切換。瀏覽器檢查啟用條件後,仍可能阻止切換。請依範例透過 isActive() 和事件讀取狀態。
isActive() 不需要使用者手勢。瀏覽器會先更新這個方法讀取的狀態,再發出 oaiannotationmodechange 事件。事件的 event.detail.active 是布林值。瀏覽器不會發出初始事件,明確指定的狀態若與目前相同,也不會重複發出事件。因此,請讀取目前狀態來初始化介面。如果在模式啟用時撤銷存取權,最後一個事件會回報 active: false,而先前保留的狀態讀取方法會回傳 false。
註解模式會攔截頁面點擊。按住空白鍵即可操作頁面控制項,包括網站上的退出按鈕。你也可以透過瀏覽器的註解介面退出。單純按住空白鍵時,isActive() 仍會回傳 true。此 API 不支援 oai-annotation-ignore 或其他能讓點擊直接傳遞至頁面的屬性。
退出模式會關閉編輯器並保留已儲存的註解,不會送出註解或將其移至撰寫工具。移除元件時,請呼叫 cleanupAnnotationButton()。即使命名空間已不存在,清理函式仍可使用先前保留的 API 參照移除監聽器。
測試整合功能
在桌面應用程式的內建瀏覽器中開啟你的網站,測試已加入的功能:
- 進入註解模式,選取物件和文字。確認反白效果、名稱、範圍和中繼資料都符合預期的目標。
- 使用網站上的按鈕開啟註解。確認選取的元素或文字範圍、初始留言和編輯器模式。
- 變更自訂控制項的值,與原始狀態比較,然後清除預覽。確認應用程式已還原原始狀態。
- 針對畫布內容,測試選取空白區域、調整大小和變更場景。切換物件,確認控制項事件仍會更新當時記錄的目標。取消一次非同步命中測試,確認之後仍可選取物件。
- 儲存註解,然後從撰寫工具的附件預覽重新開啟並編輯註解。確認註解保留了原本的控制項和目標,並確認移除註解時會一併清除相關預覽。
- 隨訊息一併傳送註解。確認 ChatGPT 收到選取內容、中繼資料和請求的值,包括使用者看得到的選項標籤,以及在省略
currentValue的控制項上維持不變的選擇。 - 在不支援此 API 的瀏覽器中開啟網站,確認一般互動仍可正常運作。
若要提供 ChatGPT 可在網站上執行的操作,請加入網站工具(WebMCP)。註解會將使用者選取的內容與意見帶入對話,而網站工具則讓智慧體能根據這些上下文,運用應用程式現有的功能執行操作。