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

源代码： Lib/webbrowser.py

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

在 Unix 系统下，如果可以使用图形浏览器，则首选使用图形浏览器；如果图形浏览器不可用或 X11 显示器不可用，则将使用文本模式浏览器。如果使用文本模式浏览器，则调用进程将阻塞，直到用户退出浏览器。

如果存在环境变量 BROWSER，则将其解释为以 os.pathsep 分隔的浏览器列表，并在平台默认浏览器之前尝试使用这些浏览器。当列表部分的值包含字符串 %s 时，它将被解释为要使用的字面浏览器命令行，其中参数 URL 替换为 %s；如果该部分不包含 %s，则它将被简单地解释为要启动的浏览器的名称。 [1]

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

脚本 webbrowser 可以用作该模块的命令行界面。它接受一个 URL 作为参数。它接受以下可选参数：-n 在新浏览器窗口中打开 URL（如果可能）；-t 在新的浏览器页面（“标签页”）中打开 URL。当然，这些选项是互斥的。使用示例

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

可用性：不支持 Emscripten，不支持 WASI。

此模块在 WebAssembly 平台 wasm32-emscripten 和 wasm32-wasi 上不可用或无法正常工作。有关更多信息，请参阅 WebAssembly 平台。

定义了以下异常

异常 webbrowser.Error

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

定义了以下函数

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

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

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

使用参数 url 引发 审计事件 webbrowser.open。

webbrowser.open_new(url)

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

webbrowser.open_new_tab(url)

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

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

备注

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

  2. 仅限 Windows 平台。

  3. 仅限 macOS 平台。

3.3 版新增： 已添加对 Chrome/Chromium 的支持。

3.12 版更改： 已删除对多个过时浏览器的支持。删除的浏览器包括 Grail、Mosaic、Netscape、Galeon、Skipstone、Iceape 和 Firefox 35 及以下版本。

3.11 版后弃用，将在 3.13 版中删除： MacOSX 已弃用，请改用 MacOSXOSAScript。

以下是一些简单的例子

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)

浏览器控制器对象

浏览器控制器提供了以下方法，它们与三个模块级便捷函数的功能类似

webbrowser.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()。

脚注