This document is for an old version of Python that is no longer supported. You should upgrade and read the Python 当前稳定版本的文档.

# 20.1. `webbrowser` — 方便的Web浏览器控制器

源码： Lib/webbrowser.py

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

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

If the environment variable `BROWSER` exists, it is interpreted to override the platform default list of browsers, as an `os.pathsep`-separated list of browsers to try in order. When the value of a list part contains the string `%s`, then it is interpreted as a literal browser command line to be used with the argument URL substituted for `%s`; if the part does not contain `%s`, it is simply interpreted as the name of the browser to launch. 1

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

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

    python -m webbrowser -t "http://www.python.org"

定义了以下异常：

exception `webbrowser.``Error`

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

定义了以下函数：

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

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

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

  在 2.5 版更改: new can now be 2.

`webbrowser.``open_new`(url)

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

`webbrowser.``open_new_tab`(url)

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

  2.5 新版功能.

`webbrowser.``get`([name])

  Return a controller object for the browser type name. If name is empty, return a controller for a default browser appropriate to the caller’s environment.

`webbrowser.``register`(name, constructor[, instance])

  注册 name 浏览器类型。 注册浏览器类型后， `get()` 函数可以返回该浏览器类型的控制器。 如果没有提供 instance，或者为 `None`，constructor 将在没有参数的情况下被调用，以在需要时创建实例。 如果提供了 instance，则永远不会调用 constructor，并且可能是 `None`。

  This entry point is only useful if you plan to either set the `BROWSER` variable or call `get()` with a nonempty argument matching the name of a handler you declare.

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

类型名 | 类名 | 注释
--- | --- | ---
`'mozilla'` | `Mozilla('mozilla')` |
`'firefox'` | `Mozilla('mozilla')` |
`'netscape'` | `Mozilla('netscape')` |
`'galeon'` | `Galeon('galeon')` |
`'epiphany'` | `Galeon('epiphany')` |
`'skipstone'` | `BackgroundBrowser('skipstone')` |
`'kfmclient'` | `Konqueror()` | (1)
`'konqueror'` | `Konqueror()` | (1)
`'kfm'` | `Konqueror()` | (1)
`'mosaic'` | `BackgroundBrowser('mosaic')` |
`'opera'` | `Opera()` |
`'grail'` | `Grail()` |
`'links'` | `GenericBrowser('links')` |
`'elinks'` | `Elinks('elinks')` |
`'lynx'` | `GenericBrowser('lynx')` |
`'w3m'` | `GenericBrowser('w3m')` |
`'windows-default'` | `WindowsDefault` | (2)
`'macosx'` | `MacOSX('default')` | (3)
`'safari'` | `MacOSX('safari')` | (3)
`'google-chrome'` | `Chrome('google-chrome')` | (4)
`'chrome'` | `Chrome('chrome')` | (4)
`'chromium'` | `Chromium('chromium')` | (4)
`'chromium-browser'` | `Chromium('chromium-browser')` | (4)

注释:

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

2. 仅限 Windows 平台。

3. 仅限 Mac OS X 平台。

4. Support for Chrome/Chromium has been added in version 2.7.5.

以下是一些简单的例子:

    url = 'http://www.python.org/'

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

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

## 20.1.1. 浏览器控制器对象

浏览器控制器提供三个与模块级便捷函数相同的方法：

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

  2.5 新版功能.

备注

1

  这里命名的不带完整路径的可执行文件将在 `PATH` 环境变量给出的目录中搜索。