webbrowser — 方便的网页浏览器控制器

源代码: Lib/webbrowser.py

webbrowser 模块提供了一个高级接口，允许向用户显示基于网页的文档。在大多数情况下，只需调用此模块中的 open() 函数即可。

在 Unix 系统下，X11 会优先使用图形浏览器，但如果图形浏览器不可用或没有可用的 X11 显示，则会使用文本模式浏览器。如果使用文本模式浏览器，调用进程将阻塞，直到用户退出浏览器。

如果环境变量 BROWSER 存在，它将被解释为以 os.pathsep 分隔的浏览器列表，这些浏览器将在平台默认浏览器之前尝试。当列表部分的某个值包含字符串 %s 时，它将被解释为文字浏览器命令行，参数 URL 将替换 %s；如果该值是一个单独的单词，并且指的是一个已注册的浏览器，则该浏览器将被添加到搜索列表的开头；如果该部分不包含 %s，它将被简单地解释为要启动的浏览器名称。[1]

3.14 版本中的变化: BROWSER 变量现在也可以用于重新排序平台默认浏览器列表。这在 macOS 上特别有用，因为平台默认浏览器不引用 PATH 中的命令行工具。

对于非 Unix 平台，或者当 Unix 上有远程浏览器可用时，控制进程不会等待用户使用完浏览器，而是允许远程浏览器在显示器上维护自己的窗口。如果 Unix 上没有远程浏览器可用，控制进程将启动一个新的浏览器并等待。

在 iOS 上，BROWSER 环境变量以及任何控制自动提升、浏览器偏好设置和新标签/窗口创建的参数都将被忽略。网页将始终在用户首选的浏览器中打开，在新标签页中，并将浏览器带到前台。在 iOS 上使用 webbrowser 模块需要 ctypes 模块。如果 ctypes 不可用，则对 open() 的调用将失败。

脚本 webbrowser 可用作模块的命令行接口。它接受一个 URL 作为参数。它接受以下可选参数：

-n, --new-window

如果可能，在新的浏览器窗口中打开 URL。

-t, --new-tab

在新的浏览器标签页中打开 URL。

这些选项当然是互斥的。使用示例：

python -m webbrowser -t "https://pythonlang.cn"

可用性: 不支持 WASI，不支持 Android。

定义了以下异常：

exception webbrowser.Error

浏览器控制错误时引发的异常。

定义了以下函数：

webbrowser.open(url, new=0, autoraise=True)

使用默认浏览器显示 url。如果 new 为 0，则如果可能，url 将在同一浏览器窗口中打开。如果 new 为 1，则如果可能，将打开一个新的浏览器窗口。如果 new 为 2，则如果可能，将打开一个新的浏览器页面（“标签页”）。如果 autoraise 为 True，则如果可能，窗口将提升（请注意，在许多窗口管理器下，无论此变量的设置如何，都会发生这种情况）。

如果成功启动浏览器，则返回 True，否则返回 False。

请注意，在某些平台上，尝试使用此函数打开文件名可能会成功并启动操作系统的关联程序。但是，这既不受支持也不具有可移植性。

引发一个 审计事件 webbrowser.open，参数为 url。

webbrowser.open_new(url)

如果可能，在默认浏览器的新窗口中打开 url；否则，在唯一的浏览器窗口中打开 url。

如果成功启动浏览器，则返回 True，否则返回 False。

webbrowser.open_new_tab(url)

如果可能，在默认浏览器的新页面（“标签页”）中打开 url；否则，等同于 open_new()。

如果成功启动浏览器，则返回 True，否则返回 False。

webbrowser.get(using=None)

返回浏览器类型 using 的控制器对象。如果 using 为 None，则返回一个适用于调用者环境的默认浏览器控制器。

webbrowser.register(name, constructor, instance=None, *, preferred=False)

注册浏览器类型 name。一旦注册了浏览器类型，get() 函数就可以返回该浏览器类型的控制器。如果未提供 instance，或为 None，则在需要时将调用 constructor 而不带参数来创建实例。如果提供了 instance，则永远不会调用 constructor，并且可以为 None。

将 preferred 设置为 True 会使此浏览器成为不带参数的 get() 调用的首选结果。否则，此入口点仅在您计划设置 BROWSER 变量或调用 get() 并传入与您声明的处理程序名称匹配的非空参数时才有用。

3.7 版本中的变化: 添加了 preferred 仅限关键字参数。

预定义了多种浏览器类型。此表列出了可传递给 get() 函数的类型名称以及控制器类的相应实例化，所有这些都在此模块中定义。

类型名称

类名称

备注

'mozilla'

Mozilla('mozilla')

'firefox'

Mozilla('mozilla')

'epiphany'

Epiphany('epiphany')

'kfmclient'

Konqueror()

(1)

'konqueror'

Konqueror()

(1)

'kfm'

Konqueror()

(1)

'opera'

Opera()

'links'

GenericBrowser('links')

'elinks'

Elinks('elinks')

'lynx'

GenericBrowser('lynx')

'w3m'

GenericBrowser('w3m')

'windows-default'

WindowsDefault

(2)

'macosx'

MacOSXOSAScript('default')

(3)

'safari'

MacOSXOSAScript('safari')

(3)

'google-chrome'

Chrome('google-chrome')

'chrome'

Chrome('chrome')

'chromium'

Chromium('chromium')

'chromium-browser'

Chromium('chromium-browser')

'iosbrowser'

IOSBrowser

(4)

备注

  1. “Konqueror” 是 Unix KDE 桌面环境的文件管理器，只有在 KDE 运行时使用才有意义。如果能可靠地检测 KDE 会很好；KDEDIR 变量不足。另请注意，即使使用 KDE 2 的 konqueror 命令，也使用名称“kfm”——实现选择运行 Konqueror 的最佳策略。

  2. 仅适用于 Windows 平台。

  3. 仅适用于 macOS。

  4. 仅适用于 iOS。

3.2 版本新增: 添加了一个新的 MacOSXOSAScript 类，并在 Mac 上使用它代替之前的 MacOSX 类。这增加了对打开当前未设置为操作系统默认浏览器的支持。

3.3 版本新增: 添加了对 Chrome/Chromium 的支持。

3.12 版本中的变化: 移除了对几个过时浏览器的支持。移除的浏览器包括 Grail、Mosaic、Netscape、Galeon、Skipstone、Iceape 和 Firefox 35 及以下版本。

3.13 版本中的变化: 添加了对 iOS 的支持。

这里有一些简单的例子：

url = 'https://docs.pythonlang.cn/'

# Open URL in a new tab, if a browser window is already open.
webbrowser.open_new_tab(url)

# Open URL in new window, raising the window if possible.
webbrowser.open_new(url)

浏览器控制器对象

浏览器控制器提供 name 属性，以及以下三个与模块级便利函数并行的函数：

controller.name

浏览器的系统相关名称。

controller.open(url, new=0, autoraise=True)

使用此控制器处理的浏览器显示 url。如果 new 为 1，则如果可能，将打开新的浏览器窗口。如果 new 为 2，则如果可能，将打开新的浏览器页面（“标签页”）。

controller.open_new(url)

如果可能，在此控制器处理的浏览器新窗口中打开 url；否则，在唯一的浏览器窗口中打开 url。别名 open_new()。

controller.open_new_tab(url)

如果可能，在此控制器处理的浏览器新页面（“标签页”）中打开 url；否则，等同于 open_new()。

脚注