选择器 - 小肩膀教育

核心 API

css: 选择器

返回: FirefoxElement

page.ele("css:#login-btn")

用 CSS 选择器定位元素。最常用，覆盖 80% 的场景。

参数说明

参数	说明
css:...	标准 CSS 选择器，如 #id、.class、div > p、[data-id='x']。

常见坑

伪元素（::before）无法选中。

tag: 选择器

返回: FirefoxElement

page.ele("tag:h1")

按标签名定位。简洁直接，适合唯一标签。

参数说明

参数	说明
tag:...	HTML 标签名，如 h1、input、textarea。

常见坑

同名标签多时定位不够精确。

相关示例

一步上手：最少代码完成访问与读取

text: 选择器

返回: FirefoxElement

page.ele("text:登录")

按可见文本内容定位。适合按钮、链接等有固定文案的元素。

参数说明

参数	说明
text:...	元素包含的文本（模糊匹配）。

常见坑

文本经常变化的元素不适合用 text 定位。

相关示例

元素查找：CSS / XPath / 文本 / 属性 / 容器内定位

xpath: 选择器

返回: FirefoxElement

page.ele("xpath://div[@class='result']")

用 XPath 表达式定位。最灵活，适合复杂结构。

参数说明

参数	说明
xpath:...	标准 XPath 表达式。

常见坑

XPath 较长时可读性差，优先考虑 CSS。

相关示例

XPath Picker 综合演示

选择器对比

前缀	语法示例	推荐程度	适合场景
css:	css:#id、css:.class、css:[data-x]	首选	大多数场景
tag:	tag:h1、tag:input	常用	标签唯一时
text:	text:登录、text:提交	常用	按钮/链接文案固定
xpath:	xpath://div[@id='x']	兜底	CSS 搞不定时
@属性名=	@data-testid=login	推荐	有测试属性时

快速上手

python 各种选择器用法

from ruyipage import launch

page = launch()
page.get("https://example.com")

# CSS 选择器（最常用）
h1 = page.ele("css:h1")
links = page.eles("css:a[href]")

# 标签名选择器
paragraphs = page.eles("tag:p")

# 文本选择器
more_link = page.ele("text:More information")

# XPath 选择器
div = page.ele("xpath://div[1]")

# 属性选择器
login_btn = page.ele("@data-testid=login-btn")

print(f"H1: {h1.text}")
print(f"链接数: {len(links)}")
print(f"段落数: {len(paragraphs)}")

page.quit()

相关示例源码

2 个示例 ▶ 点击展开

元素查找：CSS / XPath / 文本 / 属性 / 容器内定位

examples/02_element_finding.py

系统讲透单元素、多元素、文本、XPath 和属性定位的入门示例。

GitHub 仓库查看仓库源码 page.elepage.elesele.eleele.textele.attrele.attrsele.tag

通过 ID、class 和属性定位元素
批量获取列表元素
通过 XPath 和文本定位元素
在父容器内继续查找子元素
读取元素标签、属性和尺寸信息

源码文件：app/content/ruyipage_examples/02_element_finding.py · 仓库：02_element_finding.py

python 注释版

# =============================
# RuyiPage 示例注释版
# 标题: 元素查找：CSS / XPath / 文本 / 属性 / 容器内定位
# 说明: 系统讲透单元素、多元素、文本、XPath 和属性定位的入门示例。
# 你会学到:
#   1. 通过 ID、class 和属性定位元素
#   2. 批量获取列表元素
#   3. 通过 XPath 和文本定位元素
#   4. 在父容器内继续查找子元素
#   5. 读取元素标签、属性和尺寸信息
# 相关 API: page.ele, page.eles, ele.ele, ele.text, ele.attr, ele.attrs, ele.tag
# =============================

# -*- coding: utf-8 -*-
"""
示例2: 元素查找
测试功能：
- CSS选择器查找
- XPath查找
- 文本查找
- 属性查找
- 多元素查找
- 元素属性获取
"""

import os
import sys
import io

# 设置控制台输出编码为UTF-8（Windows兼容）
if sys.platform == 'win32':
    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')

sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))

from ruyipage import FirefoxPage, FirefoxOptions

def test_element_finding():
    """测试元素查找功能"""
    print("=" * 60)
    print("测试2: 元素查找")
    print("=" * 60)

    opts = FirefoxOptions()
    opts.headless(False)
    page = FirefoxPage(opts)

    try:
        # 加载测试页面
        test_page = os.path.join(os.path.dirname(__file__), 'test_pages', 'test_page.html')
        test_url = 'file:///' + os.path.abspath(test_page).replace('\\', '/')
        page.get(test_url)
        page.wait(1)

        # 1. 通过ID查找
        print("\n1. 通过ID查找元素:")
        title = page.ele('#main-title')
        print(f"   标题文本: {title.text}")
        print(f"   标签名: {title.tag}")

        # 2. 通过class查找
        print("\n2. 通过class查找元素:")
        test_div = page.ele('.test-class')
        print(f"   第一个.test-class元素: {test_div.text}")

        # 3. 查找所有匹配元素
        print("\n3. 查找所有.test-class元素:")
        all_test = page.eles('.test-class')
        print(f"   找到 {len(all_test)} 个元素")
        for i, elem in enumerate(all_test, 1):
            print(f"   元素{i}: {elem.text}")

        # 4. 通过XPath查找
        print("\n4. 通过XPath查找:")
        link = page.ele('xpath://a[@id="test-link"]')
        print(f"   链接文本: {link.text}")
        print(f"   链接地址: {link.link}")

        # 5. 通过文本查找
        print("\n5. 通过文本查找:")
        btn = page.ele('text:点击我')
        print(f"   按钮ID: {btn.attr('id')}")

        # 6. 通过属性查找
        print("\n6. 通过属性查找:")
        test_div = page.ele('[data-test="value"]')
        print(f"   data-test属性的元素: {test_div.text}")
        print(f"   所有属性: {test_div.attrs}")

        # 7. 组合选择器
        print("\n7. 组合选择器:")
        section = page.ele('#form-section')
        input_elem = section.ele('input[type="text"]')
        print(f"   表单区域内的文本输入框: {input_elem.attr('placeholder')}")

        # 8. 获取元素属性
        print("\n8. 获取元素属性:")
        img = page.ele('#test-img')
        print(f"   图片alt: {img.attr('alt')}")
        print(f"   图片src: {img.src}")

        # 9. 元素状态检查
        print("\n9. 元素状态检查:")
        disabled_btn = page.ele('#disabled-btn')
        print(f"   禁用按钮是否可用: {disabled_btn.is_enabled}")
        print(f"   禁用按钮是否显示: {disabled_btn.is_displayed}")

        # 10. 元素尺寸和位置
        print("\n10. 元素尺寸和位置:")
        click_btn = page.ele('#click-btn')
        print(f"   按钮尺寸: {click_btn.size}")
        print(f"   按钮位置: {click_btn.location}")

        print("\n" + "=" * 60)
        print("✓ 所有元素查找测试通过！")
        print("=" * 60)

    except Exception as e:
        print(f"\n✗ 测试失败: {e}")
        import traceback
        traceback.print_exc()
    finally:
        page.wait(2)
        page.quit()

if __name__ == '__main__':
    test_element_finding()

# -*- coding: utf-8 -*-
"""
示例2: 元素查找
测试功能：
- CSS选择器查找
- XPath查找
- 文本查找
- 属性查找
- 多元素查找
- 元素属性获取
"""

import os
import sys
import io

# 设置控制台输出编码为UTF-8（Windows兼容）
if sys.platform == 'win32':
    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')

sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))

from ruyipage import FirefoxPage, FirefoxOptions

def test_element_finding():
    """测试元素查找功能"""
    print("=" * 60)
    print("测试2: 元素查找")
    print("=" * 60)

    opts = FirefoxOptions()
    opts.headless(False)
    page = FirefoxPage(opts)

    try:
        # 加载测试页面
        test_page = os.path.join(os.path.dirname(__file__), 'test_pages', 'test_page.html')
        test_url = 'file:///' + os.path.abspath(test_page).replace('\\', '/')
        page.get(test_url)
        page.wait(1)

        # 1. 通过ID查找
        print("\n1. 通过ID查找元素:")
        title = page.ele('#main-title')
        print(f"   标题文本: {title.text}")
        print(f"   标签名: {title.tag}")

        # 2. 通过class查找
        print("\n2. 通过class查找元素:")
        test_div = page.ele('.test-class')
        print(f"   第一个.test-class元素: {test_div.text}")

        # 3. 查找所有匹配元素
        print("\n3. 查找所有.test-class元素:")
        all_test = page.eles('.test-class')
        print(f"   找到 {len(all_test)} 个元素")
        for i, elem in enumerate(all_test, 1):
            print(f"   元素{i}: {elem.text}")

        # 4. 通过XPath查找
        print("\n4. 通过XPath查找:")
        link = page.ele('xpath://a[@id="test-link"]')
        print(f"   链接文本: {link.text}")
        print(f"   链接地址: {link.link}")

        # 5. 通过文本查找
        print("\n5. 通过文本查找:")
        btn = page.ele('text:点击我')
        print(f"   按钮ID: {btn.attr('id')}")

        # 6. 通过属性查找
        print("\n6. 通过属性查找:")
        test_div = page.ele('[data-test="value"]')
        print(f"   data-test属性的元素: {test_div.text}")
        print(f"   所有属性: {test_div.attrs}")

        # 7. 组合选择器
        print("\n7. 组合选择器:")
        section = page.ele('#form-section')
        input_elem = section.ele('input[type="text"]')
        print(f"   表单区域内的文本输入框: {input_elem.attr('placeholder')}")

        # 8. 获取元素属性
        print("\n8. 获取元素属性:")
        img = page.ele('#test-img')
        print(f"   图片alt: {img.attr('alt')}")
        print(f"   图片src: {img.src}")

        # 9. 元素状态检查
        print("\n9. 元素状态检查:")
        disabled_btn = page.ele('#disabled-btn')
        print(f"   禁用按钮是否可用: {disabled_btn.is_enabled}")
        print(f"   禁用按钮是否显示: {disabled_btn.is_displayed}")

        # 10. 元素尺寸和位置
        print("\n10. 元素尺寸和位置:")
        click_btn = page.ele('#click-btn')
        print(f"   按钮尺寸: {click_btn.size}")
        print(f"   按钮位置: {click_btn.location}")

        print("\n" + "=" * 60)
        print("✓ 所有元素查找测试通过！")
        print("=" * 60)

    except Exception as e:
        print(f"\n✗ 测试失败: {e}")
        import traceback
        traceback.print_exc()
    finally:
        page.wait(2)
        page.quit()

if __name__ == '__main__':
    test_element_finding()

XPath Picker 综合演示

examples/42_xpath_picker_complex_showcase.py

完整展示 XPath Picker 在复杂节点、iframe、嵌套 iframe 和 open shadow root 中的拾取与代码生成能力。

GitHub 仓库查看仓库源码 opts.enable_xpath_pickerlaunch(xpath_picker=True)page.getpicker 自动生成代码链

启用 XPath Picker 浮窗
查看绝对 XPath 与相对 XPath
自动生成 RuyiPage 定位代码
处理 iframe 与 shadow root 嵌套结构

RuyiPage 选择器

核心 API

css: 选择器

tag: 选择器

text: 选择器

xpath: 选择器

选择器对比

快速上手

相关示例源码

元素查找：CSS / XPath / 文本 / 属性 / 容器内定位

XPath Picker 综合演示