DrissionPage

https://www.drissionpage.cn
Admin
DrissionPage is a powerful Python-based web automation tool that can control browsers, send/receive...
Tokens:287,967
Snippets:2,221
Trust Score:6.2
Update:1 week ago
Show doc for...
Tokens:
Raw
### Initiate download with download()

Source: https://www.drissionpage.cn/download/intro

Uses the download() method to actively start a file download. This method is based on requests and automatically synchronizes cookies.

```python
from DrissionPage import SessionPage  
  
page = SessionPage()  
page.download('https://dldir1.qq.com/qqfile/qq/TIM3.4.8/TIM3.4.8.22092.exe')  
```

--------------------------------

### console.start()

Source: https://www.drissionpage.cn/browser_control/console

Starts listening for console messages. This method must be called before using wait(), steps(), or messages to capture console output.

```APIDOC
## console.start()

### Description
Starts listening for console messages.

### Method
console.start()

### Parameters
None

### Returns
None

```

--------------------------------

### wait.download_begin()

Source: https://www.drissionpage.cn/download/browser

Waits for a download to start. Can be used on a Tab object for tab-triggered downloads or on a Chromium object for downloads from uncontrolled tabs.

```APIDOC
## wait.download_begin()

### Description
Waits for a download to start. Can be used on a Tab object for tab-triggered downloads or on a Chromium object for downloads from uncontrolled tabs.

### Method
wait.download_begin()

### Parameters
- **timeout** (float) - Optional - Timeout in seconds. None uses the page default wait time.
- **cancel_it** (bool) - Optional - If True, cancels the task when caught. Default is False.

### Returns
- **DownloadMission** - If wait succeeds and cancel_it is False.
- **dict** - If wait succeeds and cancel_it is True.
- **False** - If wait fails.

### Example
```python
from DrissionPage import Chromium

tab = Chromium().latest_tab
tab('t:a').click()  # Click a link that triggers download
tab.wait.download_begin()
```
```

--------------------------------

### Set Proxy After Browser Startup

Source: https://www.drissionpage.cn/features/5

Use browser.new_context(proxy=...) to set a proxy for a specific context after the browser has started.

```python
from DrissionPage import Chromium  
  
browser = Chromium()  
# 新建上下文，使用不同的代理  
context = browser.new_context(proxy='http://lisi:abc123@123.4.56.78:9101')  
tab = context.new_tab()  
tab.get('https://ipv4.webshare.io/')  
```

--------------------------------

### Set Proxy Before Browser Startup

Source: https://www.drissionpage.cn/features/5

Use ChromiumOptions.set_proxy() to configure a proxy with credentials before the browser starts. This setting applies to all contexts.

```python
from DrissionPage import Chromium, ChromiumOptions  
  
# 浏览器创建时设置  
co = ChromiumOptions().set_proxy('http://zhangsan:abc123@12.34.56.78:9101')  
browser = Chromium(co)  
tab = browser.latest_tab  
tab.get('https://ipv4.webshare.io/')  
```

--------------------------------

### listen.start()

Source: https://www.drissionpage.cn/browser_control/listener

Starts the network listener on a page object, optionally setting target URL patterns, HTTP methods, and resource types to filter captured packets.

```APIDOC
## listen.start()

### Description
Starts the listener and optionally sets the target URL patterns to match. If the listener is already running, calling this method clears the captured queue.

### Method
N/A (SDK method)

### Parameters
- **targets** (str | list | tuple | set) - Optional - URL patterns to match. Use a list for multiple patterns. Set to `True` to capture all packets.
- **is_regex** (bool) - Optional - Whether the targets are regular expressions. Defaults to `None` (keeps previous setting). Note: when `targets` is not `None`, `is_regex` is automatically set to `False` unless explicitly set to `True`.
- **method** (str | list | tuple | set) - Optional - HTTP methods to listen for. Defaults to `('GET', 'POST')`. Set to `True` to listen for all methods. `None` keeps previous setting.
- **res_type** (str | list | tuple | set) - Optional - ResourceType values to listen for. Set to `True` to listen for all types. `None` keeps previous setting.

### Returns
`None`

### Example
```python
tab.listen.start('gitee.com/explore')
```
```

--------------------------------

### screencast.start()

Source: https://www.drissionpage.cn/browser_control/screen

开始录制浏览器窗口。

```APIDOC
## screencast.start()

### Description
开始录制浏览器窗口。

### Method
页面对象 screencast 功能

### Parameters
- **save_path** (str | Path) - 可选 - 保存图片或视频的路径

### Return
None

### Note
保存路径必需设置，无论是用 screencast.set_save_path() 还是 screencast.start() 都可以。

### Example
```python
tab.screencast.start()
```
```

--------------------------------

### Execute JavaScript on element with run_js()

Source: https://www.drissionpage.cn/browser_control/ele_operation

Executes JavaScript on the element, where 'this' refers to the element. The first example clicks the element, the second retrieves its height. Remember to include 'return' to get a result.

```python
# 用执行 js 的方式点击元素  
ele.run_js('this.click();')  
  
# 用 js 获取元素高度  
height = ele.run_js('return this.offsetHeight;')  
```

--------------------------------

### get()

Source: https://www.drissionpage.cn/SessionPage/visit

以 GET 方式请求页面，支持连接失败重试，不返回 Response 对象，而是从页面对象的 html 等属性读取结果。

```APIDOC
## get()

### Description
以 GET 方式请求页面，支持连接失败重试，不返回 Response 对象，而是从页面对象的 html 等属性读取结果。

### Method
GET

### Endpoint
N/A（方法调用）

### Parameters
#### Method Parameters
- **url** (str) - Required - 目标 url，可指向本地文件路径
- **show_errmsg** (bool) - Optional - 连接出错时是否显示和抛出异常，默认 False
- **retry** (int) - Optional - 重试次数，为 None 时使用页面参数，默认 3
- **interval** (float) - Optional - 重试间隔（秒），为 None 时使用页面参数，默认 2
- **timeout** (float) - Optional - 加载超时时间（秒）
- **params** (dict) - Optional - url 请求参数
- **data** (dict|str) - Optional - 携带的数据
- **json** (dict|str) - Optional - 要发送的 JSON 数据，会自动设置 Content-Type 为 'application/json'
- **headers** (dict) - Optional - 请求头
- **cookies** (dict|CookieJar) - Optional - cookies 信息
- **files** (Any) - Optional - 要上传的文件，可以是一个字典，其中键是文件名，值是文件对象或文件路径
- **auth** (Any) - Optional - 身份认证信息
- **allow_redirects** (bool) - Optional - 是否允许重定向，默认 True
- **proxies** (dict) - Optional - 代理信息
- **hooks** (Any) - Optional - 回调方法
- **stream** (bool) - Optional - 是否使用流式传输
- **verify** (bool|str) - Optional - 是否验证 SSL 证书
- **cert** (str|Tuple[str, str]) - Optional - SSL 客户端证书文件的路径(.pem 格式)，或('cert', 'key')元组

### Request Example
```python
from DrissionPage import SessionPage

page = SessionPage()
page.get('http://g1879.gitee.io/drissionpage')
```

### Response
#### Success Response
- **bool** - 是否连接成功

#### Response Example
```python
True
```
```

--------------------------------

### 启动浏览器 (dp --launch-browser / -l)

Source: https://www.drissionpage.cn/advance/commands

启动浏览器，等待程序接管。传入端口号，0 表示用配置文件中的值。提供完整写法 --launch-browser 和简略写法 -l。

```bash
# 完整写法  
dp --launch-browser 9333  
  
# 简略写法  
dp -l 0  
```

--------------------------------

### get() 方法返回连接状态信息

Source: https://www.drissionpage.cn/features/4.2

get() 方法返回 NavResult 对象，包含 url、status、headers、request、Response（仅 s 模式）和 ok 属性。示例展示了如何访问这些属性。

```python
from DrissionPage import Chromium  
  
tab = Chromium().latest_tab  
res = tab.get('https://DrissionPage.cn')  
print(res.status)  
print(res.ok)  
print(res.url)  
print(res.headers)  
print(res.request)  

```

--------------------------------

### wait.download_begin()

Source: https://www.drissionpage.cn/browser_control/browser_object

此方法用于等待浏览器下载开始。有些下载是从临时闪现的标签页触发的，这种需要由浏览器对象去捕捉。

```APIDOC
## wait.download_begin()

### Description
此方法用于等待浏览器下载开始。有些下载是从临时闪现的标签页触发的，这种需要由浏览器对象去捕捉。

### Method
wait.download_begin()

### Parameters
#### Parameters
- **timeout** (float) - Optional - 超时时间（秒），None 使用页面对象超时时间
- **cancel_it** (bool) - Optional - 是否取消该任务

### Returns
- **DownloadMission** - 等待成功返回下载任务对象
- **False** - 等待失败返回 False
```

--------------------------------

### 使用 get() 方法访问网页

Source: https://www.drissionpage.cn/browser_control/visit

通过 Chromium 实例的 latest_tab 对象调用 get() 方法跳转到指定网址。

```python
from DrissionPage import Chromium  
  
tab = Chromium().latest_tab  
tab.get('http://DrissionPage.cn')  
```

--------------------------------

### 等待并获取数据包示例

Source: https://www.drissionpage.cn/browser_control/listener

启动监听后，循环点击下一页并等待数据包，打印数据包 URL。注意要先启动监听再执行动作，listen.start() 之前的数据包获取不到。

```python
from DrissionPage import Chromium  
  
tab = Chromium().latest_tab  
tab.get('https://gitee.com/explore/all')  # 访问网址，这行产生的数据包不监听  
  
tab.listen.start('gitee.com/explore')  # 开始监听，指定获取包含该文本的数据包  
for _ in range(5):  
    tab('@rel=next').click()  # 点击下一页  
    res = tab.listen.wait()  # 等待并获取一个数据包  
    print(res.url)  # 打印数据包url  
```

```text
https://gitee.com/explore/all?page=2  
https://gitee.com/explore/all?page=3  
https://gitee.com/explore/all?page=4  
https://gitee.com/explore/all?page=5  
https://gitee.com/explore/all?page=6  
```

--------------------------------

### Manage tabs with Chromium object

Source: https://www.drissionpage.cn/features/4.1

Shows how to manage tabs with the Chromium object: get the latest tab, get a tab by title, create a new tab, activate a tab, and close a tab.

```python
from DrissionPage import Chromium  
  
browser = Chromium()  
tab1 = browser.latest_tab  # 获取最后激活的标签页对象  
tab2 = browser.get_tab(title='DrissionPage')  # 获取指定标签页  
tab3 = browser.new_tab()  # 新建标签页  
browser.activate_tab(tab2)  # 将tab2提到最前面  
tab1.close()  # 关闭标签页  

```

--------------------------------

### 设置窗口大小 set.window.size()

Source: https://www.drissionpage.cn/browser_control/page_operation

设置窗口大小，只传入一个参数时另一个参数不变。参数 width 和 height 均为 int 类型，默认 None。返回 None。

```python
tab.set.window.size(500, 500)  
```

--------------------------------

### 获取筛选结果属性集合示例

Source: https://www.drissionpage.cn/browser_control/get_elements/filter

演示如何使用 get() 方法获取筛选结果的文本集合。包含获取所有元素文本与筛选后元素文本的对比。

```python
from DrissionPage import Chromium  
  
tab = Chromium().latest_tab  
tab.get('https://www.baidu.com')  
eles = tab('#s-top-left').eles('t:a')  
print(eles.get.texts())  # 获取所有元素的文本  
print(eles.filter.displayed().get.texts())  # 获取的元素的文本  
```

```text
['新闻', 'hao123', '地图', '贴吧', '视频', '图片', '网盘', '文库', '更多', '翻译', '学术', '百科', '知道', '健康', '营销推广', '直播', '音乐', '橙篇', '查看全部百度产品 >']  
['新闻', 'hao123', '地图', '贴吧', '视频', '图片', '网盘', '文库', '更多']  
```

--------------------------------

### 等待下载开始：wait.download_begin() 示例

Source: https://www.drissionpage.cn/browser_control/waiting

点击下载按钮后，使用 wait.download_begin() 等待下载任务开始。该方法返回 DownloadMission 对象或 False。

```python
tab('#download_btn').click()  # 点击按钮触发下载  
tab.wait.download_begin()  # 等待下载开始  
```

--------------------------------

### 访问登录页面

Source: https://www.drissionpage.cn/get_start/examples/control_browser

使用 get() 方法访问 gitee 登录页面，它会等待页面完全加载后再继续执行。

```python
tab.get('https://gitee.com/login')  
```

--------------------------------

### 循环访问分页 URL

Source: https://www.drissionpage.cn/get_start/examples/data_packets

通过循环构造分页 URL 并使用 get() 方法访问。

```python
for i in ranage(1, 4):  
    page.get(f'https://gitee.com/explore/all?page={i}')  
```

--------------------------------

### 用命令行复制默认 ini 文件到项目路径

Source: https://www.drissionpage.cn/advance/ini

在项目文件夹路径下运行 dp --configs-to-here 命令，效果与 configs_to_here() 一致，但不能指定文件名。

```bash
dp --configs-to-here  
```

--------------------------------

### 读取本地文件：page.get()

Source: https://www.drissionpage.cn/SessionPage/visit

get() 的 url 参数可指向本地文件路径，用于解析本地 HTML 文件。

```python
from DrissionPage import SessionPage  
  
page = SessionPage()  
page.get(r'D:\demo.html')  
```

--------------------------------

### wait.download_begin(cancel_it=False)

Source: https://www.drissionpage.cn/download/browser

Waits for a download to begin and returns a DownloadMission object. If cancel_it is True, the download is canceled and the mission info can be used for further actions.

```APIDOC
## wait.download_begin(cancel_it=False)

### Description
Waits for a download to begin and returns a DownloadMission object. If `cancel_it` is `True`, the download is canceled and the mission info can be used for further actions.

### Method
wait.download_begin()

### Parameters
- **cancel_it** (bool) - Optional - If `True`, cancels the download task.

### Request Example
```python
from DrissionPage import Chromium

tab = Chromium().latest_tab
tab('t:a').click()
data = tab.wait.download_begin(cancel_it=True)
tab.download(data.url)
```

### Response
Returns a `DownloadMission` object.
```

--------------------------------

### 设置超时和重试参数

Source: https://www.drissionpage.cn/browser_control/visit

在 get() 方法中通过 retry、interval 和 timeout 参数自定义网络请求的重试逻辑和超时时间。

```python
from DrissionPage import Chromium  
  
tab = Chromium().latest_tab  
tab.get('http://DrissionPage.cn', retry=1, interval=1, timeout=1.5)  
```

--------------------------------

### 使用连接参数访问网页：page.get()

Source: https://www.drissionpage.cn/SessionPage/visit

使用 get() 方法并传入 headers、cookies、proxies 等连接参数。注意：传入的 headers 等参数会覆盖配置中的同名项，但只覆盖传入的项。

```python
from DrissionPage import SessionPage  
  
page = SessionPage()  
  
url = 'https://www.baidu.com'  
headers = {'referer': 'gitee.com'}  
cookies = {'name': 'value'}  
proxies = {'http': '127.0.0.1:1080', 'https': '127.0.0.1:1080'}  
page.get(url, headers=headers, cookies=cookies, proxies=proxies)  
```

--------------------------------

### 设置总下载路径 (Chromium.set.download_path)

Source: https://www.drissionpage.cn/download/browser

使用 Chromium 对象的 set.download_path() 方法设置下载路径。不设置时默认下载到程序当前路径。设置后新建的 Tab 对象会使用该路径，之前建立的 Tab 对象路径不变。

```python
from DrissionPage import Chromium  

browser = Chromium()  
browser.set.download_path(r'C:\tmp')  

```

--------------------------------

### parent()

Source: https://www.drissionpage.cn/browser_control/get_elements/relative

Gets a parent element of the current element at a specified level or matching a locator.

```APIDOC
## parent()

### Description
Gets a parent element of the current element at a specified level or matching a locator.

### Method
parent()

### Parameters
- **level_or_loc** (int | str | Tuple[str, str]) - Optional - Level of parent element (starting from 1) or a locator to filter ancestors.
- **index** (int) - Optional - When level_or_loc is a locator, selects the nth result counting from the current element upward. Ignored when level_or_loc is an integer.
- **timeout** (float) - Optional - Timeout in seconds for the search. None uses page timeout. Not applicable in s mode.

### Returns
- **ChromiumElement** - Element object in d mode.
- **SessionElement** - Element object in s mode.
- **NoneElement** - If no result found.

### Example
```python
# Get the second-level parent element of ele1
ele2 = ele1.parent(2)

# Get the parent element with id 'id1'
ele2 = ele1.parent('#id1')
```
```

--------------------------------

### 使用 ChromiumOptions 配置系统用户目录

Source: https://www.drissionpage.cn/browser_control/connect_browser

通过 ChromiumOptions 的 use_system_user_path 方法配置浏览器使用系统默认用户文件夹。使用此方法前必须关闭已启动的系统浏览器，否则会导致连接失败。

```python
from DrissionPage import Chromium, ChromiumOptions  
  
co = ChromiumOptions().use_system_user_path()  
browser = Chromium(co)  
```

--------------------------------

### post()

Source: https://www.drissionpage.cn/SessionPage/visit

以 POST 方式请求页面，用法与 get() 一致，支持 data 和 json 参数传递数据。

```APIDOC
## post()

### Description
以 POST 方式请求页面，用法与 get() 一致，支持 data 和 json 参数传递数据。

### Method
POST

### Endpoint
N/A（方法调用）

### Parameters
#### Method Parameters
- **url** (str) - Required - 目标 url，可指向本地文件路径
- **show_errmsg** (bool) - Optional - 连接出错时是否显示和抛出异常，默认 False
- **retry** (int) - Optional - 重试次数，为 None 时使用页面参数，默认 3
- **interval** (float) - Optional - 重试间隔（秒），为 None 时使用页面参数，默认 2
- **timeout** (float) - Optional - 加载超时时间（秒）
- **params** (dict) - Optional - url 请求参数
- **data** (dict|str) - Optional - 携带的数据
- **json** (dict|str) - Optional - 要发送的 JSON 数据，会自动设置 Content-Type 为 'application/json'
- **headers** (dict) - Optional - 请求头
- **cookies** (dict|CookieJar) - Optional - cookies 信息
- **files** (Any) - Optional - 要上传的文件，可以是一个字典，其中键是文件名，值是文件对象或文件路径
- **auth** (Any) - Optional - 身份认证信息
- **allow_redirects** (bool) - Optional - 是否允许重定向，默认 True
- **proxies** (dict) - Optional - 代理信息
- **hooks** (Any) - Optional - 回调方法
- **stream** (bool) - Optional - 是否使用流式传输
- **verify** (bool|str) - Optional - 是否验证 SSL 证书
- **cert** (str|Tuple[str, str]) - Optional - SSL 客户端证书文件的路径(.pem 格式)，或('cert', 'key')元组

### Request Example
```python
from DrissionPage import SessionPage

page = SessionPage()
data = {'username': '****', 'pwd': '****'}

page.post('http://example.com', data=data)
# 或
page.post('http://example.com', json=data)
```

### Response
#### Success Response
- **bool** - 是否连接成功

#### Response Example
```python
True
```
```

--------------------------------

### 使用 listen 监听数据包并打印响应（DrissionPage 4.0）

Source: https://www.drissionpage.cn/features/4

示例代码演示了 DrissionPage 4.0 中新的监听器用法：通过 page.listen.start() 指定目标并启动监听，访问网站后使用 page.listen.wait() 等待数据包，并打印响应正文。代码中使用了 TimePinner 进行计时，输出显示响应体为字典结构。

```python
from DrissionPage import ChromiumPage  
from TimePinner import Pinner  
from pprint import pprint  
  
page = ChromiumPage()  
page.listen.start('api/getkeydata')  # 指定监听目标并启动监听  
pinner = Pinner(True, False)  
page.get('http://www.hao123.com/')  # 访问网站  
packet = page.listen.wait()  # 等待数据包  
pprint(packet.response.body)  # 打印数据包正文  
pinner.pin('用时', True)  
```

```text
{'hao123.new.shishi.bangdan.recom': [{'index': '1',  
                                      'pure_title': '以色列和哈马斯移交首批被扣押人员'},  
                                     {'index': '2',  
                                      'pure_title': '听到免签政策法国外长笑了'},  
                                     ......  
用时：3.3114853000151925  
```

--------------------------------

### 普通访问网页：page.get()

Source: https://www.drissionpage.cn/SessionPage/visit

使用 SessionPage 的 get() 方法访问在线网页。该方法不返回 Response 对象，而是从页面对象的 html 等属性读取结果。

```python
from DrissionPage import SessionPage  
  
page = SessionPage()  
page.get('http://g1879.gitee.io/drissionpage')  
```

--------------------------------

### 导入其他辅助工具

Source: https://www.drissionpage.cn/get_start/import

导入 wait_until、make_session_ele、configs_to_here 等辅助工具，分别用于等待条件、从 html 生成元素、复制配置文件到当前路径。

```python
from DrissionPage.common import wait_until  
from DrissionPage.common import make_session_ele  
from DrissionPage.common import configs_to_here  
```

--------------------------------

### Retrieve all download tasks

Source: https://www.drissionpage.cn/download/DownloadKit

Accesses the missions attribute to get a dictionary of all current download tasks.

```python
page.download_set.save_path(r'D:\download')  
page.download('http://****/****1.pdf')  
page.download('http://****/****1.pdf')  
print(page.download.missions)  
```

```text
{  
    1: <Mission 1 D:\download\xxx1.pdf xxx1.pdf>  
    2: <Mission 2 D:\download\xxx1_1.pdf xxx1_1.pdf>  
    ...  
}  
```

--------------------------------

### 复制默认 ini 文件到当前路径 (dp --configs-to-here / -c)

Source: https://www.drissionpage.cn/advance/commands

复制默认配置文件到当前路径。提供完整写法 --configs-to-here 和简略写法 -c。

```bash
# 完整写法  
dp --configs-to-here  
  
# 简略写法  
dp -c  
```

--------------------------------

### select.by_index()

Source: https://www.drissionpage.cn/browser_control/ele_operation

Selects options by their index (starting from 1). For multi-select lists, multiple items can be selected.

```APIDOC
## select.by_index()

### Description
Selects options in a `<select>` element by their index, starting from 1. For multi-select lists, multiple items can be selected.

### Method
`select.by_index()`

### Parameters
- **index** (int | list | tuple) - Required - The index of the option to select. Pass a list or tuple to select multiple items.
- **timeout** (float) - Optional - Timeout in seconds. Defaults to page timeout if `None`.

### Returns
- **bool** - `True` if selection succeeded, `False` otherwise.
```

--------------------------------

### Remove element attribute with remove_attr()

Source: https://www.drissionpage.cn/browser_control/ele_operation

Removes an attribute from the element. The example removes the 'href' attribute.

```python
ele.remove_attr('href')  
```

--------------------------------

### 使用 click.to_download 触发下载

Source: https://www.drissionpage.cn/download/browser

通过 click.to_download 方法点击元素触发下载，并可直接指定保存路径和重命名文件。该方法返回一个 DownloadMission 对象，可调用 wait() 等待下载完成。

```python
from DrissionPage import Chromium  
  
tab = Chromium().latest_tab   
tab.get('https://im.qq.com/pcqq/index.shtml')  
ele = tab('全新体验版下载')  
ele.wait.has_rect()  
mission = ele.click.to_download(save_path='tmp', rename='QQ.exe')  
mission.wait()  
```

--------------------------------

### 等待页面加载开始：wait.load_start() 示例

Source: https://www.drissionpage.cn/browser_control/waiting

点击元素后，使用 wait.load_start() 等待页面进入加载状态，避免过早获取元素。

```python
ele.click()  # 点击某个元素  
tab.wait.load_start()  # 等待页面进入加载状态  
# 执行在新页面的操作  
print(page.title)  
```

--------------------------------

### Get Focused Element

Source: https://www.drissionpage.cn/browser_control/get_elements/find_in_object

Use the active_ele property of the page object to retrieve the element currently in focus.

```python
ele = tab.active_ele  
```

--------------------------------

### Start Browser

Source: https://www.drissionpage.cn/tutorials/TgeBrowser

Call the /api/browser/start endpoint using the envId to launch the browser and retrieve the debug port.

```python
response = requests.post(  
    f"{API_BASE_URL}/api/browser/start",  
    json={"envId": env_id},  
    headers=headers  
)  
debug_port = response.json()["data"]["port"]  
```

--------------------------------

### 设置 Tab 下载路径 (tab.set.download_path)

Source: https://www.drissionpage.cn/download/browser

使用 Tab 对象的 set.download_path() 方法设置下载路径，只在当前 Tab 对象生效。

```python
from DrissionPage import Chromium  

tab = Chromium().latest_tab  
tab.set.download_path(r'C:\tmp1')  # 设置Tab下载路径  

```

--------------------------------

### select.cancel_by_index()

Source: https://www.drissionpage.cn/browser_control/ele_operation

Cancels selection of options by their index (starting from 1). For multi-select lists, multiple items can be deselected.

```APIDOC
## select.cancel_by_index()

### Description
Cancels selection of options in a `<select>` element by their index, starting from 1. For multi-select lists, multiple items can be deselected.

### Method
`select.cancel_by_index()`

### Parameters
- **index** (int | list | tuple) - Required - The index of the option to deselect. Pass a list or tuple to deselect multiple items.
- **timeout** (float) - Optional - Timeout in seconds. Defaults to page timeout if `None`.

### Returns
- **bool** - `True` if deselection succeeded, `False` otherwise.
```

--------------------------------

### 隐藏浏览器窗口 set.window.hide()

Source: https://www.drissionpage.cn/browser_control/page_operation

隐藏浏览器窗口，与 headless 模式不同，直接隐藏浏览器进程，任务栏上也会消失。仅支持 Windows 系统，且必须安装 pypiwin32 库。窗口隐藏后，如果有新窗口出现，整个浏览器会重新显现。注意：浏览器隐藏后并未关闭，下次运行程序会接管已隐藏的浏览器；若有新建标签页，会自行显示。

```python
tab.set.window.hide()  
```

--------------------------------

### 设置用户数据路径 (dp --set-user-path / -u)

Source: https://www.drissionpage.cn/advance/commands

设置配置文件中的用户数据路径。提供完整写法 --set-user-path 和简略写法 -u。

```bash
# 完整写法  
dp --set-user-path D:\chrome\user_data  
  
# 简略写法  
dp -u D:\chrome\user_data  
```

--------------------------------

### Set element attribute with set.attr()

Source: https://www.drissionpage.cn/browser_control/ele_operation

Sets an attribute on the element. The example sets the 'href' attribute to 'http://DrissionPage.cn'.

```python
ele.set.attr('href', 'http://DrissionPage.cn')  
```

--------------------------------

### 使用 configs_to_here() 复制默认 ini 文件到项目路径

Source: https://www.drissionpage.cn/advance/ini

调用 DrissionPage.common 中的 configs_to_here() 方法，将默认 ini 文件复制到当前项目文件夹并命名为 dp_configs.ini，程序会优先读取该文件。

```python
from DrissionPage.common import configs_to_here  
  
configs_to_here()  
```

--------------------------------

### Set element property with set.property()

Source: https://www.drissionpage.cn/browser_control/ele_operation

Sets a property on the element. The example sets the 'value' property to 'Hello world!'.

```python
ele.set.property('value', 'Hello world!')  
```

--------------------------------

### 使用 new_env 方法创建全新浏览器

Source: https://www.drissionpage.cn/browser_control/connect_browser

使用 ChromiumOptions 的 new_env 方法启动全新的浏览器环境。如果指定端口已有浏览器，程序会自动关闭旧实例并启动新实例。

```python
from DrissionPage import Chromium, ChromiumOptions  
  
co = ChromiumOptions().new_env()  
browser = Chromium(co)  
```

--------------------------------

### 设置窗口位置 set.window.location()

Source: https://www.drissionpage.cn/browser_control/page_operation

设置窗口位置，只传入一个参数时另一个参数不变。参数 x 和 y 均为 int 类型，默认 None。返回 None。

```python
tab.set.window.location(500, 500)  
```

--------------------------------

### add_extension(path)

Source: https://www.drissionpage.cn/browser_control/browser_options

Adds a browser extension to be loaded when the browser starts. The extension is loaded temporarily and will not persist in the user folder.

```APIDOC
## add_extension(path)

### Description
Adds a browser extension to be loaded when the browser starts. The extension is loaded temporarily and will not persist in the user folder.

### Method
add_extension

### Parameters
- **path** (str | Path) - Required - The path to the extension.

### Returns
- **ChromiumOptions** - The configuration object itself.

### Example
```python
co.add_extension(r'D:\SwitchyOmega')
```
```

--------------------------------

### 设置浏览器路径 (dp --set-browser-path / -p)

Source: https://www.drissionpage.cn/advance/commands

设置配置文件中的浏览器路径。提供完整写法 --set-browser-path 和简略写法 -p。

```bash
# 完整写法  
dp --set-browser-path "D:\chrome\Chrome.exe"  
  
# 简略写法  
dp -p "D:\chrome\Chrome.exe"  
```

--------------------------------

### Selenium Iframe Navigation Comparison

Source: https://www.drissionpage.cn/browser_control/get_elements/find_in_object

This example demonstrates the traditional, more verbose approach required by Selenium to switch into nested iframes.

```python
driver = webdriver.Chrome()  
driver.switch_to.frame(0)  
driver.switch_to.frame(0)  
ele = driver.find_element(By.ID, 'abc')  
driver.switch_to.default_content()  
```

--------------------------------

### wait.download_begin() (Browser)

Source: https://www.drissionpage.cn/browser_control/waiting

Waits for a download task to begin in the browser. Returns a DownloadMission object on success or False on failure.

```APIDOC
## wait.download_begin() (Browser)

### Description
Waits for a download task to begin in the browser.

### Method
wait.download_begin()

### Parameters
- **timeout** (float) - Optional - Timeout in seconds. If None, uses the page's timeout setting.
- **cancel_it** (bool) - Optional - Whether to cancel the task. Default is False.

### Returns
- **DownloadMission** - The download mission object on success.
- **False** - On failure.

### Example
```python
tab('#download_btn').click()  # Click button to trigger download
tab.wait.download_begin()  # Wait for download to start
```
```

--------------------------------

### 新建标签页并切换到新标签页（旧版 vs 新版）

Source: https://www.drissionpage.cn/features/4

旧版使用 new_tab(switch_to=True) 创建并切换，新版直接使用 new_tab() 返回标签页对象。

```python
# ------ 旧版代码 ------  
tab = page.new_tab(switch_to=True)  
  
# ------ 新版代码 ------  
tab = page.new_tab()  
```
Tokens:
Raw