> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/cn/web-scraper-api/features/js-rendering-and-browser-control.md).

# JS 渲染和浏览器控制

了解如何使用渲染参数，以及如何在网页爬虫API 中定义浏览器指令，以便抓取复杂的动态页面。

## JavaScript 渲染

如果您要抓取的页面使用 JavaScript 将数据加载到 DOM 中，请在请求中添加 `render` 参数。我们会先完整渲染页面，再以以下两种格式之一返回结果：

<table><thead><tr><th width="162.625">render 值</th><th>返回内容</th></tr></thead><tbody><tr><td><code>html</code></td><td>完整渲染后的页面原始 HTML</td></tr><tr><td><code>png</code></td><td>渲染后页面的 Base64 编码截图（PNG）</td></tr></tbody></table>

{% hint style="info" %}
如果您想抓取并下载图片，请参阅 [**本节**](https://developers.oxylabs.io/products/cn/web-scraper-api/features/result-processing-and-storage/output-types/download-images.md)**.**
{% endhint %}

### 请求示例

{% tabs %}
{% tab title="cURL" %}

```shell
curl --user "USERNAME:PASSWORD" \
'https://realtime.oxylabs.io/v1/queries' \
-H "Content-Type: application/json" \
-d '{"source": "universal", "url": "https://www.example.com", "render": "html"}'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
from pprint import pprint

# Structure payload.
payload = {
    'source': 'universal',
    'url': 'https://www.example.com',
    'render': 'html',
}

# Get response.
response = requests.request(
    'POST',
    'https://realtime.oxylabs.io/v1/queries',
    auth=('USERNAME', 'PASSWORD'),
    json=payload,
)

# Instead of response with job status and results url, this will return the
# JSON response with the result.
pprint(response.json())
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$params = [
    'source' => 'universal',
    'url' => 'https://www.example.com',
    'render' => 'html',
];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://realtime.oxylabs.io/v1/queries");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, "USERNAME" . ":" . "PASSWORD");

$headers = array();
$headers[] = "Content-Type: application/json";
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
echo $result;

if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);
```

{% endtab %}

{% tab title="C#" %}

```csharp
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

namespace OxyApi
{
    class Program
    {
        static async Task Main()
        {
            const string Username = "YOUR_USERNAME";
            const string Password = "YOUR_PASSWORD";

            var parameters = new Dictionary<string, string>()
            {
                { "source", "universal" },
                { "url", "https://www.example.com" },
                { "render" : "html" },
            };


            var client = new HttpClient();

            Uri baseUri = new Uri("https://realtime.oxylabs.io");
            client.BaseAddress = baseUri;

            var requestMessage = new HttpRequestMessage(HttpMethod.Post, "/v1/queries");
            requestMessage.Content = JsonContent.Create(parameters);

            var authenticationString = $"{Username}:{Password}";
            var base64EncodedAuthenticationString = Convert.ToBase64String(System.Text.ASCIIEncoding.UTF8.GetBytes(authenticationString));
            requestMessage.Headers.Add("Authorization", "Basic " + base64EncodedAuthenticationString);

            var response = await client.SendAsync(requestMessage);
            var contents = await response.Content.ReadAsStringAsync();

            Console.WriteLine(contents);
        }
    }
}
```

{% endtab %}

{% tab title="Go 语言" %}

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	const Username = "YOUR_USERNAME"
	const Password = "YOUR_PASSWORD"

	payload := map[string]string{
		"source": "universal",
		"url": "https://www.example.com",
        	"render": "html",
	}

	jsonValue, _ := json.Marshal(payload)

	client := &http.Client{}
	request, _ := http.NewRequest("POST",
		"https://realtime.oxylabs.io/v1/queries",
		bytes.NewBuffer(jsonValue),
	)

	request.SetBasicAuth(Username, Password)
	response, _ := client.Do(request)

	responseText, _ := ioutil.ReadAll(response.Body)
	fmt.Println(string(responseText))
}
```

{% endtab %}

{% tab title="Java" %}

```java
package org.example;

import okhttp3.*;
import org.json.JSONObject;

public class Main implements Runnable {
    private static final String AUTHORIZATION_HEADER = "Authorization";
    public static final String USERNAME = "YOUR_USERNAME";
    public static final String PASSWORD = "YOUR_PASSWORD";

    public void run() {
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("source", "universal");
        jsonObject.put("url", "https://www.example.com");
        jsonObject.put("render", "html");

        Authenticator authenticator = (route, response) -> {
            String credential = Credentials.basic(USERNAME, PASSWORD);

            return response
                    .request()
                    .newBuilder()
                    .header(AUTHORIZATION_HEADER, credential)
                    .build();
        };

        var client = new OkHttpClient.Builder()
                .authenticator(authenticator)
                .build();

        var mediaType = MediaType.parse("application/json; charset=utf-8");
        var body = RequestBody.create(jsonObject.toString(), mediaType);
        var request = new Request.Builder()
                .url("https://realtime.oxylabs.io/v1/queries")
                .post(body)
                .build();

        try (var response = client.newCall(request).execute()) {
            assert response.body() != null;
            System.out.println(response.body().string());
        } catch (Exception exception) {
            System.out.println("Error: " + exception.getMessage());
        }

        System.exit(0);
    }

    public static void main(String[] args) {
        new Thread(new Main()).start();
    }
}
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
import fetch from 'node-fetch';

const username = 'YOUR_USERNAME';
const password = 'YOUR_PASSWORD';
const body = {
  'source': 'universal',
  'url': 'https://www.example.com',
  'render': 'html'
};
const response = await fetch('https://realtime.oxylabs.io/v1/queries', {
  method: 'post',
  body: JSON.stringify(body),
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + Buffer.from(`${username}:${password}`).toString('base64'),
  }
});

console.log(await response.json());
```

{% endtab %}

{% tab title="JSON" %}

```json
{
    "source": "universal", 
    "url": "https://www.example.com", 
    "render": "html"
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
JavaScript 渲染会增加抓取页面所需的时间。如果使用 Realtime 或 Proxy Endpoint 集成方式，请在客户端将超时时间设置为 180 秒。
{% endhint %}

{% hint style="warning" %}
为确保流量消耗最低，我们的系统在页面渲染期间不会加载不必要的资源。
{% endhint %}

## 对特定页面强制渲染

为成功抓取数据，由于内容具有动态性，某些特定域名下的页面类型需要进行渲染。对于这些页面，我们的系统 **会自动强制渲染** 即使您没有设置 `render` 参数，也能确保您始终从这些原本难以抓取的页面中获取准确、可靠的数据。

{% hint style="warning" %}
请注意，与不进行渲染的任务相比，渲染任务会消耗更多流量。
{% endhint %}

如果您希望禁用渲染，可以在请求中添加以下参数：

```
"render": ""
```

受影响目标的完整列表保存在下方文件中。我们希望用户在抓取以下页面时充分了解这一点：

<details>

<summary>强制渲染的域名</summary>

<table><thead><tr><th valign="top">域名</th><th valign="top">渲染类别</th></tr></thead><tbody><tr><td valign="top"><code>acmemarkets</code></td><td valign="top"><code>product_pages</code></td></tr><tr><td valign="top"><code>adorebeauty</code></td><td valign="top"><code>product</code></td></tr><tr><td valign="top"><code>aeroin</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>agrizone</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>ajog</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>albertsons</code></td><td valign="top"><code>aisles</code>; <code>product_pages</code>; <code>search</code></td></tr><tr><td valign="top"><code>allegro</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>amazon</code></td><td valign="top"><code>amazon_bestsellers</code></td></tr><tr><td valign="top"><code>anbima</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>andronicos</code></td><td valign="top"><code>product_pages</code></td></tr><tr><td valign="top"><code>appliancesonline</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>aruodas</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>asda</code></td><td valign="top"><code>search</code></td></tr><tr><td valign="top"><code>auto5</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>avfoni</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>avito</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>b-parts</code></td><td valign="top"><code>product</code></td></tr><tr><td valign="top"><code>bakersplus</code></td><td valign="top"><code>product</code>; <code>category</code></td></tr><tr><td valign="top"><code>bedbathandbeyond</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>bergdorfgoodman</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>bestbuy</code></td><td valign="top"><code>site</code></td></tr><tr><td valign="top"><code>bevmo</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>bidfax</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>bilbasen</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>binglee</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>blibli</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>bloomingdales</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>book-secure</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>bookscouter</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>boulanger</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>canadagoose</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>canadiangamingbusiness</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>car</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>carfax</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>cargurus</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>carrefour</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>carrsqc</code></td><td valign="top"><code>product_pages</code></td></tr><tr><td valign="top"><code>carsales</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>carters</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>casasbahia</code></td><td valign="top"><code>search</code></td></tr><tr><td valign="top"><code>cec</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>ceneo</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>challenger</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>chewy</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>choicehotels</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>chrono24</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>citymarket</code></td><td valign="top"><code>product</code>; <code>category</code></td></tr><tr><td valign="top"><code>continentalwigs</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>costco</code></td><td valign="top"><code>products</code>; <code>categories (url)</code></td></tr><tr><td valign="top"><code>crunchbase</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>csod</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>cuinsight</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>darty</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>davidyurman</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>dillons</code></td><td valign="top"><code>product</code>; <code>category</code></td></tr><tr><td valign="top"><code>dergahtesbih</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>dextools</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>didi-food</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>didongviet</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>displays2go</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>ebay</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>ecsc-expat</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>edaboard</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>elcajonmitsubishi</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>elcapitalfinanciero</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>electroplanet</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>eraspace</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>etsy</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>exchange4media</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>expedia</code></td><td valign="top"><code>organic_requests</code></td></tr><tr><td valign="top"><code>extendedstayamerica</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>facebook</code></td><td valign="top"><code>marketplace</code></td></tr><tr><td valign="top"><code>fedex</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>flooranddecor</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>fmkorea</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>fotocasa</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>food4less</code></td><td valign="top"><code>product</code>; <code>category</code></td></tr><tr><td valign="top"><code>foodsco</code></td><td valign="top"><code>product</code>; <code>category</code></td></tr><tr><td valign="top"><code>fredmeyer</code></td><td valign="top"><code>product</code>; <code>category</code></td></tr><tr><td valign="top"><code>frysfood</code></td><td valign="top"><code>product</code>; <code>category</code></td></tr><tr><td valign="top"><code>g2</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>gerbes</code></td><td valign="top"><code>product</code>; <code>category</code></td></tr><tr><td valign="top"><code>glassdoor</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>gnc</code></td><td valign="top"><code>product</code></td></tr><tr><td valign="top"><code>goflink</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>google</code></td><td valign="top"><code>google_ai_mode</code>;<code>maps</code></td></tr><tr><td valign="top"><code>gopuff</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>grainger</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>greggyoungcdjratlantic</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>grofers</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>grok</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>haldex</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>harristeeter</code></td><td valign="top"><code>product</code>; <code>search</code>; <code>category</code>; <code>root</code></td></tr><tr><td valign="top"><code>harrods</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>harveynorman</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>hasznaltauto</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>headtopics</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>homecare</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>homedepot</code></td><td valign="top"><code>search</code></td></tr><tr><td valign="top"><code>homehardware</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>hyatt</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>hydradynellc</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>icrimewatch</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>ifood</code></td><td valign="top"><code>delivery</code></td></tr><tr><td valign="top"><code>immobilienscout24</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>indeed</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>instagram</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>interdiscount</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>intermarche</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>itsynergy</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>janesvillevw</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>jaycfoods</code></td><td valign="top"><code>product</code>; <code>category</code></td></tr><tr><td valign="top"><code>jbhifi</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>jewelosco</code></td><td valign="top"><code>product_pages</code></td></tr><tr><td valign="top"><code>kaina24</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>kayak</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>kingsoopers</code></td><td valign="top"><code>product</code>; <code>category</code></td></tr><tr><td valign="top"><code>kroger</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>laprensagrafica</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>latamairlines</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>lazada</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>leboncoin</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>leclercdrive</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>lexusofatlanticcity</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>lifestyleasia</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>loblaws</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>loccitane</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>lowes</code></td><td valign="top"><code>product</code></td></tr><tr><td valign="top"><code>loyalty360</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>luisaviaroma</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>macys</code></td><td valign="top"><code>brand</code>;<code>featured</code>;<code>product</code></td></tr><tr><td valign="top"><code>magazineluiza</code></td><td valign="top"><code>product</code></td></tr><tr><td valign="top"><code>marianos</code></td><td valign="top"><code>product</code>; <code>category</code></td></tr><tr><td valign="top"><code>master-outillage</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>mavs</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>mcmaster</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>medscape</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>menards</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>mercadolibre</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>mercadolivre</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>metromarket</code></td><td valign="top"><code>product</code>; <code>category</code></td></tr><tr><td valign="top"><code>milatcikolata</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>mister-auto</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>neimanmarcus</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>norauto</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>nordstrom</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>oocl</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>ozon</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>pay-less</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>pedidosya</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>petco</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>picknsave</code></td><td valign="top"><code>product</code>; <code>category</code></td></tr><tr><td valign="top"><code>pointp</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>powerbuy</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>pricerunner</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>printus</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>publix</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>qfc</code></td><td valign="top"><code>product</code>; <code>category</code></td></tr><tr><td valign="top"><code>radwell</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>ralphs</code></td><td valign="top"><code>product</code>; <code>category</code></td></tr><tr><td valign="top"><code>raptorsupplies</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>realadvisor</code></td><td valign="top"><code>api</code></td></tr><tr><td valign="top"><code>realestate</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>redfin</code></td><td valign="top"><code>localization</code></td></tr><tr><td valign="top"><code>reporteindigo</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>researchgate</code></td><td valign="top"><code>pdf</code></td></tr><tr><td valign="top"><code>reuters</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>ripley</code></td><td valign="top"><code>product_pages</code></td></tr><tr><td valign="top"><code>runnersneed</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>rvtrader</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>safeway</code></td><td valign="top"><code>aisles</code>;<code>product_pages</code>;<code>search</code></td></tr><tr><td valign="top"><code>sahibinden</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>saksfifthavenue</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>sbermarket</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>secure-hotel-booking</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>senheng</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>sephora</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>shaws</code></td><td valign="top"><code>product_pages</code></td></tr><tr><td valign="top"><code>shein</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>shi</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>shoppersdrugmart</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>similarweb</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>smappliance</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>smithsfoodanddrug</code></td><td valign="top"><code>product</code>; <code>category</code></td></tr><tr><td valign="top"><code>smythstoys</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>sobeys</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>sociolla</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>speedo</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>starmarket</code></td><td valign="top"><code>product_pages</code></td></tr><tr><td valign="top"><code>stockx</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>stupiddope</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>svastara</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>takealot</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>target</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>theaustralian</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>theiet</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>thenonprofittimes</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>thespaces</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>tiki</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>tiktok</code></td><td valign="top"><code>all</code>;<code>search</code>;<code>user</code></td></tr><tr><td valign="top"><code>tmall</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>tomthumb</code></td><td valign="top"><code>product_pages</code></td></tr><tr><td valign="top"><code>tractorsupply</code></td><td valign="top"><code>search</code></td></tr><tr><td valign="top"><code>trendyol</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>truckpaper</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>truclothing</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top">truepeoplesearch</td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>upwork</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>vimeo</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>vivadodgeramfiat</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>vons</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>wabco-customercentre</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>walmart</code></td><td valign="top"><code>geo_location</code>; <code>search_with_video</code></td></tr><tr><td valign="top"><code>watchfinder</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>weismarkets</code></td><td valign="top"><code>organic</code></td></tr><tr><td valign="top"><code>wine</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>winoui</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>wipo</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>worten</code></td><td valign="top"><code>products</code></td></tr><tr><td valign="top"><code>wyndhamhotels</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>yelp</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>zalando</code></td><td valign="top"><code>all</code></td></tr><tr><td valign="top"><code>zoro</code></td><td valign="top"><code>all</code></td></tr></tbody></table>

</details>

## 浏览器指令

当页面需要交互时，例如点击按钮、输入搜索词或滚动以加载更多项目，你可以自定义 `browser_instructions` ，这些指令会在页面渲染时运行。

{% hint style="success" %}
构建浏览器指令最简单的方法是使用 [网页爬虫API Playground](https://dashboard.oxylabs.io/?route=/api-playground)中的 AI 可视化构建器。了解详情，请点击 [此处](https://developers.oxylabs.io/products/cn/web-scraper-api/web-scraper-api-playground/oxycopilot.md#browser-instruction-builder).
{% endhint %}

### 快速入门

首先，浏览器指令需要指定 `render` 参数，可以是 `html` 或 `png`，并以列表形式提供给 `browser_instructions` 字段。列表中的每一项都会按顺序执行。

假设你想搜索 `pizza boxes` 在网站上——在搜索框中输入搜索词，点击搜索按钮，并等待 5 秒让结果加载：

```json
{
    "source": "universal",
    "url": "https://www.etsy.com/",
    "render": "html",
    "browser_instructions": [
        {
            "type": "input",
            "value": "pizza boxes",
            "selector": {
                "type": "css",
                "value": "#global-enhancements-search-query"
            }
        },
        {
            "type": "click",
            "selector": {
                "type": "css",
                "value": "button[data-id='gnav-search-submit-button']"
            }
        },
        {
            "type": "wait",
            "wait_time_s": 5
        }
    ]
}
```

指令运行后，结果中会包含 HTML：

```json
{
  "results": [
    {
      "content": "<!DOCTYPE html><html lang=\"en-US\">  Search results for \"pizza boxes\"  </html>",
      "created_at": "2026-08-19 12:23:06",
      "updated_at": "2026-08-19 12:23:24",
      "page": 1,
      "url": "https://www.etsy.com/search?q=pizza+boxes&ref=search_bar&instant_download=false",
      "job_id": "7495817623108602881",
      "is_render_forced": false,
      "type": "raw",
      "status_code": 200
    }
  ]
}
```

抓取到的 HTML 应如下所示：

<figure><img src="https://3714446197-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-c2baf702d27346d7b1f44fb7493f478456ba8520%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

#### 获取浏览器资源 <a href="#fetching-browser-resources" id="fetching-browser-resources"></a>

我们提供了一条独立的浏览器指令，用于获取浏览器资源。

此函数定义如下：

使用 `fetch_resource` 将使作业返回第一个符合所提供格式的 Fetch/XHR 资源，而不是目标 HTML。

假设我们想要定位一个 GraphQL 资源，该资源是在浏览器中正常访问产品页面时获取的。我们将按如下方式提供作业信息：

```json
{
    "source": "universal",
    "url": "https://petstore.swagger.io/",
    "render": "html",
    "browser_instructions": [
        {
            "type": "fetch_resource",
            "filter": "/v2/swagger.json"
        }
    ]
}
```

这些指令将产生如下结果：

```json
{
    "results": [
        {
            "content": "{\"swagger\":\"2.0\",\"info\":{\"description\":\"This is a sample server Petstore server. ...",
            "created_at": "2026-09-17 12:27:43",
            "updated_at": "2026-09-17 12:28:29",
            "page": 1,
            "url": "https://petstore.swagger.io/v2/swagger.json",
            "job_id": "7506328031753955329",
            "status_code": 200
        }
    ],
    "job": {...}
}
```

## 支持的浏览器指令列表 <a href="#list-of-supported-browser-instructions" id="list-of-supported-browser-instructions"></a>

### 通用参数

下面定义的所有指令都使用一组一致的参数，具体如下：

#### `type` <a href="#type" id="type"></a>

* **类型**: `Enum["click", "input", "scroll", "scroll_to_bottom", "wait", "wait_for_element", "fetch_resource"]`
* **说明：** 浏览器指令类型。
* **必需**: `true`

#### `timeout_s` <a href="#timeout_s" id="timeout_s"></a>

* **类型**: `int`
* **说明：** 如果未能及时完成操作，等待多久后跳过该操作。
* **限制**: 0 < `timeout_s` <= 60
* **默认值**: 5

#### `wait_time_s` <a href="#wait_time_s" id="wait_time_s"></a>

* **类型**: `int`
* **说明：** 执行下一项操作前等待的时长。
* **限制**: 0 < `wait_time_s` <= 60
* **默认值**: 0

#### `on_error` <a href="#on_error" id="on_error"></a>

* **类型**: `Enum["error", "skip"]`
* **说明：** 此指令失败时，指示如何处理后续指令：
  * `"error"`：停止执行浏览器指令。
  * `"skip"`：继续执行下一条指令。
* **默认值**: `"error"`

#### 通用参数示例

```json
{
    "type": "wait_for_element",
    "selector": {
        "type": "text",
        "value": "Load More Items"
    },
    "timeout_s": 5,
    "wait_time_s": 2,
    "on_error": "skip"

}
```

### 指令 <a href="#click" id="click"></a>

#### `click` <a href="#click" id="click"></a>

* **说明**：点击一个元素，并等待指定秒数。
* **参数：**
  * `type: str = "click"`
  * `selector: dict`
    * `type: Enum["xpath", "css", "text"]`
    * `value: str`

**示例**:

```json
{
    "type": "click",
    "selector": {
        "type": "xpath",
        "value": "//button"
    }
}
```

#### `input` <a href="#input" id="input"></a>

* **说明**：在选定的元素中输入文本。
* **参数：**
  * `type: str = "input"`
  * `selector: dict`
    * `type: Enum["xpath", "css", "text"]`
    * `value: str`
  * `value: str`

**示例：**

```json
{
    "type": "input",
    "selector": {
        "type": "xpath",
        "value": "//input"
    },
    "value": "pizza boxes"
}
```

#### `scroll` <a href="#scroll" id="scroll"></a>

* **说明**：滚动指定的像素数。
* **参数：**
  * `type: str = "scroll"`
  * `x: int`
  * `y: int`

**示例：**

```json
{
    "type": "scroll",
    "x": 0,
    "y": 100
}
```

#### `scroll_to_bottom` <a href="#scroll_to_bottom" id="scroll_to_bottom"></a>

* **说明**：在指定的秒数内滚动到底部。
* **参数：**
  * `type: str = "scroll_to_bottom"`

**示例**:

```json
{
    "type": "scroll_to_bottom",
    "timeout_s": 10
}
```

#### `wait` <a href="#wait" id="wait"></a>

* **说明**：等待指定的秒数。
* **参数：**
  * `type: str = "wait"`

**示例**:

```json
{
    "type": "wait",
    "wait_time_s": 2
}
```

#### `wait_for_element` <a href="#wait_for_element" id="wait_for_element"></a>

* **说明**：等待元素加载，最长等待指定的秒数。
* **参数：**
  * `type: str = "wait_for_element"`
  * `selector: dict`
    * `type: Enum["xpath", "css", "text"]`
    * `value: str`

**示例：**

```json
{
    "type": "wait_for_element",
    "selector": {
        "type": "text",
        "value": "Load More Items"
    },
    "timeout_s": 5
}
```

#### `fetch_resource` <a href="#fetch_resource" id="fetch_resource"></a>

{% hint style="warning" %}
此 `fetch_resource` 指令必须是浏览器指令列表中的最后一条指令；之后的任何指令都不会执行。
{% endhint %}

* **说明**：获取第一个与指定模式匹配的 Fetch/XHR 资源。
* **参数：**
  * `type: str = "fetch_resource"`
  * `filter: str(RegEx expression)`
  * `on_error: Enum["error", "skip"]`

**示例：**

```json
{
    "type": "fetch_resource",
    "filter": "/graphql/item/"
}
```

### 指令验证

指令格式中的任何不一致都会导致返回 `400` 状态码和相应的错误消息。

例如，以下负载：

```json
{
    "source": "universal",
    "url": "https://www.example.com/",
    "render": "html",
    "browser_instructions": [
        {
            "type": "unsupported-wait",
            "wait_time_s": 5
        }
    ]
}
```

将导致：

```json
{    
    "errors": {
        "message": "不支持操作类型 `unsupported-wait`，请选择以下类型之一：'click,fetch_resource,input,scroll,scroll_to_bottom,wait,wait_for_element'"
    }
}
```

## 故障排查 <a href="#status-codes" id="status-codes"></a>

### 状态码 <a href="#status-codes" id="status-codes"></a>

请参阅我们列出的响应代码 [**此处**](https://developers.oxylabs.io/products/cn/web-scraper-api/response-codes.md)。有关指令验证的状态代码，详见 [**此处**](#instruction-validation).

### 错误和警告

如果浏览操作导致错误或警告，您可以在结果中通过以下键查看： `browser_instructions_error` 或 `browser_instructions_warnings`。例如，如果您发送了以下浏览器指令，但页面上找不到预期的 `xpath` ，结果中会包含一条警告。

`browser_instructions`:

```json
[
    {
        "type": "input", 
        "selector": {
            "type": "xpath",
            "value": "//input[@type='search']"
        },
        "value": "oxylabs"
    }
]
```

结果：

```json
{
  "results": [
    {
      "content": "<!doctype html><html>
        执行指令后的内容      
      </html>",
      "created_at": "2023-10-11 11:35:23",
      "updated_at": "2023-10-11 11:36:08",
      "browser_instructions_warnings": [
        {
          "action_type": "click",
          "msg": "Unable to find selector type `xpath` with value `//input[@type=search]` on the page."
        },
      ],
      "page": 1,
      "url": "https://example.com",
      "job_id": "7117835067442906113",
      "status_code": 200
    }
  ]
}

```

| 可能出现的错误和警告                                           |
| ---------------------------------------------------- |
| 将浏览器指令转换为操作时发生意外错误。                                  |
| 执行浏览器指令时发生意外错误： `{action.type}` 操作。                  |
| 操作 `{action.type}` 超时。                               |
| 找不到选择器类型 `{selector.type}` ，其值为 `{selector.value}` 。 |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/cn/web-scraper-api/features/js-rendering-and-browser-control.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
