DrissionPage/docs/WebPage使用方法/3.4获取元素信息.md

获取到须要的页面元素后，可以使用元素对象获取元素的信息。

`WebPage`常用的元素对象有四种：

- `ChromiumElement`：浏览器一般元素

- `ChromiumShadowRootElement`：shadow-root 元素

- `ChromiumFrame`：专门用于操作`<iframe>`元素的对象

- `SessionElement`：s 模式的元素，或前 3 者转换而成的静态元素

前三者是 d 模式下通过浏览器页面元素生成，后者是 s 模式由静态文本生成。

`ChromiumElement`对象拥有`SessionElement`对象所有属性。

`ChromiumFrame`作为既是元素又是页面的存在，后面章节单独介绍。

# ✔️ 简单示例

以下示例可直接运行查看结果：

```python
from DrissionPage import WebPage

page = WebPage('s')
page.get('https://gitee.com/explore')

# 获取推荐目录下所有 a 元素
li_eles = page('tag:ul@@text():全部推荐项目').eles('t:a')

for i in li_eles:  # 遍历列表
    print(i.tag, i.text, i.attr('href'))  # 获取并打印标签名、文本、href 属性

"""输出：
a 全部推荐项目 https://gitee.com/explore/all
a 前沿技术 https://gitee.com/explore/new-tech
a 智能硬件 https://gitee.com/explore/hardware
a IOT/物联网/边缘计算 https://gitee.com/explore/iot
a 车载应用 https://gitee.com/explore/vehicle
以下省略……
"""
```

# ✔️ `SessionElement`属性

假设`ele`为以下`div`元素的对象：

```html
<div id="div1" class="divs">Hello World!
    <p>行元素</p>
    <!--这是注释-->
</div>
```

## 📍 `html`

此属性返回元素的`outerHTML`文本。

```python
html = ele.html
"""返回：
<div id="div1" class="divs">Hello World!
    <p>行元素</p>
    <!--这是注释-->
</div>
"""
```

## 📍 `inner_html`

此属性返回元素的`innerHTML`文本。

```python
inner_html = ele.inner_html
"""返回：
Hello World!
    <p>行元素</p>
    <!--这是注释-->
"""
```

## 📍 `tag`

此属性返回元素的标签名。

```python
tag = ele.tag  
# 返回：div
```

## 📍 `text`

此属性返回元素内所有文本组合成的字符串。  
该字符串已格式化，即已转码，已去除多余换行符，符合人读取习惯，便于直接使用。无须重复写处理代码。

```python
text = ele.text
"""返回：
Hello World!
行元素
"""
```

## 📍 `raw_text`

此属性返回元素内原始文本。

```python
text = ele.raw_text
"""返回（注意保留了元素间的空格和换行）：
Hello World!
    行元素


"""
```

## 📍 `texts()`

此方法返回元素内所有**直接**子节点的文本，包括元素和文本节点。 它有一个参数`text_node_only`，为`True`时则只获取只返回不被包裹的文本节点。这个方法适用于获取文本节点和元素节点混排的情况。

参数：

- `text_node_only`：是否只返回文本节点

返回：文本列表

```python
texts = ele.texts()
print(e.texts())  
# 输出：['Hello World!', '行元素']

print(e.texts(text_node_only=True))  
# 输出：['Hello World!']
```

## 📍 `comments`

此属性以列表形式返回元素内的注释。

```python
comments = ele.comments  
# 返回：[<!--这是注释-->]
```

## 📍 `attrs`

此属性以字典形式返回元素所有属性及值。

```python
attrs = ele.attrs  
# 返回：{'id': 'div1', 'class': 'divs'}
```

## 📍 `attr()`

此方法返回元素某个`attribute`属性值。它接收一个字符串参数`attr`，返回该属性值文本，无该属性时返回`None`。  
此属性返回的`src`、`href`属性为已补充完整的路径。`text`属性为已格式化文本。

参数：

- `attr`：属性名称

返回：属性值文本

```python
ele_id = ele.attr('id')  
# 返回：div1
```

## 📍 `link`

此方法返回元素的 href 属性或 src 属性，没有这两个属性则返回`None`。

```html
<a href='http://www.baidu.com'>百度</a>
```

假设`a_ele`为以上元素的对象：

```python
link = a_ele.link  
# 返回：http://www.baidu.com
```

## 📍 `page`

此属性返回元素所在的页面对象。由 html 文本直接生成的`SessionElement`的`page`属性为`None`。

```python
page = ele.page
```

## 📍 `xpath`

此属性返回当前元素在页面中 xpath 的绝对路径。

```python
xpath = ele.xpath  
#  返回：/html/body/div
```

## 📍 `css_path`

此属性返回当前元素在页面中 css selector 的绝对路径。

```python
css = ele.css_path  
# 返回：:nth-child(1)>:nth-child(1)>:nth-child(1)
```

# ✔️ `ChromiumElement`属性

`ChromiumElement`对象拥有`SessionElement`对象上述所有属性，并因运行在浏览器中拥有更丰富的属性。

## 📍 `size`

此属性以元组形式返回元素的大小。

```python
size = ele.size
# 返回：(50, 50)
```

## 📍 `location`

此属性以元组形式返回元素**左上角**在**整个页面**中的坐标。

```python
loc = ele.location
# 返回：(50, 50)
```

## 📍 `client_location`

此属性以元组形式返回元素**左上角**在**当前视口**中的坐标。

```python
loc = ele.client_location
# 返回：(50, 50)
```

## 📍 `midpoint`

此属性以元组形式返回元素**中点**在**整个页面**中的坐标。

```python
loc = ele.midpoint
# 返回：(55, 55)
```

## 📍 `client_midpoint`

此属性以元组形式返回元素**中点**在**视口**中的坐标。

```python
loc = ele.client_midpoint
# 返回：(55, 55)
```

## 📍 `pseudo_before`

此属性以文本形式返回当前元素的`::before`伪元素内容。

```python
before_txt = ele.pseudo_before
```

## 📍 `pseudo_after`

此属性以文本形式返回当前元素的`::after`伪元素内容。

```python
after_txt = ele.pseudo_after
```

## 📍 `style()`

该方法返回元素 css 样式属性值，可获取伪元素的属性。它有两个参数，`style`参数输入样式属性名称，`pseudo_ele`参数输入伪元素名称，省略则获取普通元素的 css 样式属性。

参数：

- `style`：样式名称
- `pseudo_ele`：伪元素名称（如有）

返回：样式属性值

```python
# 获取 css 属性的 color 值
prop = ele.style('color')

# 获取 after 伪元素的内容
prop = ele.style('content', 'after')
```

## 📍 `prop()`

此方法返回`property`属性值。它接收一个字符串参数，返回该参数的属性值。

参数：

- `prop`：属性名称

返回：属性值

## 📍`is_in_viewport`

此属性以布尔值方式返回元素是否在视口中，以元素可以接受点击的点为判断。

## 📍`is_alive`

此属性以布尔值形式返回当前元素是否仍可用。用于判断 d 模式下是否因页面刷新而导致元素失效。

## 📍 `is_selected`

此属性以布尔值返回元素是否选中。

## 📍 `is_enabled`

此属性以布尔值返回元素是否可用。

## 📍 `is_displayed`

此属性以布尔值返回元素是否可见。

# ✔️ 保存和截图

保存功能是本库一个特色功能，可以直接读取浏览器缓存，无须依赖 gui 或重新下载就可以保存页面资源。

作为对比，selenium 无法自身实现图片另存，往往须要通过使用 gui 进行辅助，不仅效率和可靠性低，还占用键鼠资源。

## 📍 `get_src()`

此方法用于返回元素`src`属性所使用的资源。base64 的会转为`bytes`返回，其它的以`str`返回。无资源的返回`None`。

例如，可获取页面上图片字节数据，用于识别内容，或保存到文件。`<script>`标签也可获取 js 文本。

!> 无法获取 Blob 内容。

**参数：** 无

**返回：** 资源内容字符串

```python
img = page('tag:img')
src = img.get_src()
```

## 📍 `save()`

此方法用于保存`get_src()`方法获取到的资源到文件。

**参数：**

- `path`：文件保存路径，为`None`时保存到当前文件夹

- `rename`：文件名称，须包含后缀，为`None`时从资源url获取

**返回：**`None`

```python
img = page('tag:img')
img.save('D:\\img.png')
```

## 📍 `get_screenshot()`

此方法用于对元素进行截图。若截图时元素在视口外，须 90 以上版本内核支持。

**参数：**

- `path`：图片完整路径，后缀可选`'jpg'`、`'jpeg'`、`'png'`、`'webp'`

- `as_bytes`：是否已字节形式返回图片，可选`'jpg'`、`'jpeg'`、`'png'`、`'webp'`。为`True`时以`'png'`输出。生效时`path`参数无效。

**返回：** 图片完整路径或字节文本

```python
img = page('tag:img')
img.get_screenshot()
bytes_str = img.get_screenshot(as_bytes='png')  # 返回截图二进制文本
```

# ✔️ `ChromiumShadowRootElement`属性

本库把 shadow dom 的`root`看作一个元素处理，可以获取属性，也可以执行其下级的查找，使用逻辑与`ChromiumElement`一致，但属性较之少，有如下这些：

## 📍 `tag`

此属性返回元素标签名，即`'shadow-root'`。

## 📍 `html`

此属性返回`shadow_root`的 html 文本，由`<shadow_root></shadow_root>` 标签包裹。

## 📍 `inner_html`

此属性返回`shadow_root`内部的 html 文本。

## 📍 `page`

此属性返回元素所在页面对象。

## 📍 `parent_ele`

此属性返回所依附的普通元素对象。

## 📍 `is_enabled`

与`ChromiumElement`一致。

## 📍 `is_alive`

与`ChromiumElement`一致。