/accessibilityTree - 捕获无障碍树 · Cloudflare Browser Run docs

/accessibilityTree 端点指示浏览器导航到网站，并在 JavaScript 执行后捕获页面的无障碍树。无障碍树包括 role、name、value、state 和层级等与无障碍相关的信息。

端点

https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-run/accessibilityTree

必填字段

必须提供 url 或 html 之一：

url（字符串）
html（字符串）

常见使用场景

为 AI 智能体提供结构化页面表示，用于导航和浏览器自动化工作流
检查暴露给辅助技术的 role、accessible name、value 和 state
识别自动化工作流可以操作的交互元素，如按钮、链接、菜单和表单字段

基本用法

从 URL 捕获无障碍树

前往 https://example.com/ 并返回页面的无障碍树。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-run/accessibilityTree' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/"
}'

{
	"success": true,
	"result": {
		"accessibilityTree": {
			"role": "RootWebArea",
			"name": "Example Domain",
			"children": [
				{
					"role": "heading",
					"name": "Example Domain",
					"level": 1
				},
				{
					"role": "StaticText",
					"name": "This domain is for use in documentation examples without needing permission. Avoid use in operations."
				},
				{
					"role": "link",
					"name": "Learn more"
				}
			]
		}
	},
	"meta": {
		"status": 200,
		"title": "Example Domain"
	}
}

import Cloudflare from "cloudflare";

const client = new Cloudflare({
	apiToken: process.env["CLOUDFLARE_API_TOKEN"],
});

const accessibilityTree = await client.browserRendering.accessibilityTree.create({
	account_id: process.env["CLOUDFLARE_ACCOUNT_ID"],
	url: "https://example.com/",
});

console.log(accessibilityTree.accessibilityTree);

interface Env {
	BROWSER: BrowserRun;
}

export default {
	async fetch(request, env): Promise<Response> {
		return await env.BROWSER.quickAction("accessibilityTree", {
			url: "https://example.com/",
		});
	},
} satisfies ExportedHandler<Env>;

可选参数

以下可选参数可用于 /accessibilityTree 请求，除必填的 url 或 html 参数外。

可选参数	类型	描述
`interestingOnly`	布尔值	当为 `true` 时，仅返回语义上有意义的节点。默认为 `true`。如果设置了 `root` 且省略 `interestingOnly`，默认为 `false`。
`root`	字符串	将无障碍树锚定到子树的 CSS 选择器。如果选择器不匹配任何元素，`accessibilityTree` 返回 `null`。要在子树内仅返回语义上有意义的节点，请显式将 `interestingOnly` 设置为 `true`。

高级用法

包含所有节点

默认情况下，interestingOnly 为 true，会将响应过滤为语义上有意义的节点。将 interestingOnly 设置为 false 以包含无障碍树中的每个节点，包括通用和展示性节点。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-run/accessibilityTree' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "interestingOnly": false
}'

响应示例

{
	"success": true,
	"result": {
		"accessibilityTree": {
			"role": "RootWebArea",
			"name": "Example Domain",
			"children": [
				{
					"role": "generic",
					"name": "",
					"children": [
						{
							"role": "heading",
							"name": "Example Domain",
							"level": 1
						},
						{
							"role": "paragraph",
							"name": "",
							"children": [
								{
									"role": "StaticText",
									"name": "This domain is for use in documentation examples without needing permission. Avoid use in operations."
								}
							]
						},
						{
							"role": "paragraph",
							"name": "",
							"children": [
								{
									"role": "link",
									"name": "Learn more"
								}
							]
						}
					]
				}
			]
		}
	},
	"meta": {
		"status": 200,
		"title": "Example Domain"
	}
}

捕获子树

将 root 设置为 CSS 选择器字符串，以返回页面特定部分的无障碍树。

当设置了 root 且未提供 interestingOnly 时，interestingOnly 默认为 false。要将子树过滤为语义上有意义的节点，请显式将 interestingOnly 设置为 true。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-run/accessibilityTree' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "root": "h1",
    "interestingOnly": true
}'

{
	"success": true,
	"result": {
		"accessibilityTree": {
			"role": "heading",
			"name": "Example Domain",
			"level": 1
		}
	},
	"meta": {
		"status": 200,
		"title": "Example Domain"
	}
}

处理 root 选择器无匹配的情况

如果 root 不匹配页面上的任何元素，请求返回 HTTP 200，且 accessibilityTree 为 null。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-run/accessibilityTree' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "root": "#does-not-exist"
}'

{
	"success": true,
	"result": {
		"accessibilityTree": null
	},
	"meta": {
		"status": 200,
		"title": "Example Domain"
	}
}

处理 JavaScript 密集型页面

对于 JavaScript 密集型页面或单页应用（SPA），默认的页面加载行为可能返回空或不完整的结果。这是因为浏览器在 JavaScript 完成渲染内容之前就认为页面已加载完毕。

最简单的解决方案是将 gotoOptions.waitUntil 参数设置为 networkidle0 或 networkidle2：

{
	"url": "https://example.com",
	"gotoOptions": {
		"waitUntil": "networkidle0"
	}
}

如需更快响应，高级用户可使用 waitForSelector 等待特定元素，而非等待所有网络活动停止。这需要了解哪个 CSS 选择器表示所需内容已加载。更多详情，请参阅 Quick Actions 超时。

设置自定义 User Agent

可在 JSON 请求体的顶层传入 userAgent 参数，在页面级别更改 user agent。当目标网站根据 user agent 返回不同内容时很有用。

故障排除

如有疑问或遇到错误，请参阅 Browser Run 常见问题与故障排除指南。