pywebview中文文档

# API

# 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)

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

  • title - 窗口标题
  • url - 载入的URL. 如果URL没有协议前缀，则将其解析为相对于应用程序入口点的路径。或者传递WSGI服务器对象来启动本地web服务器。
  • html - 要加载的HTML代码。如果同时指定了URL和HTML，则HTML优先。
  • js_api - 将python对象暴露到当前pywebview窗口的Javascript作用域中。 js_api 对象可以在javascript通过 window.pywebview.api.<methodname>(<parameters>) 函数调用. 调用暴露的函数返回一个promise，该promise在函数返回时响应。 仅支持返回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。请注意，此设置不会隐藏或使窗口透明。要隐藏窗口边框，请将frameless参数设置为True。
  • text_select - 启用文档文本选择。默认值为False。为了基于每个元素控制文本选择， 使用 user-select (opens new window) CSS 属性.
  • zoomable - 启用文档缩放。默认值为False
  • draggable - 启用图像和链接对象拖动。默认值为False server=http.BottleServer, server_args
  • vibrancy - 启用窗口活力。默认值为False。仅限macOS。
  • server - 此窗口的自定义WSGI服务器实例。默认为BottleServer。
  • server_args - 传递给服务器实例化的参数字典。
  • localization - 为每个窗口的本地化传递一个本地化词典。

# 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 并取决于平台. 参考 Renderer 了解详情.
  • debug - 开启调试模式. 查看 调试 了解详情.
  • http_server - 为绝对本地路径启用内置HTTP服务器。 对于相对路径，HTTP服务器会自动启动，无法禁用。对于每个窗口，都会生成一个单独的HTTP服务器。对于非本地URL，此选项将被忽略。
  • http_port - 指定HTTP服务器的端口号。默认情况下，端口是随机的。
  • user_agent - 更改用户代理字符串。
  • private_mode - 控制会话之间是否存储Cookie和其他持久对象。默认情况下，隐私模式处于打开状态，会话之间不存储任何内容。
  • storage_path - 硬盘上的一个可选位置，用于存储Cookie和本地存储等持久对象。 默认在linux系统使用~/.pywebview路径，而Windows上使用%APPDATA%\pywebview。
  • menu - 传递菜单对象列表以创建应用程序菜单。有关用法的详细信息，请参阅此实例。
  • server - 自定义WSGI服务器实例。默认为BottleServer。
  • ssl - 如果使用默认的BottleServer（现在是GTK后端），将在webview和内部服务器之间使用SSL加密。仅限可可/QT/GTK。
  • 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
}

添加额外的选项覆盖默认配置 pywebview 以满足你的需求。

  • ALLOW_DOWNLOADS 允许文件下载。默认情况下禁用。
  • ALLOW_FILE_URLS 启用 file:// urls. 默认情况下禁用.
  • OPEN_EXTERNAL_LINKS_IN_BROWSER. 打开包含 target=_blank 表示的链接在额外浏览器，默认启用。
  • OPEN_DEVTOOLS_IN_DEBUG 调试模式自动打开开发者工具，默认启用。
  • REMOTE_DEBUGGING_PORT 使用远程调试器，当使用 edgechromium时。 默认禁用

# 示例

# webview.token

webview.token

会话独有的CSRF的token属性.该token暴露到 window.pywebview.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.events.mouseover += DOMEventHandler(on_click, debounce=500)

# webview.dom.ManipulationMode

设置操纵DOM元素位置的枚举。可能的值有：

  • LastChild - 元素作为目标的最后一个子元素插入
  • FirstChild - 元素作为目标的第一个子元素插入
  • Before - 元素插入到目标之前
  • After - 元素插入到目标之后
  • Replace - 插入元素以替换目标

通过 element.append, element.copy, element.move 和 window.dom.create_element 函数使用。

# webview.Element

# element.attributes

获取或修改元素的属性. attributes 是一个 PropsDict 实现大部分dict函数的类dict对象。 要添加属性，只需为中的键赋值即可 attributes. 同样，要删除属性，可以将其值设置为None。

# 例子

element.attributes['id'] = 'container-id' # 设置元素的ID
element.attributes['data-flag'] = '1337'
element.attributes['id'] = None # 移除元素的ID
del element.attributes['data-flag'] # 移除元素的 data-flag 属性

# element.classes

element.classes

获取或设置元素的class属性。 classes 是一个 ClassList 类似于列表，包含列表的函数子集 append, remove 和 clear。 此外它还有一个 toggle 函数用于切换类的功能。

# 例子

element.classes = ['container', 'red', 'dotted'] # 覆盖元素的class属性
element.classes.remove('red') # 移除red这个class
element.classes.add('blue') # 增加blue这个class
element.classes.toggle('dotted')

# element.append

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

将HTML内容作为最后一个子元素插入到元素中。要控制新元素的位置，请使用 mode 参数。相关的值请参考：Manipulation mode。

# element.blur

element.blur()

让一个元素失去焦点

# element.children

element.children

获取一个元素的子元素。返回一个Element对象列表。

# element.copy

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

创建一个复制的元素。 target可以是另一个Element或DOM选择器字符串。如果省略target，则会在当前元素的父元素中创建一个副本。要控制新元素的位置，请使用mode参数。有关可能的值，请参阅 Manipulation mode 。id参数从副本中删除。您可以通过指定id参数来设置副本的id。

# element.empty

element.empty()

清空这个元素的子元素。

# element.events

element.events

元素的所有DOM事件的容器对象，即 events.click， event.keydown。此容器是动态填充的，其内容取决于节点的事件。要订阅DOM事件，请使用 += 语法, 例如 element.events.click += callback。 删除事件侦听器使用 -=， 比如 element.events.click -= callback。 回调可以是函数或实例 DOMEventHandler 如果你需要控制事件的传播。

# element.focus

element.focus()

聚焦元素。

# element.focused

element.focused

获取当前元素的聚焦状态。

# element.hide

element.hide()

隐藏元素，通过设置css的 display: none属性。

# element.id

element.id

获取或设置一个元素的id。返回None则未设置id。

# element.move

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

移动元素到目标元素里面，target可以是其他Element对象，或者是DOM元素选择器文本。 为了控制元素插入位置，可以使用 mode 参数。参考 Manipulation mode 查阅可选值。

# 例子

DOM Manipulation

# element.next

element.next

获取元素的 获取元素的下一个兄弟。如果没有兄弟元素在场，则返回None。

# element.off

element.off(event, callback)

移除一个事件监听器，等同于element.event.event_name -= callback.

# 例子

# 这两个完全相同
element.off('click', callback_func)
element.events.click -= callback_func

DOM Events

# element.on

element.on(event, callback)

添加一个事件监听器到dom对象。如果需要控制事件的传播，callback 参数可以是函数或者是一个 DOMEventHandler实例。等同于 element.event.event_name += callback.

# 例子

# 这两个完全相同
element.on('click', callback_func)
element.events.click += callback_func

DOM Events

# element.parent

element.parent

获取元素的父元素Element对象，如果到达根元素，则返回None。

# element.previous

element.previous

获取元素的前一个元素。如果没有则返回None。

# element.remove

element.remove()

从DOM移除元素. Element 对象不会被销毁，但会被标记为已移除。尝试访问元素的任何属性或调用元素的任何函数都会导致警告。

DOM Manipulation

# element.show

element.show()

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

DOM Manipulation

# element.style

获取或修改一个元素的style style，返回一个属性字典对象，实现了dict大部分函数方法。要添加样式声明，您只需为attributes赋值即可。 同样，要重置声明，可以将其值设置为None。

# 例子

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

# element.tabindex

element.tabindex

获取或设置元素的 tabindex 属性。

# element.tag

element.tag

获取元素的标签名称。

# element.text

element.text

获取或设置元素的文本内容。

# element.toggle

element.toggle()

切换元素的可见性。

# element.value

element.value

获取或设置元素的值。仅适用于具有值的输入元素。

# element.visible

element.visible

获取元素是否可见。

# webview.Menu

用于创建应用程序菜单。 查看 菜单例子 了解详情。

Menu(title, items=[]). 实例化以创建可以是顶级菜单或嵌套菜单的菜单。title是菜单标题 items是具体的MenuAction、MenuSeparator或者是Menu。

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

MenuSeparator(title, function) 实例化以创建菜单分隔符。

# webview.Screen

表示在系统上找到的显示器。

# screen.height

screen.height

获取显示器高度。

# screen.width

screen.width

获取显示器宽度。

# webview.Window

表示承载WEB试图的窗口，通过create_window 函数返回 window 对象。

# window.title

window.title

获取或设置窗口的标题。

# window.on_top

window.on_top

获取或设置窗口是否始终位于顶部。

# window.x

window.x

获取窗口左上角corner的X坐标。

# window.y

window.y

获取窗口左上角坐标的Y坐标。

# window.width

window.width

获取窗口宽度。

# window.height

window.height

获取窗口高度。

# window.clear_cookies

window.clear_cookies()

清除所有cookie，包括 HttpOnly。

# 例子

# 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 一个元组，用于筛选文件类型，必须使用该格式："Description (*.ext1;*.ext2...)".

未指定参数时，则默认使用 "All files (*.*)" 。你可以在localization字典中更改所有文件的字符串。

# 例子

# window.destroy

window.destroy()

销毁窗口。

例子

# window.evaluate_js

window.evaluate_js(script, callback=None)

执行Javascript代码。返回最后一个计算的表达式。如果提供了回调函数，则会解析promises，并调用回调函数，并将结果作为参数。Javascript类型转换为Python类型，例如JS对象转换为字典，数组转换为列表，undefined转换为None。 函数被省略，循环引用被转换为 [Circular Reference] 字符串迭代器。 如果执行的代码引发错误，则抛出异常webview.error.JavascriptException。 r-strings是加载Javascript的推荐方式。

# window.expose

向JS API公开一个或多个Python函数。函数公开为 window.pywebview.api.func_name

例子

# window.get_cookies

window.get_cookies()

返回为当前网站设置的所有Cookie的列表 ( SimpleCookie (opens new window)).

# window.get_current_url

window.get_current_url()

返回当前URL。如果没有加载URL，则返回None。

例子

# window.get_elements

window.get_elements(selector)

已废弃. 使用 window.dom.get_elements 替代.

例子

# window.hide

window.hide()

隐藏该窗口。

例子

# window.load_css

window.load_css(css)

将CSS作为字符串加载。

例子

# window.load_html

window.load_html(content, base_uri=base_uri())

加载HTML代码。用于解析相对URL的基本URL设置为启动程序的目录。请注意，当HTML以这种方式加载时，您不能使用hashbang锚点。

例子

# window.load_url

window.load_url(url)

加载新URL。

例子

# window.maximize

window.maximize()

最大化窗口。

例子

# window.minimize

window.minimize()

最小化窗口。

例子

# window.move

window.move(x, y)

将窗口移动到新位置。

例子

# window.native

window.native.Handle # get application window handle on Windows

获取本机窗口对象。这对于将自定义样式应用于窗口非常有用。对象类型取决于平台

System.Windows.Form - Windows AppKit.NSWindow - macOS Gtk.ApplicationWindow - GTK QMainWindow - QT kivy.uix.widget.Widget - Android

native属性在before_show事件触发后可用。

您还可以通过window.national.WebView访问每个平台的WebView对象。WebView的类型如下。

Microsoft.Web.WebView2.WinForms.WebView2 - Windows / EdgeChromium System.Windows.Forms.WebBrowser - Windows / MSHTML WebKit.WKWebView - macOS gi.repository.WebKit2.WebView - GTK QtWebEngineWidgets.QWebEngineView / QtWebKitWidgets.QWebView- QT android.webkit.WebView - Android

# window.resize

window.resize(width, height, fix_point=FixPoint.NORTH | FixPoint.WEST)

调整窗口大小。可选参数fix_point指定窗口相对于哪个点调整大小。改参数接受的值有 webview.window.FixPoint enum (NORTH, SOUTH, EAST, WEST)

例子

# window.restore

window.restore()

恢复最小化窗口。

例子

# window.set_title

window.set_title(title)

已废弃. 使用 window.title 代替。 修改窗口的标题。

例子

# window.show

window.show()

显示隐藏的窗口，已显示的窗口没有效果。

例子

# window.toggle_fullscreen

window.toggle_fullscreen()

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

例子

# window.dom.body

window.body

获取文档的body元素，返回为 Element 对象

# window.dom.create_element

window.create_element(html, parent=None, mode=webview.dom.ManipulationMode.LastChild)

插入HTML内容并返回根对象的Element。 parent 参数可以是其他Element对象或者DOM元素原则强文本。若省略父级，则创建的DOM将附加到文档的正文。 为了控制元素的位置，可以使用 mode 参数， 具体的值参考 Manipulation 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对象公开了许多生命周期和窗口管理事件。要注册事件，请使用+=语法，例如window.events.loaded += func。重复的注册将被忽略，对于重复的注册，函数只会被调用一次。取消注册的事件，使用-=语法，比如window.events.loaded -= func. 为了从事件处理程序访问窗口对象， 你可以提供 window 位置参数在事件当中。

# window.events.before_show

在pywebview窗口显示之前触发的事件。这是最早暴露window.native属性的事件。

# window.events.closed

在pywebview窗口关闭之前触发的事件。

例子

# window.events.closing

pywebview窗口即将关闭时触发的事件。如果设置了confirm_close参数，则会在显示关闭确认之前触发此事件。如果事件处理程序返回False，则关闭操作将被取消。

例子

# window.events.loaded

DOM就绪时触发的事件。

例子

# window.events.minimized

窗口最小化时触发的事件。

例子

# window.events.restore

窗口恢复时触发的事件。

例子

# window.events.maximized

窗口最大化时触发的事件（macOS上为全屏）

# window.events.resized

调整pywebview窗口大小时触发的事件。事件处理程序可以没有，或接受（width、height）参数。

例子

# window.events.shown

显示pywebview窗口时触发的事件。

例子

# DOM 事件

pywebview 导出了一个DOM事件window.pywebviewready ，当 window.pywebview被创建时触发。

例子

# 拖拽区域

使用无边框窗口时，窗口可以通过点击被添加 pywebview-drag-region class的元素拖拽或移动。

<div class='pywebview-drag-region'>现在窗口可以通过这个元素被拖动</div>

这个魔术方法类名可以通过覆盖 webview.DRAG_REGION_SELECTOR 常量进行改写。

例子

← 应用程序架构 →