核心 API 通俗详解

接管了候鸟浏览器之后，接下来最重要的事，就是让 Selenium 按照您的意图操控页面。本章用大白话解释您 80% 的时间都会用到的核心 API。

一、导航与页面控制

打开网址

python

driver.get("https://www.amazon.com")

白话：让浏览器"去这个网址"。
脚本会阻塞在这里，直到页面加载完毕（onload 事件触发）才继续执行。

等页面加载完再走

网速有快有慢，如果页面还没刷完就执行后续代码，脚本会找不到元素而报错。最稳妥的办法是配合等待（见第三节）。

获取页面信息

python

title = driver.title                  # 获取页面标题
url   = driver.current_url           # 获取当前 URL
html  = driver.page_source           # 获取完整页面 HTML

前进、后退、刷新

python

driver.back()     # 后退（等于按浏览器左上角← 箭头）
driver.forward()  # 前进
driver.refresh()  # 刷新页面（F5）

二、查找页面元素

IMPORTANT

找到元素是一切操作的前提。 找不到元素 = 找不到门 = 什么都做不了。

定位器类型速查表

Selenium 4 统一使用 By 类来指定定位方式：

python

from selenium.webdriver.common.by import By

定位方式	代码示例	适用场景
ID	`By.ID, "username"`	最快最稳，优先选这个
CSS 选择器	`By.CSS_SELECTOR, "#username"`	灵活，通用性最强
XPath	`By.XPATH, "//input[@name='user']"`	复杂结构必备，但写起来麻烦
类名	`By.CLASS_NAME, "btn-primary"`	简单场景可用，重名元素慎用
标签名	`By.TAG_NAME, "input"`	很少单独使用
链接文字	`By.LINK_TEXT, "登录"`	点链接时方便
name 属性	`By.NAME, "password"`	表单元素常用

查找单个元素

python

# 查找 id 为 "username" 的元素（找不到就报 NoSuchElementException）
element = driver.find_element(By.ID, "username")

# 查找第一个匹配的 CSS 选择器
btn = driver.find_element(By.CSS_SELECTOR, ".login-form button[type='submit']")

查找多个元素（返回列表）

python

# 找到所有商品列表项
items = driver.find_elements(By.CSS_SELECTOR, ".product-item")
print(f"共找到 {len(items)} 个商品")

# 遍历每个元素
for item in items:
    print(item.text)

如何在浏览器里找到选择器？（实操技巧）

在候鸟浏览器中打开目标网页
对准要操作的按钮 右键 → 检查（Inspect）
在 DevTools 的 HTML 代码上 右键 → Copy → Copy selector（CSS 选择器）或 Copy XPath
粘贴到您的 Selenium 代码里

三、等待机制（防崩溃利器）

CAUTION

time.sleep(N) 是最糟糕的等待方式——网速快时浪费时间，网速慢时还是会崩溃。请使用 Selenium 的智能等待机制。

显式等待（强烈推荐）

等到某个条件满足才继续，最多等 N 秒，超时则报错：

python

from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.common.by import By

# 最多等 15 秒，直到 id="username" 的元素可见
wait = WebDriverWait(driver, 15)
username_input = wait.until(
    EC.visibility_of_element_located((By.ID, "username"))
)

常用等待条件 EC.xxx：

等待条件	说明
`EC.presence_of_element_located`	元素存在于 DOM 中（不一定可见）
`EC.visibility_of_element_located`	元素存在且可见（推荐）
`EC.element_to_be_clickable`	元素可见且可点击
`EC.text_to_be_present_in_element`	某元素包含指定文本
`EC.url_contains`	当前 URL 包含指定字符串
`EC.alert_is_present`	弹窗出现

实战示例：等待登录完成后跳转

python

# 点击登录按钮
driver.find_element(By.ID, "loginBtn").click()

# 等待 URL 变为含"/dashboard"的地址（表示跳转到了主页）
wait = WebDriverWait(driver, 20)
wait.until(EC.url_contains("/dashboard"))
print("登录跳转成功！")

隐式等待（全局设置，不推荐但有时有用）

python

driver.implicitly_wait(10)  # 全局等待：所有的 find_element 最多等 10 秒

四、模拟人类操作

输入文字

python

# 找到输入框并输入账号，delay 参数控制每个字符的输入间隔（毫秒）
from selenium.webdriver.common.action_chains import ActionChains
import time

input_box = driver.find_element(By.ID, "username")
input_box.clear()           # 先清空输入框原有内容
input_box.send_keys("mbbrowser_user")  # 输入内容

# 模拟更真实的人类输入（逐字符输入，有延迟）
def human_type(element, text, delay=0.08):
    """模拟人类打字速度，每个字符之间有短暂停顿"""
    for char in text:
        element.send_keys(char)
        time.sleep(delay)

点击元素

python

btn = driver.find_element(By.CSS_SELECTOR, "button[type='submit']")
btn.click()

模拟键盘按键

python

from selenium.webdriver.common.keys import Keys

# 按 Enter 键（常用于提交搜索）
search_box = driver.find_element(By.NAME, "q")
search_box.send_keys("候鸟浏览器")
search_box.send_keys(Keys.RETURN)

# 全选 + 删除
input_box.send_keys(Keys.CONTROL + "a")  # Ctrl+A
input_box.send_keys(Keys.DELETE)          # Del

下拉框选择

python

from selenium.webdriver.support.ui import Select

# 通过可见文本选择
select = Select(driver.find_element(By.ID, "country"))
select.select_by_visible_text("美国")

# 通过 value 属性选择
select.select_by_value("US")

# 通过序号选择（从 0 开始）
select.select_by_index(2)

鼠标悬停（触发 hover 菜单）

python

from selenium.webdriver.common.action_chains import ActionChains

menu_item = driver.find_element(By.ID, "topMenu")
ActionChains(driver).move_to_element(menu_item).perform()  # 移动鼠标到该元素上

拖拽

python

source = driver.find_element(By.ID, "drag_item")
target = driver.find_element(By.ID, "drop_zone")
ActionChains(driver).drag_and_drop(source, target).perform()

五、获取元素信息

python

el = driver.find_element(By.ID, "user-info")

# 获取可见文本
text = el.text

# 获取指定属性值
href  = el.get_attribute("href")
value = el.get_attribute("value")
cls   = el.get_attribute("class")

# 判断状态
el.is_displayed()   # 元素是否可见
el.is_enabled()     # 元素是否可交互（如按钮是否灰色）
el.is_selected()    # 复选框/单选框是否选中

# 获取 CSS 属性
color = el.value_of_css_property("color")

候鸟的环境会持久化保存 Cookie，但您也可以通过代码精确操作：

python

# 获取所有 Cookie
all_cookies = driver.get_cookies()
print(all_cookies)

# 添加一个 Cookie（必须先打开该域名的网址）
driver.get("https://example.com")
driver.add_cookie({
    "name": "session_id",
    "value": "abc123",
    "domain": ".example.com"
})

# 删除指定 Cookie
driver.delete_cookie("session_id")

# 删除所有 Cookie
driver.delete_all_cookies()

七、弹窗处理

python

# 等待弹窗出现
wait.until(EC.alert_is_present())

# 获取弹窗对象
alert = driver.switch_to.alert

# 读取弹窗文字
print(alert.text)

# 接受（相当于点"确定"）
alert.accept()

# 拒绝（相当于点"取消"）
alert.dismiss()

# 在输入框类弹窗中输入内容
alert.send_keys("我的输入")
alert.accept()

八、多标签页 / 多窗口操作

python

# 打开新标签页
driver.switch_to.new_window("tab")

# 获取所有窗口句柄
handles = driver.window_handles
print(f"当前共有 {len(handles)} 个标签页")

# 切换到指定标签页
driver.switch_to.window(handles[-1])   # 切换到最后一个（最新打开的）

# 切换到第一个标签页
driver.switch_to.window(handles[0])

九、iframe 切换

网页中的登录框、广告等有时被放在 iframe 框架里，直接查找元素会找不到，必须先切换进 iframe：

python

# 通过 CSS 选择器切换进 iframe
iframe = driver.find_element(By.CSS_SELECTOR, "iframe#loginFrame")
driver.switch_to.frame(iframe)

# 现在可以操作 iframe 内的元素了
driver.find_element(By.ID, "username").send_keys("my_user")

# 操作完后，切回主页面
driver.switch_to.default_content()

十、截图

python

# 截整个页面
driver.save_screenshot("screenshot.png")

# 截单个元素
element = driver.find_element(By.ID, "product-image")
element.screenshot("product.png")

# 截图并直接返回二进制数据（用于存数据库等场景）
png_bytes = driver.get_screenshot_as_png()

十一、JavaScript 注入（高级技巧）

有些元素"点不到"（被遮挡、被 JS 拦截等），可以直接注入 JS 操控：

python

# 用 JS 强制点击
driver.execute_script("arguments[0].click();", element)

# 滚动到某个元素
driver.execute_script("arguments[0].scrollIntoView();", element)

# 滚动到页面底部
driver.execute_script("window.scrollTo(0, document.body.scrollHeight);")

# 修改输入框的值（绕过某些只读框）
driver.execute_script("arguments[0].value = '新值';", input_element)

# 从 JS 获取返回值
title = driver.execute_script("return document.title;")

TIP

API 掌握了就可以处理绝大多数场景了！下一章实战案例库提供四个可直接套用的完整业务模板。

核心 API 通俗详解 ​

一、导航与页面控制 ​

打开网址 ​

等页面加载完再走 ​

获取页面信息 ​

前进、后退、刷新 ​

二、查找页面元素 ​

定位器类型速查表 ​

查找单个元素 ​

查找多个元素（返回列表） ​

如何在浏览器里找到选择器？（实操技巧） ​

三、等待机制（防崩溃利器） ​

显式等待（强烈推荐） ​

隐式等待（全局设置，不推荐但有时有用） ​

四、模拟人类操作 ​

输入文字 ​

点击元素 ​

模拟键盘按键 ​

下拉框选择 ​

鼠标悬停（触发 hover 菜单） ​

拖拽 ​

五、获取元素信息 ​

六、Cookie 操作 ​

七、弹窗处理 ​

八、多标签页 / 多窗口操作 ​

九、iframe 切换 ​

十、截图 ​

十一、JavaScript 注入（高级技巧） ​

核心 API 通俗详解

一、导航与页面控制

打开网址

等页面加载完再走

获取页面信息

前进、后退、刷新

二、查找页面元素

定位器类型速查表

查找单个元素

查找多个元素（返回列表）

如何在浏览器里找到选择器？（实操技巧）

三、等待机制（防崩溃利器）

显式等待（强烈推荐）

隐式等待（全局设置，不推荐但有时有用）

四、模拟人类操作

输入文字

点击元素

模拟键盘按键

下拉框选择

鼠标悬停（触发 hover 菜单）

拖拽

五、获取元素信息

六、Cookie 操作

七、弹窗处理

八、多标签页 / 多窗口操作

九、iframe 切换

十、截图

十一、JavaScript 注入（高级技巧）