lexmount:browser

lexmount:browser 在任务中创建或接入云浏览器，用于采集网页、操作表单和保存页面。浏览器使用本次任务提交的项目身份，无需在代码中传入 API key，也不会向代码返回凭据或 CDP 地址。

import browser from 'lexmount:browser';

const session = await browser.create({ browserMode: 'normal' });
try {
  const page = await session.openUrl('https://example.com');
  console.log(page.title);
} finally {
  await session.destroy();
}

默认导出和具名导出 browser 指向同一个只读管理对象：import { browser } from 'lexmount:browser' 也可使用。参数采用 camelCase，返回的服务元数据采用 snake_case。

通用选项

选项对象均可省略；不支持的字段会报 TypeError。下列选项仅适用于明确接受它们的方法。

SessionOptions 同时包含 timeoutMs，ActionOptions 同时包含 timeoutMs。指定的 targetId 必须属于该会话且是未关闭的页面；需要连续操作同一页面时，先调用 targets()，然后复用同一个 ID。会话对象沿用接入时选择的区域。

会话管理

browser.create(options?)

功能： 创建云浏览器并等待其可用。

参数： 可选的 CreateOptions，包含 SessionOptions 和下表字段。除注明默认值外，省略字段由浏览器服务使用其默认配置。

返回值： Promise<BrowserSession>，成功时浏览器已可用。功能是否可用取决于项目权益及浏览器类型。创建失败或超时会拒绝，不会自动重试。

browser.get(sessionId, options?)

功能： 接入已有会话。

参数： sessionId: string 必填，为会话 ID；options?: SessionOptions 可指定区域和超时。

返回值： Promise<BrowserSession>。接入不会转移会话所有权，不会使已有会话在任务结束后自动销毁。

browser.list(options?)

功能： 查询当前项目的会话元数据。

参数： 可选的 SessionOptions，另支持 status?: 'active' | 'closed' 筛选状态。该接口未提供页码或每页数量参数。

返回值： Promise<SessionList>，包含 sessions: SessionInfo[]；可选 pagination 包含数字字段 currentPage、pageSize、totalCount、totalPages、activeCount、closedCount。此方法不返回 BrowserSession 操作句柄。

browser.destroy(sessionId, options?)

功能： 关闭指定会话并等待后端确认。

参数： sessionId: string 必填；options?: SessionOptions 可指定区域和超时。

返回值： Promise<void>。默认最多等待 180000 毫秒。

SessionInfo

browser.list() 的列表项和 session.getInfo() 使用同一种元数据结构：

Json 表示 null、布尔值、数字、字符串、这些值的数组或字符串键对象。

BrowserSession

会话句柄具有只读属性 sessionId: string，以及下列方法。

session.getInfo(options?)

功能： 读取该会话的当前状态与元数据。

参数： options?: TimeoutOptions。

返回值： Promise<SessionInfo>，字段见 SessionInfo。

session.targets(options?)

功能： 列出会话中的页面目标，用于选择 targetId。

参数： options?: TimeoutOptions。

返回值： Promise<{ session_id: string; targets: Target[] }>。每个 Target 包含字符串字段 id、type、title、url。

session.keepalive(options?)

功能： 在一段时间内定期查询会话状态，并保留查询快照。

返回值： Promise<{ session_id: string; checks: number; snapshots: SessionInfo[] }>，分别为会话 ID、检查次数和状态快照。

session.destroy(options?)

功能： 关闭此会话并等待后端确认。

参数： options?: TimeoutOptions，默认关闭确认超时 180000 毫秒。

返回值： Promise<void>。同一句柄重复调用会复用正在进行或已成功的关闭操作；关闭失败后可重试。

页面操作

以下方法的 options 均支持 ActionOptions；额外选项在各方法中列出。超时默认 30000 毫秒。

session.openUrl(url, options?)

功能： 导航选中的页面。

参数： url: string 必填，为目标地址；options?: ActionOptions。

返回值： Promise<{ navigation: Json; url: string; title: string }>，含导航结果、最终地址和页面标题。

session.eval(expression, options?)

功能： 在页面中执行 JavaScript 表达式并读取结果。

参数： expression: string 必填；options?: ActionOptions。

返回值： Promise<Json>。结果通过 JSON 值返回，不提供远程对象句柄。

session.waitSelector(selector, options?)

功能： 等待 CSS 选择器匹配元素。

参数： selector: string 必填且非空；options?: ActionOptions。

返回值： Promise<{ found: true; selector: string }>。等待超时会拒绝。

session.waitText(text, options?)

功能： 轮询页面文本，等待其出现或消失。

参数： text: string 必填，可为空字符串；options 除 ActionOptions 外支持：

返回值： Promise<WaitTextResult>。未达到条件时正常返回 timed_out: true，连接或协议失败仍会拒绝。

用 !result.timed_out 判断等待条件是否满足。等待 absent 成功时，found 和 matched 均为 false。

session.click(selector, options?)

功能： 点击 CSS 选择器指定的元素。

参数： selector: string 必填且非空；options?: ActionOptions。

返回值： Promise<true>，操作失败时拒绝。

session.fill(selector, value, options?)

功能： 填写 CSS 选择器指定的输入元素。

参数： selector: string 必填且非空；value: string 必填，允许空字符串；options?: ActionOptions。

返回值： Promise<true>，操作失败时拒绝。

session.screenshot(options?)

功能： 截取页面的 PNG 图片。

参数： 可选的 ActionOptions，另支持 fullPage?: boolean，默认 false，为 true 时截取完整页面。

返回值： Promise<Uint8Array>，为 PNG 原始字节。

session.pdf(options?)

功能： 将页面导出为 PDF。

参数： 可选的 ActionOptions，另支持 printBackground?: boolean，默认 false，决定是否打印背景。

返回值： Promise<Uint8Array>，为 PDF 原始字节。

session.snapshot(options?)

功能： 读取页面快照。

参数： options?: ActionOptions。

返回值： Promise<Json>，为含字符串字段 url、title、text、html 以及 interactive 数组的快照。interactive 最多包含 200 个交互元素，各项含 index: number、tag: string、text: string（最多 240 个字符）和可空的字符串 id、name、role。

session.raw(method, params?, options?)

功能： 向选中页面调用底层浏览器协议方法。

参数： method: string 必填且非空；params?: Record<string, Json> 默认为 {}；options?: ActionOptions。例如 raw('Page.getLayoutMetrics')。

返回值： Promise<Json>，为底层方法的结果；协议不支持的方法或非法参数会拒绝。

错误与清理

浏览器操作错误为带 name: 'BrowserError' 和字符串 code 的 Error；BrowserError 是类型声明，不是导出的运行时构造函数。按 error.code 区分失败，参数校验也可能直接抛出 TypeError。

create() 创建的会话在任务结束时会尝试回收，仍应在 finally 中显式 await session.destroy()。会话本身不会保持任务活动；本地任务结束不代表云端关闭已确认。get() 接入的会话由调用方安排关闭。

完整脚本见云浏览器示例，声明见 browser.d.ts。