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

原始碼: Lib/webbrowser.py

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

在 Unix 系統下，X11 會優先使用圖形瀏覽器，但如果圖形瀏覽器不可用或沒有可用的 X11 顯示，則會使用文字模式瀏覽器。如果使用文字模式瀏覽器，呼叫程序將阻塞，直到使用者退出瀏覽器。

如果環境變數 BROWSER 存在，它將被解釋為以 os.pathsep 分隔的瀏覽器列表，這些瀏覽器將在平臺預設瀏覽器之前嘗試。當列表部分的某個值包含字串 %s 時，它將被解釋為文字瀏覽器命令列，引數 URL 將替換 %s；如果該值是一個單獨的單詞，並且指的是一個已註冊的瀏覽器，則該瀏覽器將被新增到搜尋列表的開頭；如果該部分不包含 %s，它將被簡單地解釋為要啟動的瀏覽器名稱。[1]

3.14 版本中的變化: BROWSER 變數現在也可以用於重新排序平臺預設瀏覽器列表。這在 macOS 上特別有用，因為平臺預設瀏覽器不引用 PATH 中的命令列工具。

對於非 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://python.club.tw"

可用性: 不支援 WASI，不支援 Android。

定義了以下異常：

exception webbrowser.Error

瀏覽器控制錯誤時引發的異常。

定義了以下函式：

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

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

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

請注意，在某些平臺上，嘗試使用此函式開啟檔名可能會成功並啟動作業系統的關聯程式。但是，這既不受支援也不具有可移植性。

引發一個 審計事件 webbrowser.open，引數為 url。

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，並且可以為 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.club.tw/'

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

瀏覽器控制器物件

瀏覽器控制器提供 name 屬性，以及以下三個與模組級便利函式並行的函式：

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

腳註