> ## Documentation Index
> Fetch the complete documentation index at: https://brightdata-ipv6-release.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 函数
## 交互函数
本文列出并解释了交互代码中用于使用 IDE 编写抓取工具的可用命令。
标有星号 **⭐** 的命令是 Bright Data 开发的专有函数。
### `bad_input`
将抓取工具输入标记为不良。将阻止任何抓取重试 `error_code=bad_input`
```js theme={null}
bad_input();
bad_input('Missing search term');
```
***
### `blocked`
由于网站拒绝访问，将该页面标记为失败（ `error_code=blocked` ）
```js theme={null}
blocked();
blocked('Login page was shown');
```
***
### ⭐ `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}
待定
```
***
### ⭐ `capture_graphql`
捕获并重放具有已更改变量的 graphql 请求
* 选项：用于控制要捕获的 graphql 请求的参数
* url
* payload
```js Example #1 theme={null}
let q = capture_graphql({
payload: {id: 'ProfileQuery'},
// you may need to pass url opt as RegExp in case when
// graphql endpoint is not "*/graphql" which is default value
// url: /\bgraphql\b/ // default
});
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'},
// you may need to pass url opt as RegExp in case when
// graphql endpoint is not "*/graphql" which is default value
// url: /\bgraphql\b/ // default
});
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()
// Click the closest match to the passed coordinates
// (relative to the page).
// For example, clicking the center pin in a map
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 () 以添加后台观察程序，该观察程序将在弹窗出现时将其关闭。如果弹窗多次出现，将始终被关闭
* 弹窗选择器：有效的 CSS 选择器
* 关闭选择器：有效的 CSS 选择器
* 选项：click\_inside：包含关闭按钮选择器的父级 iframe 选择器
```js theme={null}
close_popup('.popup', '.popup_close');
close_popup('iframe.with-popup', '.popup_close', {click_inside: 'iframe.with-popup'});
```
***
### `collect`
向网络爬虫创建的数据集添加一行数据
**syntax**: `collect([, ]);`
* `data_line`: 包含要收集的字段的对象
* `validate_fn`: 用于验证行数据是否有效的可选函数
```js theme={null}
collect({price: data.price});
collect(product, p=>{
if (!p.title)
throw new Error('Product is missing a title');
})
```
***
### `console`
来自交互代码的日志消息
```js theme={null}
console.log(1, 'brightdata', [1, 2], {key: value});
console.error(1, 'brightdata', [1, 2], {key: value});
```
***
### `country`
将您的抓取配置为从特定国家/地区运行\
**syntax**: `country();`
* `code`: 2 个字符的 ISO 国家/地区代码
```js theme={null}
country('us');
```
***
### `dead_page`
将页面标记为无效链接，以便您可以从未来的收集中过滤掉它 `error_code=dead_page`
```js theme={null}
dead_page();
dead_page('Product was removed');
```
***
### ⭐ `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 (after 5 seconds)
```
***
### `el_is_visible`
检查元素在页面上是否可见
* `selector`: 有效的 CSS selector
* `timeout`: 等待元素在页面上可见的超时时间
```js theme={null}
el_is_visible('#example');
el_is_visible('.is_not_visible', 5e3); // false (after 5 seconds)
```
***
### `embed_html_comment`
在页面 HTML 中添加注释。可用于在 HTML 快照中嵌入元数据。
* comment: 注释的正文
```js theme={null}
embed_html_comment('trace-id: asdf123');
```
***
### ⭐ `font_exists`
确定浏览器在页面上渲染给定字体系列的能力\
**syntax**: `font_exists();`
```js theme={null}
font_exists('Liberation Mono');
```
***
### ⭐ `freeze_page`
强制页面停止进行更改。这可以用于将页面保存为特定状态，以便在抓取后运行的页面快照不会看到与现在看到的页面状态不同的页面状态。这个命令是实验性的。如果您发现问题，请向支持部门报告
```js theme={null}
freeze_page();
```
***
### ⭐ `hover`
悬停在元素上（将等待元素出现后再悬停在它上面）\
**syntax**: `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`
从站点地图 xml 中读取 url 列表（支持站点地图索引和 .gz 压缩站点地图。参见示例。）
```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) 位置\
**syntax**: `mouse_to(, );`
* `x`: 定位 x 位置
* `y`: 定位 y 位置
```js theme={null}
mouse_to(0, 0);
```
***
### `navigate`
将浏览器导航到 URL\
**syntax**: `navigate();`
* 默认情况下，404 状态代码会抛出 dead\_page 错误。使用 `opt.allow_status` 来覆盖它
* `url`: 要导航到的 URL
* `opt`: 导航选项（参见示例）
```js theme={null}
navigate(input.url);
navigate('https://example.com');
// waits until DOM content loaded event is fired in the browser
navigate(`url`, {wait_until: 'domcontentloaded'});
// adds a referer to the navigation
navigate(`url`, {referer: `url`});
// the number of milliseconds to wait for. Default is 30000 ms
navigate(`url`, {timeout: 45000});
// Don't throw an error if this URL sends a 404 status code
navigate(`url`, {allow_status: [404]});
// Specify browser width/height
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'});
// lat in range: [-85, 85], long in range: [-180, 180]
proxy_location({lat: 37.7749, long: 122.4194});
// radius in 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();
// returns:
// [
// '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`
与单击相同，但使用鼠标右键（等待元素出现后再单击）\
**syntax**: `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}`\
**syntax**: `scroll_to();`
* `selector`: 要滚动到的元素的选择器
```js theme={null}
scroll_to('.author-profile');
scroll_to('top'); // scroll to the top of the page
scroll_to('bottom'); // scroll to the bottom of the page
scroll_to('top', {immediate: true}); // jump to top of page immediately
```
***
### ⭐ `scroll_to_all`
滚动浏览页面，以便与选择器匹配的所有元素都显示在屏幕上\
**syntax**: `scroll_to_all();`
* `selector`: 想要滚动浏览的元素的选择权
```js theme={null}
scroll_to_all('.author-profiles');
```
***
### ⭐ `select`
从选择元素中选择一个值\
**syntax**: `select(