通过浏览器批注 API,您可以自定义网站上哪些内容可供用户选择、用户反馈附带哪些上下文,以及用户在向 ChatGPT 发送批注前可以用哪些控件预览更改。
在 ChatGPT Enterprise 和 ChatGPT Edu 工作空间中,管理员必须通过工作空间策略允许自定义站点批注。
您的网站无需更改代码即可使用浏览器批注。用户可以选择页面中的部分内容,添加评论,然后通过“上下文”将批注发送给 Codex 或 ChatGPT 工作。
作为开发者,您可以使用浏览器批注 API 提供应用特有的上下文或控件。例如,在展示设计系统时,您可以为组件的不同变体附上预览,让开发者了解如何更新网站上的组件。
本指南的示例使用 TypeScript。复制一个示例,将其保存为 annotations.ts,然后运行以下命令,将其编译为可在浏览器中运行的模块:
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 对象,并遵守以下限制:
- 最多包含 6 个属性,值可以是字符串、有限数值、布尔值或
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 元数据。如果目标是文本范围,或目标元素位于影子 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 码元。不支持折叠的范围、仅包含空白字符的文本、选中的隐藏文本,以及位于封闭影子根中的范围。
文本范围请求仅使用默认文本编辑器。浏览器会拒绝带有 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 的数据,不要包含函数、符号或大整数。 |
如果定义或目标无效,或超出限制,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 元素,且位于影子 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 选择。发生错误或结果无效时也会回退。如果命中测试成功执行但未命中对象,请显式返回 null。
即使任务已取消,也必须让其 Promise 最终兑现或拒绝。浏览器同一时间只允许运行一个 hitTest 回调。即使回调已取消或超时,浏览器也会等到 Promise 兑现或拒绝后才允许下一个回调运行。如果由工作线程处理选取,请在其任务中止时让待处理的 Promise 兑现或拒绝。直接丢弃已取消任务的工作线程响应,可能会阻塞后续的画布选取操作。
移动对象或更改缩放比例后,请调用 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 事件,让界面与实际状态保持同步。为兼容旧版浏览器或不支持这些方法的浏览器,请分别检测两个方法是否可用。添加以下按钮,并在按钮创建后运行脚本:
<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)。批注将用户选择的内容和反馈带入对话,站点工具则让智能体可以结合这些上下文,通过应用已有的功能执行操作。