API

大约 16 分钟

API

IDEPY Next基础API功能仅保留Windows EdgeChrome支持，

同时在这基础上，进行了功能优化，其余特性功能与pywebview5.4一致。

为便于用户理解与功能调用，可以通过以下别名进行开发。

import idepy_next as webview

webview.create_window

webview.create_window(title, url=None, html=None, js_api=None, width=800, height=600,
                      x=None, y=None, screen=None, resizable=True, fullscreen=False,
                      min_size=(200, 100), hidden=False, frameless=False,
                      easy_drag=True, shadow=False, focus=True, minimized=False, maximized=False,
                      on_top=False, confirm_close=False, background_color='#FFFFFF',
                      transparent=False, text_select=False, zoomable=False,
                      draggable=False, server=http.BottleServer, server_args={},
                      localization=None,storage_path = None,private_mode = None,user_agent = None,
                      REMOTE_DEBUGGING_PORT=None,webview2_ext_args = None, document_loaded_script = None,
                      easy_resize = False
)

创建一个新的窗口并返回其实例。可用于创建多个窗口。窗口在 GUI 循环启动之前不会显示。如果在此期间调用该函数，窗口会立即显示。

title - 窗口标题
url - 加载的 URL 地址。如果没有协议前缀，则将其解析为相对于应用程序入口点的路径。或者可以传递一个 WSGI 服务器对象以启动本地 Web 服务器。
html - 要加载的 HTML 代码。如果同时指定了 URL 和 HTML，HTML 将优先。
js_api - 向当前 idepy 窗口的Javascript域暴露一个 Python 对象。可以通过调用 window.idepy.api.<methodname>(<parameters>) 函数从 Javascript 调用该对象的方法。暴露的函数返回一个承诺，一旦函数返回就会解决。只有基本的 Python 对象（如 int, str, dict, ...）可以返回到 Javascript。
width - 窗口宽度。默认为 800px
height - 窗口高度。默认为 600px
x - 窗口 x 坐标。默认居中
y - 窗口 y 坐标。默认居中
screen - 要显示窗口的屏幕。screen 是通过 webview.screens 返回的屏幕实例。
resizable - 是否可以调整大小。默认为 True
fullscreen - 以全屏模式启动。默认为 False
min_size - 指定最小窗口大小的 (width, height) 元组。默认为 200x100
hidden - 默认创建隐藏窗口。默认为 False
frameless - 创建无边框窗口。默认为 False。
easy_drag - 对于无边框窗口，启用易拖拽模式。可以拖动任何点来移动窗口。默认为 True。注意，对于正常窗口，easy_drag 没有作用。有关详细信息，请参阅拖拽区域。
shadow - 为窗口添加阴影。默认为 False。仅限 Windows。
focus - 如果为 False，创建不可聚焦的窗口。默认为 True。
minimized - 显示最小化窗口
maximized - 显示最大化窗口
on_top - 设置窗口始终位于其他窗口之上。默认为 False。
confirm_close - 是否显示窗口关闭确认对话框。默认为 False
background_color - 在 WebView 加载之前显示的窗口背景颜色。指定为十六进制颜色。默认为白色。
transparent - 创建透明窗口。不支持 Windows。默认为 False。注意，此设置不会隐藏或使窗口 chrome 透明。要隐藏窗口 chrome，请将 frameless 设为 True。
text_select - 启用文档文本选择。默认为 False。要在每个元素的基础上控制文本选择，请使用用户选择 CSS 属性。
zoomable - 启用文档缩放。默认为 False
draggable - 启用图像和链接对象的拖拽。默认为 False
vibrancy - 启用窗口振动。默认为 False。仅限 macOS。
server - 为此窗口自定义的 WSGI 服务器实例。默认为 BottleServer。
server_args - 传递到服务器实例化的参数字典
localization - 传递一个本地化字典，以便按窗口进行本地化。
storage_path - 单独设置该窗口的用户数据存储目录，不设置默认使用全局的配置，在start配置。
private_mode - 单独设置该窗口的隐私模式，不设置默认使用全局的配置，在start配置。
user_agent - 单独设置该窗口的用户代理头，不设置默认使用全局的配置，在start配置
REMOTE_DEBUGGING_PORT - 单独设置该窗口的远程调试端口，不设置默认使用全局的配置，在start配置
webview2_ext_args - 设置webview2实例创建的额外参数，可参考微软官方相关文档。
document_loaded_script - 每次文档元素加载完毕后，自动注入的脚本内容
easy_resize - 1.1.0版本后支持启用网页边缘模拟缩放模式，多用于创建frameless窗口，默认为 False。

webview.create_window_group

import idepy_next as webview

# 创建群组和窗口
window_group = webview.create_window_group("控制台")
window1 = webview.create_window("IDEPY","https://idepy.com",hidden=True)
window2 = webview.create_window("IDEPY","https://idepy.com",hidden=True)

# 窗口创建完毕后自动添加到群组
def add_window_to_group(window):
    window_group.add(window)
    window.hidden = False
# 注册事件
window1.events.before_load += add_window_to_group
window2.events.before_load += add_window_to_group
webview.start()

创建窗口群组，并返回一个WindowGroup对象，可通过调用该示例的add方法添加数组成员。

title - 窗口群组的标题
width -窗口群组的宽度
height - -窗口群组的高度
返回 WindowGroup 对象

webview.start

webview.start(func=None, args=None, localization={}, gui=None, debug=False,
              http_server=False, http_port=None, user_agent=None, private_mode=True,
              storage_path=None, menu=[], server=http.BottleServer, ssl=False,
              server_args={}, icon=None):

启动GUI消息循环以显示之前创建的窗口。此函数必须从主线程调用。

func - GUI循环启动时要调用的函数。
args - 函数参数。可以是单个值或值的元组。
localization - 包含本地化字符串的字典。默认字符串及其键在localization.py中定义
gui - 强制使用特定的GUI。允许的值取决于平台，分别是cef、qt或gtk。有关详细信息，请参阅Web Engine。
debug - 启用调试模式。有关详细信息，请参阅Debugging。
http_server - 启用内置HTTP服务器以处理绝对本地路径。对于相对路径，会自动启动HTTP服务器且无法禁用。对于每个窗口，都会spawn一个单独的HTTP服务器。此选项对非本地URL无效。
http_port - 指定HTTP服务器的端口号。默认端口是随机分配的。
user_agent - 更改用户代理字符串。
private_mode - 控制是否在会话之间存储Cookie和其他持久对象。默认情况下，隐私模式启用且会在会话之间清除数据。
storage_path - 可选的硬盘驱动器路径，用于存储Cookie和本地存储等持久对象。默认情况下，在*nix系统上使用~/.idepy，在Windows上使用 %APPDATA%\idepy。
menu - 传递一个Menu对象列表以创建应用程序菜单。有关使用详细信息，请参阅此示例。
server - 自定义WSGI服务器实例。默认为BottleServer。
ssl - 如果使用默认的BottleServer（以及目前的GTK后端），将在WebView和内部服务器之间使用SSL加密。要使用ssl，需要安装cryptography pip依赖项。默认情况下不会自动安装。
server_args - 传递到服务器实例化的参数字典
icon - 应用程序图标路径。仅适用于GTK / QT。对于其他平台，图标应通过打包工具指定。

webview.screens

webview.screens

返回一个包含所有可用显示器（作为Screen对象）的列表，其中第一个元素是主显示器。

webview.settings

webview.settings = {
  'ALLOW_DOWNLOADS': False,
  'ALLOW_FILE_URLS': True,
  'OPEN_EXTERNAL_LINKS_IN_BROWSER': True,
  'OPEN_DEVTOOLS_IN_DEBUG': True,
  'REMOTE_DEBUGGING_PORT': None
}

一些额外选项，用于覆盖_idepy_的默认行为以满足 popular功能请求。

ALLOW_DOWNLOADS 允许文件下载。默认情况下禁用。
ALLOW_FILE_URLS 启用file://链接。默认情况下禁用。
OPEN_EXTERNAL_LINKS_IN_BROWSER. 在新的浏览器窗口中打开target=_blank链接。默认情况下启用。
OPEN_DEVTOOLS_IN_DEBUG 在调试模式下自动打开开发工具。默认情况下启用。
OPEN_EXTERNAL_LINKS_IN_WINDOW_GROUP 使用窗口群组打开target=_blank链接，默认情况下禁用。
OPEN_EXTERNAL_LINKS_IN_WINDOW_ARGS（窗口群组相关参数，参考create_window_group）
REMOTE_DEBUGGING_PORT 启用远程调试（当使用edgechromium时）。默认情况下禁用。

webview.token

webview.token

一个唯一标识会话的CSRF令牌属性。相同的令牌也在window.idepy.token中暴露。有关使用详细信息，请参阅安全。

webview.dom

webview.dom.DOMEventHandler

DOMEventHandler(callback, prevent_default=False, stop_propagation=False, stop_immediate_propagation=False, debounce=0)

一个容器，用于控制事件传播或默认行为的事件处理程序。如果debounce大于零，则Python事件处理程序会根据指定的毫秒数进行防抖动处理。这对于生成大量事件（如dragover和mouseover）的情况非常有用，以避免性能问题。

示例

element.events.click += DOMEventHandler(on_click, prevent_default=True, stop_propagation=True, stop_immediate_propagation=True)
element

webview 元素操作指南

基本概念

在 webview 框架中，Element 表示网页中的一个 DOM 元素。通过该类的方法可以实现对元素的各种操作，包括属性设置、事件处理、样式管理等。

核心方法

1. 属性操作 (`element.attributes`)

attributes 是一个类似字典的对象，用于获取或修改元素的属性值。可以通过字典的方式对其进行赋值和删除操作。

示例代码：

# 设置元素的 id 属性
element.attributes['id'] = 'container-id'
# 添加自定义属性
element.attributes['data-flag'] = '1337'
# 删除元素的 id 属性
element.attributes['id'] = None
# 删除自定义属性
del element.attributes['data-flag']

2. 类名操作 (`element.classes`)

classes 是一个类似列表的对象，用于获取或设置元素的类名。可以通过添加、删除、切换类名来控制元素的样式。

示例代码：

# 设置元素的所有类名
element.classes = ['container', 'red', 'dotted']
# 移除指定的类名
element.classes.remove('red')
# 添加新的类名
element.classes.add('blue')
# 切换类名的状态（如：添加或移除）
element.classes.toggle('dotted')

3. 插入元素 (`element.append`)

将 HTML 内容插入到当前元素中，作为最后一个子元素。通过 mode 参数可以控制新元素的插入位置。

示例代码：

element.append(html, mode=webview.dom.ManipulationMode.LastChild)

4. 移动元素 (`element.move`)

将当前元素移动到目标位置（目标可以是另一个元素或选择器字符串），通过 mode 参数控制新位置。

示例代码：

element.move(target, mode=webview.dom.ManipulationMode.LastChild)

5. 创建元素副本 (`element.copy`)

创建一个当前元素的副本，插入到指定目标位置。可以通过 id 参数自定义副本的新 ID。

示例代码：

element.copy(target=None, mode=webview.dom.ManipulationMode.LastChild, id=None)

6. 空置元素 (`element.empty`)

清空当前元素的所有子内容。

示例代码：

element.empty()

7. 绑定事件 (`element.on`)

绑定 DOM 事件到当前元素上，支持自定义回调函数处理事件。例如，绑定点击事件或键盘按下事件。

示例代码：

element.on('click', callback_func)

8. 解除事件监听 (`element.off`)

解除之前绑定的某个事件监听。

示例代码：

element.off('click', callback_func)

9. 获取焦点 (`element.focus`)

将焦点设置到当前元素上，使其成为活动状态。

示例代码：

element.focus()

10. 失去焦点 (`element.blur`)

移除当前元素的焦点，使其不再处于活动状态。

示例代码：

element.blur()

11. 隐藏元素 (`element.hide`)

通过设置 display: none 将元素隐藏起来。

示例代码：

element.hide()

总结

以上是 webview.Element 类的核心操作方法，涵盖了从属性修改到事件绑定的多种功能。通过这些方法可以实现对 DOM 元素的各种灵活操作，满足常见的网页开发需求。

DOM 事件

element.remove

element.remove()

从 DOM 中移除元素。Element 对象不会被销毁，而是标记为已移除。尝试访问该元素的任何属性或调用其方法将导致警告。

DOM 操作

element.show

element.show()

显示隐藏的元素。如果元素是通过 element.hide() 隐藏的，则会恢复之前设置的 display 值。否则，将设置为 display: block。

DOM 操作

element.style

获取或修改元素的样式。style 是一个类似于字典的对象 PropsDict，实现了大部分字典功能。要添加样式声明，可以直接将值赋给字典中的键。类似地，要重置某个属性的声明，可以将其值设置为 None。

示例

element.style['width'] = '100px' # 设置元素宽度为 100px
element.style['display'] = 'flex' # 设置元素的 display 属性为 flex
element.style['width'] = None # 将宽度重置为 auto
del element.attributes['display'] # 将 display 属性重置为 block

element.visible

element.visible

获取该元素是否可见。

用于创建应用程序菜单。有关详细使用信息，请参阅此示例。

Menu(title, items=[]). 通过实例化来创建一个可以作为顶级菜单或嵌套菜单的菜单。title 是菜单标题，items 是包含操作、分隔符或其他菜单的列表。

MenuAction(title, function) 通过实例化来创建一个菜单项。title 是项目的名称，函数是当菜单操作被单击时应调用的回调。

MenuSeparator() 通过实例化来创建一个菜单分隔符。

WindowGroup

add

添加窗口到窗口群组，并显示窗口群组。

window - 使用create_window返回的对象。
allow_close - tab标签上是否显示关闭按钮。

webview.Window

表示一个承载 webview 的窗口。window 对象由 create_window 函数返回。

window.resize

window.resize()

重设窗口尺寸大小，并自动根据DPI进行缩放

width - 窗口新的尺寸。
height - 窗口新的高度。
direction - 变化的方向
x - 设置该值时，窗口左上角将移动到对应坐标，默认为None
y - 设置该值时，窗口左上角将移动到对应坐标，默认为None

window.create_confirmation_dialog

window.create_confirmation_dialog(title, message)

创建一个确认对话框（确定 / 取消）。

window.create_file_dialog

window.create_file_dialog(dialog_type=OPEN_DIALOG, directory='', allow_multiple=False, save_filename='', file_types=())

创建打开文件（webview.OPEN_DIALOG）、打开文件夹（webview.FOLDER_DIALOG）或保存文件（webview.SAVE_DIALOG）对话框。

返回一个元组，包含所选文件。如果取消操作则返回 None。

allow_multiple=True 启用多选。
directory 初始目录。
save_filename 用于保存文件对话框的默认文件名。
file_types 在打开文件对话框中支持的文件类型字符串元组。文件类型字符串必须遵循以下格式 "描述 (*.ext1;*.ext2...)"。

如果未指定参数，则默认使用 "All files (*.*)" 这个文件过滤器。可以通过国际化词典修改“所有文件”这个字符串。

window.evaluate_js

window.evaluate_js(script, callback=None)

执行JavaScript代码。返回最后一个评估表达式的结果。如果提供回调函数，则处理承诺并调用回调函数，结果作为参数传递。将JavaScript类型转换为Python类型，例如将JS对象转为字典、数组转为列表、undefined转为None。DOM节点使用自定义序列化。省略函数和循环引用，将其转换为 [Circular Reference] 字面量字符串。若执行代码时引发错误，则抛出 webview.error.JavascriptException。推荐使用 r-strings 加载JavaScript。注意，evaluate_js 使用 eval，如果设置有 unsafe-eval CSP头，则会失败。可以改用 window.run_js(code)，该方法直接执行JavaScript代码而不返回结果。

window.expose

window.expose(func)

将Python函数或多个函数暴露到JS API中。函数将以 window.idepy.api.func_name 的形式出现。

示例

window.get_cookies

window.get

window.set_title

window.set_title(title)

已弃用。请改用 window.title。此函数用于更改窗口的标题。

示例

window.show

window.show()

如果窗口当前被隐藏，此函数将显示窗口。否则无效果。

示例

window.toggle_fullscreen

window.toggle_fullscreen()

在活动监视器上切换全屏模式。

示例

window.dom.body

window.body

获取页面文档的主体，返回一个 Element 对象

window.dom.create_element

window.create_element(html, parent=None, mode=webview.dom.操作模式.LastChild)

插入 HTML 内容并返回根对象的 Element。parent 可以是另一个 Element 或 DOM 选择器字符串。如果省略 parent，则创建的 DOM 附加到文档正文。要控制新元素的位置，请使用 mode 参数。有关可能值，请参见操作模式。

window.dom.document

window.document

获取加载页面的 window.document，返回一个 Element 对象

window.dom.get_element

window.get_element(selector: str)

按选择器获取第一个匹配的 Element。如果没有找到则返回 None。

window.dom.get_elements

window.get_elements(selector: str)

按选择器获取一组 Element 对象。

window.dom.window

获取 DOM 文档的窗口 window，返回一个 Element 对象

窗口事件

窗口对象暴露出各种生命周期和窗口管理事件。要订阅事件，请使用 += 符号语法，例如 window.events.loaded += func。重复订阅将被忽略，并且仅当有多个订阅者时函数才会被执行一次。要取消订阅，请使用 -= 语法，例如 window.events.loaded -= func。在事件处理程序中访问窗口对象，请将 window 参数作为处理程序的第一个位置参数提供。大多数窗口事件是异步的，事件处理程序将在单独的线程中执行。before_show 和 before_load 事件是同步的，并且会阻止主线程直到处理完成。

<div class='idepy-drag-region'>现在可以通过拖拽这个 DIV 来移动窗口。</div>

可以通过重新分配 webview.DRAG_REGION_SELECTOR 常量来覆盖这个神奇的类名。