# `webbrowser` --- 方便的網頁瀏覽器控制器

原始碼：Lib/webbrowser.py

`webbrowser` 模組提供了一個高階介面，允許向使用者顯示基於網頁的文件。在大多數情況下，只需從此模組呼叫 `open()` 函式即可完成正確的操作。

在 Unix 下，X11 下首選圖形瀏覽器，但如果圖形瀏覽器不可用或 X11 顯示不可用，則將使用文字模式瀏覽器。如果使用文字模式瀏覽器，則呼叫程序將會阻塞 (block)，直到使用者退出瀏覽器。

如果環境變數 `BROWSER` 存在，它會被直譯為以 `os.pathsep` 分隔的瀏覽器串列，以在平台預設值之前嘗試。當串列部分的值包含字串 `%s` 時，它會被直譯為字面瀏覽器命令列，並使用引數 URL 替換 `%s`；如果值是指向已註冊瀏覽器之一的單個字，則此瀏覽器會被新增到搜尋串列的前面；如果該部分不包含 `%s`，則它僅被直譯為要啟動的瀏覽器的名稱。 [1]

在 3.14 版的變更: `BROWSER` 變數現在也可以用來重新排序平台預設值的串列。這在 macOS 上特別有用，因為該平台預設值不會參照 `PATH` 上的命令列工具。

對於非 Unix 平台，或當 Unix 上有可用的遠端瀏覽器時，控制行程不會等待使用者以完成瀏覽器，而是允許遠端瀏覽器在顯示器上維護自己的視窗。如果遠端瀏覽器在 Unix 上不可用，控制行程將啟動新的瀏覽器並等待。

在 iOS 上，`BROWSER` 環境變數以及控制自動引發 (autoraise)、瀏覽器設定和新分頁/視窗建立的任何引數都將被忽略。網頁將始終在使用者偏好的瀏覽器中的新分頁中開啟，並將瀏覽器帶到前台。在 iOS 上使用 `webbrowser` 模組需要 `ctypes` 模組。如果 `ctypes` 不可用，則呼叫 `open()` 將會失敗。

## 命令列介面

腳本 webbrowser 可以用作模組的命令列介面。它接受 URL 作為引數。它接受以下可選參數：

-n, --new-window

  如果可能的話會在新的瀏覽器視窗中開啟 URL。

-t, --new-tab

  會在新的瀏覽器分頁 ("tab") 中開啟 URL。

這些選項自然是相互排斥的。用法範例如下：

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

可用性: not WASI, not Android.

以下例外有被定義於該模組：

exception webbrowser.Error

  當瀏覽器控制項發生錯誤時引發例外。

以下函式有被定義於該模組：

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

  使用預設瀏覽器顯示 url。如果 new 為 0，則盡可能在同一瀏覽器視窗中開啟 url。如果 new 為 1，則盡可能開啟一個新的瀏覽器視窗。如果 new 為 2，則盡可能開啟一個新的瀏覽器分頁 ("tab")。如果 autoraise 為 `True`，則盡可能提升視窗（請注意，無論此變數的設定如何，許多視窗管理器下都會發生這種情況）。

  如果瀏覽器成功啟動則回傳 `True`，否則回傳 `False`。

  請注意，在某些平台上，嘗試使用此函式開啟檔案名稱可能能夠運作並啟動作業系統的關聯程式。然而這既不支援也不可移植。

  引發一個附帶引數 `url` 的稽核事件 `webbrowser.open`。

webbrowser.open_new(url)

  盡可能在預設瀏覽器的新視窗中開啟 url，否則在唯一的瀏覽器視窗中開啟 url。

  如果瀏覽器成功啟動則回傳 `True`，否則回傳 `False`。

webbrowser.open_new_tab(url)

  盡可能在預設瀏覽器的新分頁 ("tab") 中開啟 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)
`'macos'` | `MacOS('default')` | (3)
`'safari'` | `MacOS('safari')` | (3)
`'chrome'` | `MacOS('google chrome')` | (3)
`'firefox'` | `MacOS('firefox')` | (3)
`'google-chrome'` | `Chrome('google-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 的支援。

在 3.15 版被加入: `MacOS` has been added as a replacement for `MacOSXOSAScript`, opening browsers via /usr/bin/open instead of osascript.

自從版本 3.15 後不推薦使用，將會自版本 3.17 中移除。: `MacOSXOSAScript` is deprecated in favour of `MacOS`. Using /usr/bin/open instead of osascript is a security and usability improvement: osascript may be blocked on managed systems due to its abuse potential as a general-purpose scripting interpreter.

以下是一些簡單範例：

    url = 'https://docs.python.org/'

    # 如果瀏覽器視窗已打開，則在新分頁中開啟 URL。
    webbrowser.open_new_tab(url)

    # 在新視窗中開啟 URL，如果可能的話提升視窗。
    webbrowser.open_new(url)

## 瀏覽器控制器物件

瀏覽器控制器提供了 `name` 屬性和以下三個與模組層級便利函式相同的方法：

controller.name

  瀏覽器的系統相依名稱 (system-dependent name)。

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

  使用此控制器處理的瀏覽器顯示 url。如果 new 為 1，則盡可能開啟一個新的瀏覽器視窗。如果 new 為 2，則盡可能開啟一個新的瀏覽器分頁 ("tab")。

controller.open_new(url)

  盡可能在此控制器處理的瀏覽器的新視窗中開啟 url，否則在唯一的瀏覽器視窗中開啟 url。別名為 `open_new()`。

controller.open_new_tab(url)

  盡可能在此控制器處理的瀏覽器的新分頁 ("tab") 中開啟 url，否則相當於 `open_new()`。

註腳

[1]

此處命名的無完整路徑可執行檔將在 `PATH` 環境變數中給定的目錄中被搜尋。