From de75793b9413ad669b7d0f0f82e8603c633e3fbb Mon Sep 17 00:00:00 2001
From: g1879 <g1879@qq.com>
Date: Fri, 21 Jun 2024 17:48:53 +0800
Subject: [PATCH] =?UTF-8?q?=E5=BC=80=E5=8F=91=E8=A7=86=E8=A7=89=E7=9B=B8?=
 =?UTF-8?q?=E5=AF=B9=E5=AE=9A=E4=BD=8D=EF=BC=8C=E6=9C=AA=E5=AE=8C=E6=88=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 DrissionPage/_elements/chromium_element.py  | 113 ++++++++++--
 DrissionPage/_elements/chromium_element.pyi |  15 +-
 DrissionPage/_functions/elements.py         |   6 +-
 DrissionPage/_functions/elements.pyi        |   1 -
 DrissionPage/_functions/locator.py          | 186 ++++++++++++++++----
 DrissionPage/_functions/locator.pyi         |   3 +
 DrissionPage/_pages/chromium_frame.py       |   6 +-
 DrissionPage/_pages/web_page.py             |   4 +-
 DrissionPage/_units/downloader.py           |   2 +-
 DrissionPage/_units/listener.py             |   8 +-
 DrissionPage/_units/selector.py             |   4 +-
 DrissionPage/_units/waiter.py               |  52 +++---
 12 files changed, 301 insertions(+), 99 deletions(-)

diff --git a/DrissionPage/_elements/chromium_element.py b/DrissionPage/_elements/chromium_element.py
index 12a2080..076965b 100644
--- a/DrissionPage/_elements/chromium_element.py
+++ b/DrissionPage/_elements/chromium_element.py
@@ -17,7 +17,7 @@ from .none_element import NoneElement
 from .session_element import make_session_ele
 from .._base.base import DrissionElement, BaseElement
 from .._functions.keys import input_text_or_keys
-from .._functions.locator import get_loc
+from .._functions.locator import get_loc, locator_to_tuple
 from .._functions.elements import ChromiumElementsList
 from .._functions.web import make_absolute_link, get_ele_txt, format_html, is_js_func, offset_scroll, get_blob
 from .._units.clicker import Clicker
@@ -339,7 +339,7 @@ class ChromiumElement(DrissionElement):
         """
         return ChromiumElementsList(self.owner, super().afters(locator, timeout, ele_only=ele_only))
 
-    def on(self, timeout=None):
+    def over(self, timeout=None):
         """获取覆盖在本元素上最上层的元素
         :param timeout: 等待元素出现的超时时间（秒）
         :return: 元素对象
@@ -351,21 +351,110 @@ class ChromiumElement(DrissionElement):
         else:
             return NoneElement(page=self.owner, method='on()', args={'timeout': timeout})
 
-    def under(self, locator=None):
+    def east(self, locator=None, index=1):
+        """获取元素右边某个指定元素
+        :param locator: 定位符，只支持str，且不支持xpath和css方式，传入int按像素距离获取
+        :param index: 第几个，从1开始
+        :return: 获取到的元素对象
+        """
+        return self._get_relative_eles(mode='east', locator=locator, index=index)
+
+    def south(self, locator=None, index=1):
+        """获取元素下方某个指定元素
+        :param locator: 定位符，只支持str，且不支持xpath和css方式，传入int按像素距离获取
+        :param index: 第几个，从1开始
+        :return: 获取到的元素对象
+        """
+        return self._get_relative_eles(mode='south', locator=locator, index=index)
+
+    def west(self, locator=None, index=1):
+        """获取元素左边某个指定元素
+        :param locator: 定位符，只支持str，且不支持xpath和css方式，传入int按像素距离获取
+        :param index: 第几个，从1开始
+        :return: 获取到的元素对象
+        """
+        return self._get_relative_eles(mode='west', locator=locator, index=index)
+
+    def north(self, locator=None, index=1):
+        """获取元素上方某个指定元素
+        :param locator: 定位符，只支持str，且不支持xpath和css方式，传入int按像素距离获取
+        :param index: 第几个，从1开始
+        :return: 获取到的元素对象
+        """
+        return self._get_relative_eles(mode='north', locator=locator, index=index)
+
+    def _get_relative_eles(self, mode='north', locator=None, index=1):
+        """获取元素下方某个指定元素
+        :param locator: 定位符，只支持str，且不支持xpath和css方式
+        :param index: 第几个，从1开始
+        :return: 获取到的元素对象
+        """
+        if locator and not (isinstance(locator, str) and not locator.startswith(
+                ('x:', 'xpath:', 'x=', 'xpath=', 'c:', 'css:', 'c=', 'css=')) or isinstance(locator, int)):
+            raise ValueError('locator参数只能是str格式且不支持xpath和css形式。')
         rect = self.states.has_rect
         if not rect:
             raise NoRectError
-        y = int(rect[2][1])
-        x = int(self.rect.midpoint[0])
-        while True:
-            y += 1
+
+        if mode == 'east':
+            cdp_data = {'x': int(rect[1][0]), 'y': int(self.rect.midpoint[1]),
+                        'includeUserAgentShadowDOM': True, 'ignorePointerEventsNone': False}
+            variable = 'x'
+            minus = False
+        elif mode == 'south':
+            cdp_data = {'x': int(self.rect.midpoint[0]), 'y': int(rect[2][1]),
+                        'includeUserAgentShadowDOM': True, 'ignorePointerEventsNone': False}
+            variable = 'y'
+            minus = False
+        elif mode == 'west':
+            cdp_data = {'x': int(rect[0][0]), 'y': int(self.rect.midpoint[1]),
+                        'includeUserAgentShadowDOM': True, 'ignorePointerEventsNone': False}
+            variable = 'x'
+            minus = True
+        else:  # north
+            cdp_data = {'x': int(self.rect.midpoint[0]), 'y': int(rect[0][1]),
+                        'includeUserAgentShadowDOM': True, 'ignorePointerEventsNone': False}
+            variable = 'y'
+            minus = True
+
+        if isinstance(locator, int):
+            if minus:
+                cdp_data[variable] -= locator
+            else:
+                cdp_data[variable] += locator
             try:
-                ele = self.owner.run_cdp('DOM.getNodeForLocation', x=x, y=y)
-                break
+                return ChromiumElement(owner=self.owner,
+                                       backend_id=self.owner.run_cdp('DOM.getNodeForLocation',
+                                                                     **cdp_data)['backendNodeId'])
+            except CDPError:
+                return NoneElement(page=self.owner, method=f'{mode}()', args={'locator': locator})
+
+        num = 0
+        value = -3 if minus else 3
+        size = self.owner.rect.size
+        max_len = size[0] if mode == 'east' else size[1]
+        # loc_data = {'tag': None, 'and': True, 'args': [('属性名称', '匹配内容', '匹配方式', '是否否定')]}
+        loc_data = locator_to_tuple(locator) if locator else None
+        curr_ele = None
+        while 0 < cdp_data[variable] < max_len:
+            cdp_data[variable] += value
+            try:
+                bid = self.owner.run_cdp('DOM.getNodeForLocation', **cdp_data)['backendNodeId']
+                if bid == curr_ele:
+                    continue
+                else:
+                    curr_ele = bid
+                ele = self.owner.run_cdp('DOM.describeNode', backendNodeId=bid)['node']
+
+                # print(ele)
+                if loc_data is None:  # todo
+                    num += 1
+                    if num == index:
+                        return ChromiumElement(owner=self.owner, backend_id=bid)
             except:
-                raise
-                continue
-        return ChromiumElement(owner=self.owner, backend_id=ele['backendNodeId'])
+                pass
+
+        return NoneElement(page=self.owner, method=f'{mode}()', args={'locator': locator})
 
     def attr(self, attr):
         """返回一个attribute属性值
diff --git a/DrissionPage/_elements/chromium_element.pyi b/DrissionPage/_elements/chromium_element.pyi
index d483018..44ab46c 100644
--- a/DrissionPage/_elements/chromium_element.pyi
+++ b/DrissionPage/_elements/chromium_element.pyi
@@ -159,18 +159,23 @@ class ChromiumElement(DrissionElement):
                timeout: float = None,
                ele_only: bool = True) -> Union[ChromiumElementsList, List[Union[ChromiumElement, str]]]: ...
 
-    def on(self, timeout: float = None) -> ChromiumElement: ...
+    def over(self, timeout: float = None) -> ChromiumElement: ...
 
-    def under(self, locator: str = None) -> ChromiumElement: ...
+    def south(self, locator: str = None, index: int = 1) -> ChromiumElement: ...
 
-    def above(self, locator: str = None) -> ChromiumElement: ...
+    def north(self, locator: str = None, index: int = 1) -> ChromiumElement: ...
 
-    def left(self, locator: str = None) -> ChromiumElement: ...
+    def west(self, locator: str = None, index: int = 1) -> ChromiumElement: ...
 
-    def right(self, locator: str = None) -> ChromiumElement: ...
+    def east(self, locator: str = None, index: int = 1) -> ChromiumElement: ...
 
     def offset(self, offset_x, offset_y) -> ChromiumElement: ...
 
+    def _get_relative_eles(self,
+                           mode: str = 'north',
+                           locator: Union[int, str] = None,
+                           index: int = 1) -> ChromiumElement: ...
+
     @property
     def wait(self) -> ElementWaiter: ...
 
diff --git a/DrissionPage/_functions/elements.py b/DrissionPage/_functions/elements.py
index 69269f2..d77d359 100644
--- a/DrissionPage/_functions/elements.py
+++ b/DrissionPage/_functions/elements.py
@@ -14,13 +14,10 @@ class SessionElementsList(list):
     def __init__(self, page=None, *args):
         super().__init__(*args)
         self._page = page
-        self._getter = None
 
     @property
     def get(self):
-        if self._getter is None:
-            self._getter = Getter(self)
-        return self._getter
+        return Getter(self)
 
     @property
     def filter(self):
@@ -83,7 +80,6 @@ class SessionFilterOne(object):
         :param index: 元素序号，从1开始
         :return: 对象自身
         """
-        print('s')
         self._index = index
         return self
 
diff --git a/DrissionPage/_functions/elements.pyi b/DrissionPage/_functions/elements.pyi
index 3484711..41562e5 100644
--- a/DrissionPage/_functions/elements.pyi
+++ b/DrissionPage/_functions/elements.pyi
@@ -21,7 +21,6 @@ def get_eles(locators: Union[List[str], tuple],
 
 class SessionElementsList(list):
     _page = ...
-    _getter: Optional[Getter] = ...
 
     def __init__(self, page=None, *args): ...
 
diff --git a/DrissionPage/_functions/locator.py b/DrissionPage/_functions/locator.py
index ac65759..2f36ad5 100644
--- a/DrissionPage/_functions/locator.py
+++ b/DrissionPage/_functions/locator.py
@@ -8,6 +8,129 @@
 from re import split
 from .by import By
 
+格式 = {
+    'and': True,
+    'args': ('属性名称', '属性值', '匹配方式', '是否否定')
+}
+
+
+def locator_to_tuple(loc):
+    loc = _preprocess(loc)
+    # todo
+
+    # 多属性查找
+    if loc.startswith(('@@', '@|', '@!')) and loc not in ('@@', '@|', '@!'):
+        loc_str = _make_multi_xpath_str('*', loc)[1]
+
+    # 单属性查找
+    elif loc.startswith('@') and loc != '@':
+        loc_str = _make_single_xpath_str('*', loc)[1]
+
+    # 根据tag name查找
+    elif loc.startswith(('tag:', 'tag=')) and loc not in ('tag:', 'tag='):
+        at_ind = loc.find('@')
+        if at_ind == -1:
+            loc_str = f'//*[name()="{loc[4:]}"]'
+        elif loc[at_ind:].startswith(('@@', '@|', '@!')):
+            loc_str = _make_multi_xpath_str(loc[4:at_ind], loc[at_ind:])[1]
+        else:
+            loc_str = _make_single_xpath_str(loc[4:at_ind], loc[at_ind:])[1]
+
+    # 根据文本查找
+    elif loc.startswith('text='):
+        loc_str = f'//*[text()={_make_search_str(loc[5:])}]'
+    elif loc.startswith('text:') and loc != 'text:':
+        loc_str = f'//*/text()[contains(., {_make_search_str(loc[5:])})]/..'
+    elif loc.startswith('text^') and loc != 'text^':
+        loc_str = f'//*/text()[starts-with(., {_make_search_str(loc[5:])})]/..'
+    elif loc.startswith('text$') and loc != 'text$':
+        loc_str = f'//*/text()[substring(., string-length(.) - string-length({_make_search_str(loc[5:])}) +1) = ' \
+                  f'{_make_search_str(loc[5:])}]/..'
+
+    # 用xpath查找
+    elif loc.startswith(('xpath:', 'xpath=')) and loc not in ('xpath:', 'xpath='):
+        loc_str = loc[6:]
+    elif loc.startswith(('x:', 'x=')) and loc not in ('x:', 'x='):
+        loc_str = loc[2:]
+
+    # 用css selector查找
+    elif loc.startswith(('css:', 'css=')) and loc not in ('css:', 'css='):
+        loc_by = 'css selector'
+        loc_str = loc[4:]
+    elif loc.startswith(('c:', 'c=')) and loc not in ('c:', 'c='):
+        loc_by = 'css selector'
+        loc_str = loc[2:]
+
+    # 根据文本模糊查找
+    elif loc:
+        loc_str = f'//*/text()[contains(., {_make_search_str(loc)})]/..'
+    else:
+        loc_str = '//*'
+
+    return {}
+
+
+def _get_args(tag: str = None, text: str = '') -> tuple:
+    """生成多属性查找的xpath语句
+    :param tag: 标签名
+    :param text: 待处理的字符串
+    :return: xpath字符串
+    """
+    # todo
+    arg_list = []
+    args = split(r'(@!|@@|@\|)', text)[1:]
+    if '@@' in args and '@|' in args:
+        raise ValueError('@@和@|不能同时出现在一个定位语句中。')
+    elif '@@' in args:
+        _and = True
+    else:  # @|
+        _and = False
+
+    for k in range(0, len(args) - 1, 2):
+        r = split(r'([:=$^])', args[k + 1], maxsplit=1)
+        arg_str = ''
+        len_r = len(r)
+
+        if not r[0]:  # 不查询任何属性
+            arg_str = 'not(@*)'
+
+        else:
+            ignore = True if args[k] == '@!' else False  # 是否去除某个属性
+            if len_r != 3:  # 只有属性名没有属性内容，查询是否存在该属性
+                arg_str = 'normalize-space(text())' if r[0] in ('text()', 'tx()') else f'@{r[0]}'
+
+            elif len_r == 3:  # 属性名和内容都有
+                arg = '.' if r[0] in ('text()', 'tx()') else f'@{r[0]}'
+                symbol = r[1]
+                if symbol == '=':
+                    arg_str = f'{arg}={_make_search_str(r[2])}'
+
+                elif symbol == ':':
+                    arg_str = f'contains({arg},{_make_search_str(r[2])})'
+
+                elif symbol == '^':
+                    arg_str = f'starts-with({arg},{_make_search_str(r[2])})'
+
+                elif symbol == '$':
+                    arg_str = f'substring({arg}, string-length({arg}) - string-length({_make_search_str(r[2])}) +1) ' \
+                              f'= {_make_search_str(r[2])}'
+
+                else:
+                    raise ValueError(f'符号不正确：{symbol}')
+
+            if arg_str and ignore:
+                arg_str = f'not({arg_str})'
+
+        if arg_str:
+            arg_list.append(arg_str)
+
+    arg_str = ' and '.join(arg_list) if _and else ' or '.join(arg_list)
+    if tag != '*':
+        condition = f' and ({arg_str})' if arg_str else ''
+        arg_str = f'name()="{tag}"{condition}'
+
+    return 'xpath', f'//*[{arg_str}]' if arg_str else f'//*'
+
 
 def is_loc(text):
     """返回text是否定位符"""
@@ -49,26 +172,8 @@ def str_to_xpath_loc(loc):
     :return: 匹配符元组
     """
     loc_by = 'xpath'
+    loc = _preprocess(loc)
 
-    if loc.startswith('.'):
-        if loc.startswith(('.=', '.:', '.^', '.$')):
-            loc = loc.replace('.', '@class', 1)
-        else:
-            loc = loc.replace('.', '@class=', 1)
-
-    elif loc.startswith('#'):
-        if loc.startswith(('#=', '#:', '#^', '#$')):
-            loc = loc.replace('#', '@id', 1)
-        else:
-            loc = loc.replace('#', '@id=', 1)
-
-    elif loc.startswith(('t:', 't=')):
-        loc = f'tag:{loc[2:]}'
-
-    elif loc.startswith(('tx:', 'tx=', 'tx^', 'tx$')):
-        loc = f'text{loc[2:]}'
-
-    # ------------------------------------------------------------------
     # 多属性查找
     if loc.startswith(('@@', '@|', '@!')) and loc not in ('@@', '@|', '@!'):
         loc_str = _make_multi_xpath_str('*', loc)[1]
@@ -127,26 +232,8 @@ def str_to_css_loc(loc):
     :return: 匹配符元组
     """
     loc_by = 'css selector'
+    loc = _preprocess(loc)
 
-    if loc.startswith('.'):
-        if loc.startswith(('.=', '.:', '.^', '.$')):
-            loc = loc.replace('.', '@class', 1)
-        else:
-            loc = loc.replace('.', '@class=', 1)
-
-    elif loc.startswith('#'):
-        if loc.startswith(('#=', '#:', '#^', '#$')):
-            loc = loc.replace('#', '@id', 1)
-        else:
-            loc = loc.replace('#', '@id=', 1)
-
-    elif loc.startswith(('t:', 't=')):
-        loc = f'tag:{loc[2:]}'
-
-    elif loc.startswith(('tx:', 'tx=', 'tx^', 'tx$')):
-        loc = f'text{loc[2:]}'
-
-    # ------------------------------------------------------------------
     # 多属性查找
     if loc.startswith(('@@', '@|', '@!')) and loc not in ('@@', '@|', '@!'):
         loc_str = _make_multi_css_str('*', loc)[1]
@@ -472,3 +559,26 @@ def css_trans(txt):
     c = ('!', '"', '#', '$', '%', '&', '\'', '(', ')', '*', '+', ',', '-', '.', '/', ':', ';', '<', '=', '>', '?', '@',
          '[', '\\', ']', '^', '`', ',', '{', '|', '}', '~', ' ')
     return ''.join([fr'\{i}' if i in c else i for i in txt])
+
+
+def _preprocess(loc):
+    """对缩写进行处理，替换回完整写法"""
+    if loc.startswith('.'):
+        if loc.startswith(('.=', '.:', '.^', '.$')):
+            loc = loc.replace('.', '@class', 1)
+        else:
+            loc = loc.replace('.', '@class=', 1)
+
+    elif loc.startswith('#'):
+        if loc.startswith(('#=', '#:', '#^', '#$')):
+            loc = loc.replace('#', '@id', 1)
+        else:
+            loc = loc.replace('#', '@id=', 1)
+
+    elif loc.startswith(('t:', 't=')):
+        loc = f'tag:{loc[2:]}'
+
+    elif loc.startswith(('tx:', 'tx=', 'tx^', 'tx$')):
+        loc = f'text{loc[2:]}'
+
+    return loc
diff --git a/DrissionPage/_functions/locator.pyi b/DrissionPage/_functions/locator.pyi
index 2f79a69..662b4ba 100644
--- a/DrissionPage/_functions/locator.pyi
+++ b/DrissionPage/_functions/locator.pyi
@@ -8,6 +8,9 @@
 from typing import Union
 
 
+def locator_to_tuple(loc: str) -> dict: ...
+
+
 def is_loc(text: str) -> bool: ...
 
 
diff --git a/DrissionPage/_pages/chromium_frame.py b/DrissionPage/_pages/chromium_frame.py
index 73904b4..f3e1ab5 100644
--- a/DrissionPage/_pages/chromium_frame.py
+++ b/DrissionPage/_pages/chromium_frame.py
@@ -453,7 +453,7 @@ class ChromiumFrame(ChromiumBase):
         """返回文档中当前元素前面符合条件的元素或节点组成的列表，可用查询语法筛选
         查找范围不限同级元素，而是整个DOM文档
         :param locator: 用于筛选的查询语法
-        :param timeout: 查找节点的超时时间
+        :param timeout: 查找节点的超时时间（秒）
         :param ele_only: 是否只获取元素，为False时把文本、注释节点也纳入
         :return: 本元素前面的元素或节点组成的列表
         """
@@ -463,7 +463,7 @@ class ChromiumFrame(ChromiumBase):
         """返回文档中当前元素后面符合条件的元素或节点组成的列表，可用查询语法筛选
         查找范围不限同级元素，而是整个DOM文档
         :param locator: 用于筛选的查询语法
-        :param timeout: 查找节点的超时时间
+        :param timeout: 查找节点的超时时间（秒）
         :param ele_only: 是否只获取元素，为False时把文本、注释节点也纳入
         :return: 本元素前面的元素或节点组成的列表
         """
@@ -559,7 +559,7 @@ class ChromiumFrame(ChromiumBase):
     def _find_elements(self, locator, timeout=None, index=1, relative=False, raise_err=None):
         """在frame内查找单个元素
         :param locator: 定位符或元素对象
-        :param timeout: 查找超时时间
+        :param timeout: 查找超时时间（秒）
         :param index: 第几个结果，从1开始，可传入负数获取倒数第几个，为None返回所有
         :param relative: WebPage用的表示是否相对定位的参数
         :param raise_err: 找不到元素是是否抛出异常，为None时根据全局设置
diff --git a/DrissionPage/_pages/web_page.py b/DrissionPage/_pages/web_page.py
index 2a8ef93..ea9e83d 100644
--- a/DrissionPage/_pages/web_page.py
+++ b/DrissionPage/_pages/web_page.py
@@ -401,7 +401,7 @@ class WebPage(SessionPage, ChromiumPage, BasePage):
     def _find_elements(self, locator, timeout=None, index=1, relative=False, raise_err=None):
         """返回页面中符合条件的元素、属性或节点文本，默认返回第一个
         :param locator: 元素的定位信息，可以是元素对象，loc元组，或查询字符串
-        :param timeout: 查找元素超时时间，d模式专用
+        :param timeout: 查找元素超时时间（秒），d模式专用
         :param index: 第几个结果，从1开始，可传入负数获取倒数第几个，为None返回所有
         :param relative: WebPage用的表示是否相对定位的参数
         :param raise_err: 找不到元素是是否抛出异常，为None时根据全局设置
@@ -414,7 +414,7 @@ class WebPage(SessionPage, ChromiumPage, BasePage):
 
     def quit(self, timeout=5, force=True):
         """关闭浏览器和Session
-        :param timeout: 等待浏览器关闭超时时间
+        :param timeout: 等待浏览器关闭超时时间（秒）
         :param force: 关闭超时是否强制终止进程
         :return: None
         """
diff --git a/DrissionPage/_units/downloader.py b/DrissionPage/_units/downloader.py
index 73dc956..ec41cc4 100644
--- a/DrissionPage/_units/downloader.py
+++ b/DrissionPage/_units/downloader.py
@@ -292,7 +292,7 @@ class DownloadMission(object):
     def wait(self, show=True, timeout=None, cancel_if_timeout=True):
         """等待任务结束
         :param show: 是否显示下载信息
-        :param timeout: 超时时间，为None则无限等待
+        :param timeout: 超时时间（秒），为None则无限等待
         :param cancel_if_timeout: 超时时是否取消任务
         :return: 等待成功返回完整路径，否则返回False
         """
diff --git a/DrissionPage/_units/listener.py b/DrissionPage/_units/listener.py
index 589b225..ef49b35 100644
--- a/DrissionPage/_units/listener.py
+++ b/DrissionPage/_units/listener.py
@@ -119,7 +119,7 @@ class Listener(object):
     def wait(self, count=1, timeout=None, fit_count=True, raise_err=None):
         """等待符合要求的数据包到达指定数量
         :param count: 需要捕捉的数据包数量
-        :param timeout: 超时时间，为None无限等待
+        :param timeout: 超时时间（秒），为None无限等待
         :param fit_count: 是否必须满足总数要求，发生超时，为True返回False，为False返回已捕捉到的数据包
         :param raise_err: 超时时是否抛出错误，为None时根据Settings设置
         :return: count为1时返回数据包对象，大于1时返回列表，超时且fit_count为True时返回False
@@ -159,7 +159,7 @@ class Listener(object):
     def steps(self, count=None, timeout=None, gap=1):
         """用于单步操作，可实现每收到若干个数据包执行一步操作（如翻页）
         :param count: 需捕获的数据包总数，为None表示无限
-        :param timeout: 每个数据包等待时间，为None表示无限
+        :param timeout: 每个数据包等待时间（秒），为None表示无限
         :param gap: 每接收到多少个数据包返回一次数据
         :return: 用于在接收到监听目标时触发动作的可迭代对象
         """
@@ -219,7 +219,7 @@ class Listener(object):
 
     def wait_silent(self, timeout=None, targets_only=False, limit=0):
         """等待所有请求结束
-        :param timeout: 超时，为None时无限等待
+        :param timeout: 超时时间（秒），为None时无限等待
         :param targets_only: 是否只等待targets指定的请求结束
         :param limit: 剩下多少个连接时视为结束
         :return: 返回是否等待成功
@@ -480,7 +480,7 @@ class DataPacket(object):
 
     def wait_extra_info(self, timeout=None):
         """等待额外的信息加载完成
-        :param timeout: 超时时间，None为无限等待
+        :param timeout: 超时时间（秒），None为无限等待
         :return: 是否等待成功
         """
         if timeout is None:
diff --git a/DrissionPage/_units/selector.py b/DrissionPage/_units/selector.py
index fe5a23a..c97aded 100644
--- a/DrissionPage/_units/selector.py
+++ b/DrissionPage/_units/selector.py
@@ -23,7 +23,7 @@ class SelectElement(object):
     def __call__(self, text_or_index, timeout=None):
         """选定下拉列表中子元素
         :param text_or_index: 根据文本、值选或序号择选项，若允许多选，传入list或tuple可多选
-        :param timeout: 超时时间，不输入默认实用页面超时时间
+        :param timeout: 超时时间（秒），不输入默认实用页面超时时间
         :return: None
         """
         para_type = 'index' if isinstance(text_or_index, int) else 'text'
@@ -82,7 +82,7 @@ class SelectElement(object):
     def by_text(self, text, timeout=None):
         """此方法用于根据text值选择项。当元素是多选列表时，可以接收list或tuple
         :param text: text属性值，传入list或tuple可选择多项
-        :param timeout: 超时时间，为None默认使用页面超时时间
+        :param timeout: 超时时间（秒），为None默认使用页面超时时间
         :return: 是否选择成功
         """
         return self._select(text, 'text', False, timeout)
diff --git a/DrissionPage/_units/waiter.py b/DrissionPage/_units/waiter.py
index 1133d7a..87e19ee 100644
--- a/DrissionPage/_units/waiter.py
+++ b/DrissionPage/_units/waiter.py
@@ -36,7 +36,7 @@ class BaseWaiter(OriginWaiter):
     def ele_deleted(self, loc_or_ele, timeout=None, raise_err=None):
         """等待元素从DOM中删除
         :param loc_or_ele: 要等待的元素，可以是已有元素、定位符
-        :param timeout: 超时时间，默认读取页面超时时间
+        :param timeout: 超时时间（秒），默认读取页面超时时间
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 是否等待成功
         """
@@ -46,7 +46,7 @@ class BaseWaiter(OriginWaiter):
     def ele_displayed(self, loc_or_ele, timeout=None, raise_err=None):
         """等待元素变成显示状态
         :param loc_or_ele: 要等待的元素，可以是已有元素、定位符
-        :param timeout: 超时时间，默认读取页面超时时间
+        :param timeout: 超时时间（秒），默认读取页面超时时间
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 是否等待成功
         """
@@ -65,7 +65,7 @@ class BaseWaiter(OriginWaiter):
     def ele_hidden(self, loc_or_ele, timeout=None, raise_err=None):
         """等待元素变成隐藏状态
         :param loc_or_ele: 要等待的元素，可以是已有元素、定位符
-        :param timeout: 超时时间，默认读取页面超时时间
+        :param timeout: 超时时间（秒），默认读取页面超时时间
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 是否等待成功
         """
@@ -84,7 +84,7 @@ class BaseWaiter(OriginWaiter):
     def eles_loaded(self, locators, timeout=None, any_one=False, raise_err=None):
         """等待元素加载到DOM，可等待全部或任意一个
         :param locators: 要等待的元素，输入定位符，用list输入多个
-        :param timeout: 超时时间，默认读取页面超时时间
+        :param timeout: 超时时间（秒），默认读取页面超时时间
         :param any_one: 是否等待到一个就返回
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 成功返回True，失败返回False
@@ -134,7 +134,7 @@ class BaseWaiter(OriginWaiter):
 
     def load_start(self, timeout=None, raise_err=None):
         """等待页面开始加载
-        :param timeout: 超时时间，为None时使用页面timeout属性
+        :param timeout: 超时时间（秒），为None时使用页面timeout属性
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 是否等待成功
         """
@@ -142,7 +142,7 @@ class BaseWaiter(OriginWaiter):
 
     def doc_loaded(self, timeout=None, raise_err=None):
         """等待页面加载完成
-        :param timeout: 超时时间，为None时使用页面timeout属性
+        :param timeout: 超时时间（秒），为None时使用页面timeout属性
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 是否等待成功
         """
@@ -159,7 +159,7 @@ class BaseWaiter(OriginWaiter):
 
     def download_begin(self, timeout=None, cancel_it=False):
         """等待浏览器下载开始，可将其拦截
-        :param timeout: 超时时间，None使用页面对象超时时间
+        :param timeout: 超时时间（秒），None使用页面对象超时时间
         :param cancel_it: 是否取消该任务
         :return: 成功返回任务对象，失败返回False
         """
@@ -185,7 +185,7 @@ class BaseWaiter(OriginWaiter):
         """等待url变成包含或不包含指定文本
         :param text: 用于识别的文本
         :param exclude: 是否排除，为True时当url不包含text指定文本时返回True
-        :param timeout: 超时时间
+        :param timeout: 超时时间（秒）
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 是否等待成功
         """
@@ -195,7 +195,7 @@ class BaseWaiter(OriginWaiter):
         """等待title变成包含或不包含指定文本
         :param text: 用于识别的文本
         :param exclude: 是否排除，为True时当title不包含text指定文本时返回True
-        :param timeout: 超时时间
+        :param timeout: 超时时间（秒）
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 是否等待成功
         """
@@ -206,7 +206,7 @@ class BaseWaiter(OriginWaiter):
         :param arg: 要被匹配的属性
         :param text: 用于识别的文本
         :param exclude: 是否排除，为True时当属性不包含text指定文本时返回True
-        :param timeout: 超时时间
+        :param timeout: 超时时间（秒）
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 是否等待成功
         """
@@ -232,7 +232,7 @@ class BaseWaiter(OriginWaiter):
 
     def _loading(self, timeout=None, start=True, gap=.01, raise_err=None):
         """等待页面开始加载或加载完成
-        :param timeout: 超时时间，为None时使用页面timeout属性
+        :param timeout: 超时时间（秒），为None时使用页面timeout属性
         :param start: 等待开始还是结束
         :param gap: 间隔秒数
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
@@ -257,7 +257,7 @@ class TabWaiter(BaseWaiter):
 
     def downloads_done(self, timeout=None, cancel_if_timeout=True):
         """等待所有浏览器下载任务结束
-        :param timeout: 超时时间，为None时无限等待
+        :param timeout: 超时时间（秒），为None时无限等待
         :param cancel_if_timeout: 超时时是否取消剩余任务
         :return: 是否等待成功
         """
@@ -297,7 +297,7 @@ class PageWaiter(TabWaiter):
 
     def new_tab(self, timeout=None, raise_err=None):
         """等待新标签页出现
-        :param timeout: 等待超时时间，为None则使用页面对象timeout属性
+        :param timeout: 超时时间（秒），为None则使用页面对象timeout属性
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 等到新标签页返回其id，否则返回False
         """
@@ -316,7 +316,7 @@ class PageWaiter(TabWaiter):
 
     def all_downloads_done(self, timeout=None, cancel_if_timeout=True):
         """等待所有浏览器下载任务结束
-        :param timeout: 超时时间，为None时无限等待
+        :param timeout: 超时时间（秒），为None时无限等待
         :param cancel_if_timeout: 超时时是否取消剩余任务
         :return: 是否等待成功
         """
@@ -356,7 +356,7 @@ class ElementWaiter(OriginWaiter):
 
     def deleted(self, timeout=None, raise_err=None):
         """等待元素从dom删除
-        :param timeout: 超时时间，为None使用元素所在页面timeout属性
+        :param timeout: 超时时间（秒），为None使用元素所在页面timeout属性
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 是否等待成功
         """
@@ -364,7 +364,7 @@ class ElementWaiter(OriginWaiter):
 
     def displayed(self, timeout=None, raise_err=None):
         """等待元素从dom显示
-        :param timeout: 超时时间，为None使用元素所在页面timeout属性
+        :param timeout: 超时时间（秒），为None使用元素所在页面timeout属性
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 是否等待成功
         """
@@ -372,7 +372,7 @@ class ElementWaiter(OriginWaiter):
 
     def hidden(self, timeout=None, raise_err=None):
         """等待元素从dom隐藏
-        :param timeout: 超时时间，为None使用元素所在页面timeout属性
+        :param timeout: 超时时间（秒），为None使用元素所在页面timeout属性
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 是否等待成功
         """
@@ -380,7 +380,7 @@ class ElementWaiter(OriginWaiter):
 
     def covered(self, timeout=None, raise_err=None):
         """等待当前元素被遮盖
-        :param timeout: 超时时间，为None使用元素所在页面timeout属性
+        :param timeout: 超时时间（秒），为None使用元素所在页面timeout属性
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 成功返回覆盖元素id，返回False
         """
@@ -388,7 +388,7 @@ class ElementWaiter(OriginWaiter):
 
     def not_covered(self, timeout=None, raise_err=None):
         """等待当前元素不被遮盖
-        :param timeout: 超时时间，为None使用元素所在页面timeout属性
+        :param timeout: 超时时间（秒），为None使用元素所在页面timeout属性
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 是否等待成功
         """
@@ -396,7 +396,7 @@ class ElementWaiter(OriginWaiter):
 
     def enabled(self, timeout=None, raise_err=None):
         """等待当前元素变成可用
-        :param timeout: 超时时间，为None使用元素所在页面timeout属性
+        :param timeout: 超时时间（秒），为None使用元素所在页面timeout属性
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 是否等待成功
         """
@@ -404,7 +404,7 @@ class ElementWaiter(OriginWaiter):
 
     def disabled(self, timeout=None, raise_err=None):
         """等待当前元素变成不可用
-        :param timeout: 超时时间，为None使用元素所在页面timeout属性
+        :param timeout: 超时时间（秒），为None使用元素所在页面timeout属性
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 是否等待成功
         """
@@ -412,7 +412,7 @@ class ElementWaiter(OriginWaiter):
 
     def disabled_or_deleted(self, timeout=None, raise_err=None):
         """等待当前元素变成不可用或从DOM移除
-        :param timeout: 超时时间，为None使用元素所在页面timeout属性
+        :param timeout: 超时时间（秒），为None使用元素所在页面timeout属性
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 是否等待成功
         """
@@ -431,7 +431,7 @@ class ElementWaiter(OriginWaiter):
 
     def stop_moving(self, timeout=None, gap=.1, raise_err=None):
         """等待当前元素停止运动
-        :param timeout: 超时时间，为None使用元素所在页面timeout属性
+        :param timeout: 超时时间（秒），为None使用元素所在页面timeout属性
         :param gap: 检测间隔时间
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 是否等待成功
@@ -465,7 +465,7 @@ class ElementWaiter(OriginWaiter):
     def clickable(self, wait_moved=True, timeout=None, raise_err=None):
         """等待当前元素可被点击
         :param wait_moved: 是否等待元素运动结束
-        :param timeout: 超时时间，为None使用元素所在页面timeout属性
+        :param timeout: 超时时间（秒），为None使用元素所在页面timeout属性
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 是否等待成功
         """
@@ -478,7 +478,7 @@ class ElementWaiter(OriginWaiter):
 
     def has_rect(self, timeout=None, raise_err=None):
         """等待当前元素有大小及位置属性
-        :param timeout: 超时时间，为None使用元素所在页面timeout属性
+        :param timeout: 超时时间（秒），为None使用元素所在页面timeout属性
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :return: 成功返回元素四角坐标（左上 右上 右下 左下），失败返回False
         """
@@ -488,7 +488,7 @@ class ElementWaiter(OriginWaiter):
         """等待元素某个元素状态到达指定状态
         :param attr: 状态名称
         :param mode: 等待True还是False
-        :param timeout: 超时时间，为None使用元素所在页面timeout属性
+        :param timeout: 超时时间（秒），为None使用元素所在页面timeout属性
         :param raise_err: 等待失败时是否报错，为None时根据Settings设置
         :param err_text: 抛出错误时显示的信息
         :return: 是否等待成功