元素mixins

mixins 模块提供可复用的功能，可以将其混合到元素类中以扩展其功能。

元素定位mixins

FindElementsMixin 为包含它的类提供元素查找功能。

pydoll.elements.mixins.find_elements_mixin

T `module-attribute`

T = TypeVar('T')

FindElementsMixin

Mixin providing comprehensive element finding and waiting capabilities.

Implements DOM element location using various selector strategies (CSS, XPath, etc.) with support for single/multiple element finding and configurable waiting. Classes using this mixin gain powerful element discovery without implementing complex location logic themselves.

find `async`

find(id=None, class_name=None, name=None, tag_name=None, text=None, timeout=0, find_all=False, raise_exc=True, **attributes)

Find element(s) using combination of common HTML attributes.

Flexible element location using standard attributes. Multiple attributes can be combined for specific selectors (builds XPath when multiple specified).

PARAMETER	DESCRIPTION
`id`	Element ID attribute value. TYPE: `Optional[str]` DEFAULT: `None`
`class_name`	CSS class name to match. TYPE: `Optional[str]` DEFAULT: `None`
`name`	Element name attribute value. TYPE: `Optional[str]` DEFAULT: `None`
`tag_name`	HTML tag name (e.g., "div", "input"). TYPE: `Optional[str]` DEFAULT: `None`
`text`	Text content to match within element. TYPE: `Optional[str]` DEFAULT: `None`
`timeout`	Maximum seconds to wait for elements to appear. TYPE: `int` DEFAULT: `0`
`find_all`	If True, returns all matches; if False, first match only. TYPE: `bool` DEFAULT: `False`
`raise_exc`	Whether to raise exception if no elements found. TYPE: `bool` DEFAULT: `True`
`**attributes`	Additional HTML attributes to match. TYPE: `dict[str, str]` DEFAULT: `{}`

RETURNS	DESCRIPTION
`Union[WebElement, list[WebElement], None]`	WebElement, list[WebElement], or None based on find_all and raise_exc.

RAISES	DESCRIPTION
`ValueError`	If no search criteria provided.
`ElementNotFound`	If no elements found and raise_exc=True.
`WaitElementTimeout`	If timeout specified and no elements appear in time.

query `async`

query(expression, timeout=0, find_all=False, raise_exc=True)

Find element(s) using raw CSS selector or XPath expression.

Direct access using CSS or XPath syntax. Selector type automatically determined based on expression pattern.

PARAMETER	DESCRIPTION
`expression`	Selector expression (CSS, XPath, ID with #, class with .). TYPE: `str`
`timeout`	Maximum seconds to wait for elements to appear. TYPE: `int` DEFAULT: `0`
`find_all`	If True, returns all matches; if False, first match only. TYPE: `bool` DEFAULT: `False`
`raise_exc`	Whether to raise exception if no elements found. TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`Union[WebElement, list[WebElement], None]`	WebElement, list[WebElement], or None based on find_all and raise_exc.

RAISES	DESCRIPTION
`ElementNotFound`	If no elements found and raise_exc=True.
`WaitElementTimeout`	If timeout specified and no elements appear in time.

find_or_wait_element `async`

find_or_wait_element(by, value, timeout=0, find_all=False, raise_exc=True)

Core element finding method with optional waiting capability.

Searches for elements with flexible waiting. If timeout specified, repeatedly attempts to find elements with 0.5s delays until success or timeout. Used by higher-level find() and query() methods.

PARAMETER	DESCRIPTION
`by`	Selector strategy (CSS_SELECTOR, XPATH, ID, etc.). TYPE: `By`
`value`	Selector value to locate element(s). TYPE: `str`
`timeout`	Maximum seconds to wait (0 = no waiting). TYPE: `int` DEFAULT: `0`
`find_all`	If True, returns all matches; if False, first match only. TYPE: `bool` DEFAULT: `False`
`raise_exc`	Whether to raise exception if no elements found. TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`Union[WebElement, list[WebElement], None]`	WebElement, list[WebElement], or None based on find_all and raise_exc.

RAISES	DESCRIPTION
`ElementNotFound`	If no elements found with timeout=0 and raise_exc=True.
`WaitElementTimeout`	If elements not found within timeout and raise_exc=True.

create_web_element

create_web_element(*args, **kwargs)

Create WebElement instance avoiding circular imports.

Factory method that dynamically imports WebElement at runtime to prevent circular import dependencies.

用法

Mixin 通常由库内部使用，用于组合功能。Tab 和 WebElement 等类使用 FindElementsMixin 来提供元素定位方法：

# 这些方法来自 FindElementsMixin
element = await tab.find(id="username")
elements = await tab.find(class_name="item", find_all=True)
element = await tab.query("#submit-button")

可用方法

FindElementsMixin 提供了多种元素定位的方法：

find() - 使用关键字参数的现代元素查找方法
query() - CSS 选择器和 XPath 查询
find_element() - 旧版元素定位方法
find_elements() - 查找多个元素的旧版方法

!!! 提示“现代 vs 传统” find() 方法是最新的、推荐的查找元素的方法。find_element() 和 find_elements() 方法保留下来，以实现向后兼容。