> ## Documentation Index > Fetch the complete documentation index at: https://docs.brightdata.com/llms.txt > Use this file to discover all available pages before exploring further. # Scraper Studio 函数参考 > Bright Data Scraper Studio 交互函数与解析器函数的完整参考：导航、等待、选择器、标签、解析器辅助函数，含参数与示例。 本参考文档说明 Bright Data Scraper Studio IDE 中可用的每一个函数：用于控制浏览器会话的交互代码，以及将 HTML 转换为结构化记录的解析器代码。每个函数都列出其参数、返回值与一个可运行的示例。 标有 **⭐** 的函数仅在 Browser worker 中可用；如果从 Code worker 中调用，将会抛出错误。完整列表请参阅 [仅 Browser 可用函数](#browser-only-functions)。 ## 如何组织 Scraper Studio 代码？ 一个 Bright Data Scraper Studio 爬虫使用两种类型的代码： | 代码类型 | 作用 | 语言与库 | | ---------------------- | ------------------------------------ | ------------------------------ | | 交互代码（Interaction code） | 在目标站点中导航：发起 URL 请求、点击、滚动、等待，以及捕获后台流量 | JavaScript + Bright Data 浏览器命令 | | 解析器代码（Parser code） | 从交互代码返回的 HTML 中提取并组织数据 | JavaScript + Cheerio (`$`) | 通过 `parse()`（运行解析器）和 `collect()`（将一条记录追加到最终数据集中）在两者之间传递数据。 ## 交互函数 本文列出了在 IDE 中使用交互代码编写抓取器时可用的命令，并对其进行了说明。 ### `bad_input` 将抓取器输入标记为无效。将阻止任何抓取重试 `error_code=bad_input` ```js theme={null} bad_input(); bad_input('缺少搜索词'); ``` *** ### `blocked` 将页面标记为失败，因为网站拒绝访问 (error\_code=blocked) ```js theme={null} blocked(); blocked('显示了登录页面'); ``` *** ### ⭐ `bounding_box` 描述元素区域的坐标框（相对于页面，而非浏览器视口）。只会测量第一个匹配的元素。 * `selector`：元素的有效 CSS 选择器 ```js theme={null} let box = bounding_box('.product-list'); // box == { // top: 10, // right: 800, // bottom: 210, // left: 200, // x: 200, // y: 10, // width: 600, // height: 200, // } ``` *** ### ⭐ `browser_size` 返回当前浏览器窗口大小 ```js theme={null} TBD ``` *** ### ⭐ `capture_graphql` 捕获并重放 graphql 请求，同时更改变量 * options：控制要捕获的 graphql 请求的参数 * url * payload ```js Example #1 theme={null} let q = capture_graphql({ payload: {id: 'ProfileQuery'}, // 如果 graphql 端点不是默认值 "*/graphql"，则可能需要使用正则表达式传递 url 选项 // url: /\bgraphql\b/ // 默认值 }); navigate('https://example.com'); let [first_query, first_response] = q.wait_captured(); collect(first_response.data.profile); let second = q.replay({ variables: {other_id: 2}, }); collect(second.data.profile); ``` ```js Example #2 theme={null} let q = capture_graphql({ payload: {id: 'ProfileQuery'}, // 如果 graphql 端点不是默认值 "*/graphql"，则可能需要使用正则表达式传递 url 选项 // url: /\bgraphql\b/ // 默认值 }); navigate('https://example.com'); if (!q.is_captured()) click('#load_more'); let [first_query, first_response] = q.wait_captured(); collect(first_response.data.profile); let second = q.replay({ variables: {other_id: 2}, }); collect(second.data.profile); ``` *** ### ⭐ `click` 点击元素（会在元素出现后再点击） * `selector`：元素选择器 ```js theme={null} click('#show-more'); $('#show-more').click() // 点击与传入坐标最接近的元素（相对于页面）。 // 例如，点击地图中心的标记 let box = bounding_box('#map') let center = {x: (box.left+box.right)/2, y: (box.top+box.bottom)/2}; click('.map-pin', {coordinates: center}); ``` *** ### ⭐ `close_popup` 弹出窗口可能在抓取过程中随时出现，您不一定能确定何时等待或关闭它们。在代码顶部添加 `close_popup()` 可创建后台监视器，当弹出窗口出现时自动关闭。如果弹出窗口多次出现，它将始终被关闭 * popup selector：有效 CSS 选择器 * close selector：有效 CSS 选择器 * options：`click_inside`：包含关闭按钮选择器的父 iframe 选择器 ```js theme={null} close_popup('.popup', '.popup_close'); close_popup('iframe.with-popup', '.popup_close', {click_inside: 'iframe.with-popup'}); ``` *** ### `collect` 向爬虫创建的数据集中添加一行数据 **语法**：`collect([, ]);` * `data_line`：包含要收集字段的对象 * `validate_fn`：可选函数，用于检查数据行是否有效 ```js theme={null} collect({price: data.price}); collect(product, p=>{ if (!p.title) throw new Error('产品缺少标题'); }) ``` *** ### `console` 记录交互代码的消息 ```js theme={null} console.log(1, 'brightdata', [1, 2], {key: value}); console.error(1, 'brightdata', [1, 2], {key: value}); ``` *** ### `country` 配置抓取器从指定国家运行 **语法**：`country();` * `code`：2 位 ISO 国家代码 ```js theme={null} country('us'); ``` *** ### `dead_page` 将页面标记为死链接，以便在未来收集中进行过滤 `error_code=dead_page` ```js theme={null} dead_page(); dead_page('产品已移除'); ``` *** ### ⭐ `detect_block` 检测页面阻止 * `resource`：指定检测所需资源的对象 * `selector` * `condition`：指定资源如何处理以进行检测的对象 * `exists` * `has_text` ```js theme={null} detect_block({selector: '.foo'}, {exists: true}); detect_block({selector: '.bar'}, {has_text: 'text'}); detect_block({selector: '.baz'}, {has_text: /regex_pattern/}); ``` *** ### ⭐ `disable_event_listeners` 停止页面上所有事件监听器运行。必须先调用 `track_event_listeners()` * `event_types`：应禁用的特定事件类型 ```js theme={null} disable_event_listeners(); disable_event_listeners(['hover', 'click']); ``` *** ### `el_exists` 检查页面元素是否存在，并返回布尔值 * `selector`：有效 CSS 选择器 * `timeout`：等待元素出现的超时时间 ```js theme={null} el_exists('#example'); // => true el_exists('.does_not_exist'); // => false el_exists('.does_not_exist', 5e3); // => false（5 秒后） ``` *** ### `el_is_visible` 检查页面元素是否可见 * `selector`：有效 CSS 选择器 * `timeout`：等待元素可见的超时时间 ```js theme={null} el_is_visible('#example'); el_is_visible('.is_not_visible', 5e3); // false（5 秒后） ``` *** ### `embed_html_comment` 在页面 HTML 中添加注释。可用于在 HTML 快照中嵌入元数据。 * `comment`：注释内容 ```js theme={null} embed_html_comment('trace-id: asdf123'); ``` *** ### ⭐ `font_exists` 断言浏览器在页面上渲染指定字体家族的能力 **语法**：`font_exists();` ```js theme={null} font_exists('Liberation Mono'); ``` *** ### ⭐ `freeze_page` 强制页面停止变化，可用于在抓取后保存页面特定状态，以便快照看到的页面状态与当前一致。此命令为实验性，如发现问题，请报告支持 ```js theme={null} freeze_page(); ``` *** ### ⭐ `hover` 悬停在元素上（会在元素出现后再悬停） **语法**：`hover();` * `selector`：元素选择器 ```js theme={null} hover('#item'); ``` *** ### ⭐ `html_capture_options` 影响 HTML 捕获过程 * `options`：对象，定义 HTML 捕获应如何处理 * `coordinate_attributes` ```js theme={null} html_capture_options({ coordinate_attributes: true, }); ``` *** ### `Image` 收集图像数据 * `src`：图像 URL 或 data:image URI 字符串 ```js theme={null} let i = new Image('https://example.com/image.png'); collect({image: i}); ``` *** ### `input` 交互代码可用的全局对象，由触发输入或 `next_stage()` 提供 ```js theme={null} navigate(input.url); ``` *** ### `job` 交互代码可用的全局对象，由触发输入或 `next_stage()` 提供 ```js theme={null} let {created} = job; ``` *** ### `load_html` 加载 HTML 并返回 Cheerio 实例 * `html`：任意 HTML 字符串 ```js theme={null} let $$ = load_html('

p1

p2

'); collect({data: $$('#p2').text()}); ``` *** ### ⭐ `load_more` 滚动列表到底部以触发加载更多内容，适用于懒加载无限滚动网站 * `selector`：包含懒加载内容的元素选择器 ```js theme={null} load_more(); load_more('.search-results'); load_more('.search-results', {children: '.result-item', trigger_selector: '.btn-load-more', timeout: 10000}); ``` *** ### `load_sitemap` 从 sitemap xml 读取 URL 列表（支持 sitemap 索引和 .gz 压缩的 sitemap，见示例） ```js theme={null} let {pages} = load_sitemap({url: 'https://example.com/sitemap.xml.gz'}); let {children} = load_sitemap({url: 'https://example.com/sitemap-index.xml'}); ``` *** ### `location` 包含当前页面位置信息的对象。可用字段：href ```js theme={null} navigate('https://example.com'); location.href; // "https://example.com/" ``` *** ### Money 收集价格/货币数据 * `value`：金额 * `currency`：货币代码 ```js theme={null} let p = new Money(10, 'USD'); collect({product_price: p}); ``` *** ### ⭐ `mouse_to` 将鼠标移动到指定的 (x, y) 位置 **语法**：`mouse_to(, );` * `x`：目标 x 坐标 * `y`：目标 y 坐标 ```js theme={null} mouse_to(0, 0); ``` *** ### `navigate` 导航浏览器到指定 URL **语法**：`navigate();` * 默认情况下，404 状态码会抛出 `dead_page` 错误，可使用 opt.`allow_status` 覆盖 * `url`：要导航的 URL * `opt`：导航选项（见示例） ```js theme={null} navigate(input.url); navigate('https://example.com'); // 等待浏览器触发 DOM 内容加载事件 navigate(`url`, {wait_until: 'domcontentloaded'}); // 为导航添加 referer navigate(`url`, {referer: `url`}); // 等待毫秒数，默认 30000 ms navigate(`url`, {timeout: 45000}); // 如果 URL 返回 404 状态码，则不抛出错误 navigate(`url`, {allow_status: [404]}); // 指定浏览器宽高 navigate(`url`, { fingerprint: {screen: {width: 400, height: 400}}, }); ``` *** ### `next_stage` 使用指定输入运行爬虫的下一阶段 * `input`：传递给下一浏览器会话的输入对象 ```js theme={null} next_stage({url: 'http://example.com', page: 1}); ``` *** ### `parse` 解析页面数据 ```js theme={null} let page_data = parse(); collect({ title: page_data.title, price: page_data.price, }); ``` *** ### `preserve_proxy_session` 在该页面的子页面中保留代理会话 ```js theme={null} preserve_proxy_session(); ``` *** ### ⭐ `press_key` 在当前聚焦的输入框中输入特殊按键（如 Enter 或 Backspace，通常用于搜索框输入后） ```js theme={null} press_key('Enter'); press_key('Backspace'); ``` *** ### ⭐ `proxy_location` 配置爬虫从指定位置运行。除非需要高精度控制，否则通常使用 `country(code)` 即可 * `configuration`：指定代理位置的对象，详情见示例 ```js theme={null} proxy_location({country: 'us'}); // 纬度范围: [-85, 85], 经度范围: [-180, 180] proxy_location({lat: 37.7749, long: 122.4194}); // 半径单位为 km proxy_location({lat: 37.7749, long: 122.4194, country: 'US', radius: 100}); ``` *** ### ⭐ `redirect_history` 返回自上次导航以来的 URL 重定向历史 ```js theme={null} navigate('http://google.com'); let redirects = redirect_history(); // 返回: // [ // 'http://google.com', // 'http://www.google.com', // 'https://www.google.com/', // ] ``` *** ### `rerun_stage` 使用新输入重新运行当前阶段 ```js theme={null} rerun_stage({url: 'http://example.com/other-page'}); ``` *** ### `resolve_url` 返回给定 URL 参数最终指向的 URL * `url`：URL 字符串或实例 ```js theme={null} let {href} = parse().anchor_elem_data; collect({final_url: resolve_url(href)}); ``` *** ### `response_headers` 返回最后一次页面加载的响应头 ```js theme={null} let headers = response_headers(); console.log('content-type', headers['content-type']); ``` *** ### `request` 发起直接 HTTP 请求 * `url` | `options`：请求的 URL 或请求选项（见示例） ```js theme={null} let res = request('http://www.example.com'); let res = request({url: 'http://www.example.com', method: 'POST', headers: {'Content-type': 'application/json'}, body: {hello: 'world'}}) ``` *** ### ⭐ `right_click` 与 click 相同，但使用鼠标右键点击（会在元素出现后再点击） **语法**：`right_click();` * `selector`：元素选择器 ```js theme={null} right_click('#item'); ``` *** ### `run_stage` 使用新浏览器会话运行特定阶段 * stage：要运行的阶段（1 为第一阶段） * input：传递给下一浏览器会话的输入对象 ```js theme={null} run_stage(2, {url: 'http://example.com', page: 1}); ``` *** ### ⭐ `scroll_to` 滚动页面，使元素可见。如果用于触发懒加载列表加载更多元素，请使用 `load_more()`。默认滚动为自然滚动，可能需要几秒。如果想立即跳转，请使用 `{immediate: true}` **语法**：`scroll_to();` * `selector`：要滚动到的元素选择器 ```js theme={null} scroll_to('.author-profile'); scroll_to('top'); // 滚动到页面顶部 scroll_to('bottom'); // 滚动到页面底部 scroll_to('top', {immediate: true}); // 立即跳转到顶部 ``` *** ### ⭐ `scroll_to_all` 滚动页面，使所有匹配选择器的元素都可见 **语法**：`scroll_to_all();` * `selector`：要滚动的元素选择器 ```js theme={null} scroll_to_all('.author-profiles'); ``` *** ### ⭐ `select` 从 select 元素中选择一个值 **语法**：`select(