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

原始碼：Lib/webbrowser.py

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

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

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

對於非 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"

Availability: 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)

'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.python.org/'

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

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

瀏覽器控制器物件

瀏覽器控制器提供了這些與三個模組層級便利函式相同的方法：

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

註腳