webbrowser — 便捷的 Web 浏览器控制器

源代码: Lib/webbrowser.py

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

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

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

对于非 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。

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

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

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，并且 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)

浏览器控制器对象

浏览器控制器提供了这些方法，它们与模块级便利函数中的三个相对应

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

脚注