From 1f52cd723ae1a5681f080c0fa4513b1e4ba75103 Mon Sep 17 00:00:00 2001
From: g1879 <g1879@qq.com>
Date: Sat, 11 Dec 2021 17:49:46 +0800
Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E6=94=B9=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/使用方法/获取元素属性.md | 35 -------------
docs/使用方法/获取页面元素.md | 99 ++++++++++++++++++++++++++---------
2 files changed, 74 insertions(+), 60 deletions(-)
delete mode 100644 docs/使用方法/获取元素属性.md
diff --git a/docs/使用方法/获取元素属性.md b/docs/使用方法/获取元素属性.md
deleted file mode 100644
index 978d232..0000000
--- a/docs/使用方法/获取元素属性.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# 获取元素信息
-
-```python
-element.html # 返回元素 outerHTML
-element.inner_html # 返回元素 innerHTML
-element.tag # 返回元素 tag name
-element.text # 返回元素 innerText 值
-element.link # 返回元素 href 或 src 绝对 url
-element.texts() # 返回元素内所有直接子节点的文本，包括元素和文本节点，可指定只返回文本节点
-element.attrs # 返回元素所有属性的字典
-element.attr(attr) # 返回元素指定attribute属性的值
-element.prop(prop) # 返回元素指定property属性的值，d 模式独有
-element.css_path # 返回元素绝对 css 路径
-element.xpath # 返回元素绝对 xpath 路径
-element.parent # 返回元素父元素
-element.next # 返回元素后一个兄弟元素
-element.prev # 返回元素前一个兄弟元素
-element.parents(num) # 返回第 num 级父元素
-element.nexts(num, mode) # 返回后面第几个元素或节点
-element.prevs(num, mode) # 返回前面第几个元素或节点
-element.ele(loc_or_str, timeout) # 返回当前元素下级第一个符合条件的子元素、属性或节点文本
-element.eles(loc_or_str, timeout) # 返回当前元素下级所有符合条件的子元素、属性或节点文本
-
-# d 模式独有：
-element.before # 获取伪元素 before 内容
-element.after # 获取伪元素 after 内容
-element.is_valid # 用于判断元素是否还在dom中
-element.size # 获取元素大小
-element.location # 获取元素位置
-element.shadow_root # 获取元素下的 ShadowRoot 元素
-element.get_style_property(style, pseudo_ele) # 获取元素样式属性值，可获取伪元素的
-element.is_selected() # 返回元素是否被选中
-element.is_enabled() # 返回元素是否可用
-element.is_displayed() # 返回元素是否可见
-```
\ No newline at end of file
diff --git a/docs/使用方法/获取页面元素.md b/docs/使用方法/获取页面元素.md
index 0801081..c5d4d7f 100644
--- a/docs/使用方法/获取页面元素.md
+++ b/docs/使用方法/获取页面元素.md
@@ -9,7 +9,51 @@ shadow-root 的 shadow_root 属性。获取到的元素可继续用这些方法
d 模式获取元素的方法内置了等待，默认使用元素所属页面的超时设置，也可用在每次获取元素时单独设置等待时间。
-简单示例：
+看一个例子，用显性等待方式定位第一个文本包含 some text 的元素。可以看出本库的定位语法比 selenium 做了大幅度精简，而且功能更强大：
+
+```python
+# 使用 selenium：
+element = WebDriverWait(driver).until(ec.presence_of_element_located((By.XPATH, '//*[contains(text(), "some text")]')))
+
+# 使用 DrissionPage：
+element = page('some text')
+```
+
+## 简单示例：
+
+```html
+
+<html>
+<body>
+<div id="one">
+ <p class="p_cls" name="row1">第一行</p>
+ <p class="p_cls" name="row2">第二行</p>
+ <p class="p_cls">第三行</p>
+</div>
+<div id="two">
+ 第二个div
+</div>
+</body>
+</html>
+```
+
+假设 page 为以上页面的 MixPage 对象，我们可以用这些方法获取其中的元素：
+
+```python
+div1 = page.ele('#one') # 获取 id 为 one 的元素
+
+p_eles = div1.eles('tag:p') # 获取 div1 元素内所有 p 元素组成的列表
+
+row1 = page.ele('@name=row1') # 获取 name 属性为 row1 的元素
+
+p_ele = page.ele('tag:p@@text():第二@@name=row2') # 获取 name 属性为 row2 且包含“第二”文本的 p 元素
+
+div2 = page.ele('第二个div') # 获取包含“第二个div”文本的元素
+
+div2 = page.ele('x://div[@id="tow"]') # 用 xpath c
+```
+
+## 实际示例：
```python
from DrissionPage import MixPage
@@ -63,7 +107,9 @@ s 模式下这个方法和 ele() 是一样的。
```python
ele2 = ele1.s_ele() # 获取 ele1 元素的 SessionElement 版本
+
ele2 = ele1.s_ele('search text') # 在 ele1 元素下查找元素，并以 SessionElemnet 返回
+
ele = page.s_ele('search text') # 在页面下查找元素，并以 SessionElemnet 返回
```
@@ -136,27 +182,7 @@ ele1.click() # 点击获取到的元素
我们使用一套简洁高效的语法去定位元素，大大简化了定位元素的代码量，增强了功能，也兼容 css selector、xpath、selenium 原生的 loc 元组（s 模式也能用）。d 模式和 s
模式定位元素的语法是完全一样的，便于模式切换时平滑过渡。
-看一个例子，用显性等待方式定位第一个文本包含 some text 的元素。可以看出本库的定位语法比 selenium 做了大幅度精简，而且功能更强大：
-```python
-# 使用 selenium：
-element = WebDriverWait(driver).until(ec.presence_of_element_located((By.XPATH, '//*[contains(text(), "some text")]')))
-
-# 使用 DrissionPage：
-element = page('some text')
-```
-
-我们稍后以这个 html 页面为例：
-
-```html
-<html>
- <body>
- <div id="">
-
- </div>
- </body>
-</html>
-```
## 关键字
@@ -175,8 +201,9 @@ element = page('some text')
表示 id 属性，只在语句最前面且单独使用时生效，可配合 = 或 :。
```python
-ele2 = ele1.ele('#ele_id') # 查找 id 属性为 ele_id 的元素
-ele2 = ele1.ele('#:ele_id') # 查找 id 属性包含 ele_id 文本的元素
+ele1 = page.ele('#ele_id') # 在页面中查找 id 属性为 ele_id 的元素
+
+ele2 = ele1.ele('#:ele_id') # 在 ele1 元素内查找 id 属性包含 ele_id 文本的元素
```
## .
@@ -185,6 +212,7 @@ ele2 = ele1.ele('#:ele_id') # 查找 id 属性包含 ele_id 文本的元素
```python
ele2 = ele1.ele('.ele_class') # 查找 class 属性为 ele_class 的元素
+
ele2 = ele1.ele('.:ele_class') # 查找 class 属性包含 ele_class 文本的元素
```
@@ -194,9 +222,13 @@ ele2 = ele1.ele('.:ele_class') # 查找 class 属性包含 ele_class 文本的
```python
ele2 = ele1.ele('@name=ele_name') # 查找 name 属性为 ele_name 的元素
+
ele2 = ele1.ele('@name:ele_name') # 查找 name 属性包含 ele_name 文本的元素
+
ele2 = ele1.ele('@name') # 查找有 name 属性的元素
+
ele2 = ele1.ele('@') # 查找没有任何属性的元素
+
ele2 = ele1.ele('@email=abc@def.com') # 查找 emaile 属性为 abc@def.com 的元素，有多个 @ 也不会重复处理
```
@@ -215,7 +247,9 @@ ele2 = ele1.ele('@@name=name@@class:cls') # 查找 name 属性为 name 且 clas
```python
ele2 = ele1.ele('text=some text') # 查找文本为 some text 的元素
+
ele2 = ele1.ele('text:some text') # 查找文本包含 some text 的元素
+
ele2 = ele1.ele('some text') # 与上一行一致
```
@@ -225,8 +259,11 @@ ele2 = ele1.ele('some text') # 与上一行一致
```python
ele2 = ele1.ele('@text()=some text') # 查找文本为 some text 的元素
+
ele2 = ele1.ele('@text():some text') # 查找文本包含 some text 的元素
+
ele2 = ele1.ele('@@text()=some text@@class=cls') # 查找文本为 some text 且 class 属性为 cls 的元素
+
ele2 = ele1.ele('@@@@text():some text') # 查找文本为 some text 且没有任何属性的元素（因第一个 @@ 后为空）
```
@@ -236,10 +273,15 @@ ele2 = ele1.ele('@@@@text():some text') # 查找文本为 some text 且没有
```python
ele2 = ele1.ele('tag:div') # 定位 div 元素
+
ele2 = ele1.ele('tag:div@class=cls') # 定位 class 属性为 cls 的 div 元素
+
ele2 = ele1.ele('tag:div@text()=text') # 定位文本为 text 的 div 元素
+
ele2 = ele1.ele('tag:div@@class=cls@@text()=text') # 定位 class 属性为 cls 且文本为 text 的 div 元素
+
ele2 = ele1.ele('tag:div@text():text') # 查找直接文本节点包含 text 字符串的 div 元素
+
ele2 = ele1.ele('tag:div@@text():text') # 查找内部文本节点包含 text 字符串的 div 元素
```
@@ -251,6 +293,7 @@ ele2 = ele1.ele('tag:div@@text():text') # 查找内部文本节点包含 text
```python
ele2 = ele1.ele('css:.div') # 查找 div 元素
+
ele2 = ele1.ele('css:>div') # 查找 div 子元素元素，这个写法是本库特有，原生不支持
```
@@ -261,7 +304,9 @@ ele2 = ele1.ele('css:>div') # 查找 div 子元素元素，这个写法是本
```python
ele2 = ele1.ele('xpath:.//div') # 查找 div 元素
+
ele2 = ele1.ele('xpath://div') # 和上面一行一样，查找元素的后代时，// 前面的 . 可以省略
+
txt = ele1.ele('xpath://div/@class') # 获取 div 元素的 class 属性，返回字符串
```
@@ -273,8 +318,9 @@ txt = ele1.ele('xpath://div/@class') # 获取 div 元素的 class 属性，返
```python
loc1 = By.ID, 'ele_id'
-loc2 = By.XPATH, '//div[@class="ele_class"]'
ele = page.ele(loc1) # 查找 id 为 ele_id 的元素
+
+loc2 = By.XPATH, '//div[@class="ele_class"]'
ele = page.ele(loc2) # 按 xpath 查找
```
@@ -285,6 +331,7 @@ d 模式下所有查找元素操作都自带等待，默认为 10 秒，也可
```python
page = MixPage(timeout=15) # 页面初始化时设置查找元素超时时间为 15 秒
page.timeout = 5 # 设置查找元素超时时间为 5 秒
+
ele1 = page.ele('some text') # 使用页面超时时间来查找元素（5 秒）
ele1 = page.ele('some text', timeout=1) # 为这次查找页面独立设置等待时间（1 秒）
ele2 = ele1.ele('some text') # 查找后代元素，使用页面超时时间（5 秒）
@@ -303,8 +350,11 @@ ele2 = ele1.ele('some text', timeout=1) # 查找后代元素，使用单独设
```python
eles = page('#table_id').eles('t:tr') # 定位到页面中 id 为 table_id 的元素，然后获取它的所有 tr 元素
+
ele2 = ele1('.cls1')('tx=text') # 定位到 class 为 cls 的元素，然后在它里面查找文本为 text 的元素
+
ele2 = ele1.sr('.cls') # 获取 ele1 的 shadow_root 元素，再在里面查找 class 属性为 cls 的元素
+
ele2 = ele1('x://div[@class="ele_class"]') # 按xpath 查找元素
```
@@ -326,4 +376,3 @@ ele2 = ele1('x://div[@class="ele_class"]') # 按xpath 查找元素
- ShadowRootElement 的 ele() 不支持 xpath 关键字。
- 定位语句内容与关键字重复时，可使用 xpath 或 css selector。
-