XDG 桌面門戶 - Arch Linux 中文维基

跳至內容

# XDG 桌面門戶

出自 Arch Linux 中文维基
翻譯狀態：

- 本文（或部分內容）譯自 XDG Desktop Portal，最近一次同步於 2025-09-01，若英文版本有所更改，則您可以幫助同步與翻譯更改的內容。
- 您可以在 ArchWiki 的對應頁面找到本文翻譯的原始修訂歷史。
- 本文可能與英文原文存在出入。

相關文章

- Flatpak
- PipeWire#WebRTC 屏幕共享

引自 Flatpak 文檔：

  門戶是用於安全訪問沙箱外資源的框架。沙箱內程序可以使用的特性包括：檢測網絡狀態；使用文件選擇器來打開文件；打開 URI；阻止設備睡眠、休眠或關機；列印；發送郵件；顯示通知；截取屏幕或錄屏［……］

門戶（portals）系統最初專為 Flatpak 應用程式設計，但任何應用程式均可藉助門戶訪問跨桌面環境和 UI 框架的統一功能。這一功能得到了廣泛使用，例如通過 PipeWire 在 Wayland 上實現屏幕共享，或讓 Firefox 採用與當前桌面環境相同 UI 框架的文件打開/保存對話框。

## 安裝

安裝 xdg-desktop-portal包 以及至少一個 #後端，該軟體包包含一個 systemd/用戶服務，通過 D-Bus 自動觸發啟動。

## 後端

當一個軟體通過 XDG 桌面門戶發起請求時，xdg-desktop-portal包 會將這個請求轉發至可用的後端實現，由後端實現適合桌面環境的 UI，並訪問特定於桌面環境的 API 處理諸如打開 URI、錄製屏幕之類的請求。後端可以安裝多個，例如使用 Sway 可以安裝 xdg-desktop-portal-wlr包 支持屏幕共享，並同時安裝 xdg-desktop-portal-gtk包 作為後備，處理 xdg-desktop-portal-wlr包 未實現的接口。

門戶後端配置儲存在 `/usr/share/xdg-desktop-portal/portals/*.portal` 中。門戶後端配置文件包含其支持的接口和桌面環境。

### 所有可用後端及其接口支持情況

後端 | 支持的桌面環境 | 使用的 UI 框架 | 接口支持情況
--- | --- | --- | ---
對話框 | 帳戶信息 | 應用程式選擇器 | 後台活動 | 剪貼板 | 桌面啟動項 | 電子郵件 | 文件選擇器 | 全局快捷鍵 | 用戶會話管理 | 輸入設備捕獲 | 系統通知 | 列印 | 遠程桌面 | 屏幕錄製 | 截屏 | 密鑰 | 系統設置 | 壁紙
xdg-desktop-portal-cosmic包 | COSMIC | iced | 是 | 否 | 否 | 否 | 否 | 否 | 否 | 是 | 否 | 否 | 否 | 否 | 否 | 否 | 是 | 是 | 否 | 是 | 否
xdg-desktop-portal-dde包 | 深度桌面環境 | Qt 5 | 是 | 是 | 是 | 是 | 否 | 否 | 否 | 是 | 是 | 是 | 否 | 是 | 否 | 否 | 否 | 是 | 是 | 是 | 是
xdg-desktop-portal-gnome包 | GNOME | GTK 4 | 是 | 是 | 是 | 是 | 是 | 是 | 否 | 是 | 否 | 否 | 是 | 是 | 是 | 是 | 是 | 是 | 否 | 是 | 是
xdg-desktop-portal-gtk包 | （通用） | GTK 3 | 是 | 是 | 是 | 否 | 否 | 是 | 是 | 是 | 否 | 是 | 否 | 是 | 是 | 否 | 否 | 否 | 否 | 是 | 否
xdg-desktop-portal-hyprland包 | Hyprland1 | Qt 6 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 是 | 否 | 是 | 否 | 否 | 否 | 是 | 是 | 否 | 否 | 否
xdg-desktop-portal-kde包 | KDE Plasma | Qt 6 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 是 | 否 | 是 | 否
xdg-desktop-portal-liri-gitAUR | Liri | Qt 5 | 是 | 是 | 是 | 是 | 否 | 否 | 是 | 是 | 否 | 是 | 否 | 是 | 是 | 否 | 是 | 是 | 否 | 是 | 是
xdg-desktop-portal-lxqt包 | LXQt | Qt 6 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 是 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 否
xdg-desktop-portal-tdAUR | theDesk | Qt 6 | 是 | 是 | 否 | 否 | 否 | 否 | 否 | 是 | 否 | 否 | 否 | 是 | 否 | 否 | 否 | 是 | 否 | 是 | 否
xdg-desktop-portal-wlr包 | wlroots | – | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 否 | 是 | 是 | 否 | 否 | 否
xdg-desktop-portal-xapp包 | Cinnamon2 | – | 否 | 否 | 否 | 是 | 否 | 否 | 否 | 否 | 否 | 是 | 否 | 否 | 否 | 否 | 否 | 是 | 否 | 是 | 是

1. 適用於所有基於 wlroots 的混成器，但提供針對 Hyprland 的額外功能，例如可在截屏或屏幕錄製時共享單個窗口。
2. 其也為 MATE 和 Xfce 提供部分支持。

除此以外，以下後端跨桌面環境實現了特定接口：

- darkman包 實現了系統設置接口（僅顏色方案設置）。
- gnome-keyring包 實現了密鑰接口。
- kwallet包 實現了密鑰接口。
- pikeruAUR 使用自己的 GUI 實現了文件選擇器接口。
- xdg-desktop-portal-shanaAUR 通過將請求重定向至 GNOME/GTK/KDE/LXQt 後端實現了文件選擇器接口。
- xdg-desktop-portal-termfilechooser-gitAUR 使用終端文件選擇器實現了文件選擇器接口。

## 配置

當收到請求時，`xdg-desktop-portal` 將會使用位於 `/usr/share/xdg-desktop-portal/桌面環境-portals.conf` 的配置文件，其中桌面環境由環境變量 `XDG_CURRENT_DESKTOP` 決定。配置文件由桌面環境提供，決定應當使用的後端。

如果需要自定義配置，或者使用的桌面環境並沒有提供默認配置，可以創建門戶配置文件 `$XDG_CONFIG_HOME/xdg-desktop-portal/portals.conf` 以決定全局或者特定接口使用的後端。如果使用多個桌面環境，也可以創建並配置特定桌面環境的配置文件 `$XDG_CONFIG_HOME/xdg-desktop-portal/桌面環境-portals.conf`。

例如，如果正在使用的桌面環境沒有門戶後端，希望使用xdg-desktop-portal-gtk包 作為通用後備後端，同時通過 xdg-desktop-portal-lxqt包 使用 LXQt 文件選擇器，可以使用以下配置：

    ~/.config/xdg-desktop-portal/portals.conf

    [preferred]
    default=gtk
    org.freedesktop.impl.portal.FileChooser=lxqt

參見 portals.conf(5)。

### 桌面環境偽裝

某些情況下（例如獨立使用窗口管理器時），可能需要讓 `xdg-desktop-portal` 以為正在使用特定的桌面環境。可以在 `xdg-desktop-portal.service` 用戶單元中使用附加配置片段添加環境變量 XDG_CURRENT_DESKTOP。例如，可以指定使用 KDE 配置的後端：

    ~/.config/systemd/user/xdg-desktop-portal.service.d/override.conf

    [Service]
    Environment="XDG_CURRENT_DESKTOP=KDE"

## 疑難解答

### 門戶無法啟動

要使 xdg-desktop-portal-wlr包 和 xdg-desktop-portal-hyprland包 正常工作，必須在 systemd 用戶會話中設置 `XDG_CURRENT_DESKTOP` 和 `WAYLAND_DISPLAY` 環境變量。

`XDG_CURRENT_DESKTOP` 需要設置為混成器名稱，例如 `XDG_CURRENT_DESKTOP=sway`。`WAYLAND_DISPLAY` 則由混成器自動設置。這兩個變量通常會在混成器啟動時自動設置，但如果 systemd 用戶會話先於混成器啟動，混成器啟動時需要導入這兩個變量。

注意：Hyprland 不會自動設置 `XDG_CURRENT_DESKTOP` 環境變量，需要手動配置。請參閱 Hyprland Wiki。

使用 `systemctl --user show-environment` 檢查這些變量是否已設置。如果未設置，請在啟動混成器時運行以下命令（例如，將其寫入混成器的配置文件），將這些環境變量導入到 systemd 用戶會話和 D-Bus 中：

    $ systemctl --user import-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP
    $ dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=混成器名称

注意：這些環境變量需要在混成器啟動時設置，通常通過混成器自身的配置完成，請參見混成器的文檔說明。
提示：Sway 提供了一個可自動完成此操作的插入文件，請參閱 Sway#配置。

更多詳情請參閱 [1] 和 [2]。

### 在多顯示器環境下使用 xdg-desktop-portal-wlr

`xdg-desktop-portal-wlr` 需要一個外部選擇器來選擇要共享的顯示器。默認按順序查找 slurp包、wofi包 和 bemenu包。若使用 slurp，收到屏幕共享請求後，滑鼠指針會變成十字形，需要點擊要共享的屏幕。若使用 wofi 或 bemenu，會出現一個可用顯示器的菜單供選擇。如果沒有任何選擇器可用，`xdg-desktop-portal-wlr` 會回退到找到的第一個顯示器。詳見 xdg-desktop-portal-wlr(5) § SCREENCAST OPTIONS。

### KDE Plasma 下 GTK 應用程式字體渲染不佳

部分 GTK 應用程式在 Plasma 環境中需要安裝 xdg-desktop-portal-gtk包 才能正確渲染字體。請安裝該軟體包，然後運行：

    $ /usr/lib/xdg-desktop-portal --replace

### GTK（可能還有其它的）文件選擇器無法工作

如果應用程式通過 Xwayland 運行（最簡單的檢查方法是運行 `xeyes`，然後將滑鼠指針移至應用程式窗口內，若程序運行在 Xwayland 下，其中眼睛會看向滑鼠指針），那麼 `xdg-desktop-portal-gtk` 會按需啟動，但在選擇文件後可能沒有任何反應。這種情況下，為 `xdg-desktop-portal-gtk` 的環境添加 `DISPLAY=:0` 可能會解決問題。要實現此操作，可以按照前文（#門戶無法啟動）關於 `import-environment` 的說明進行設置，或者直接編輯 `xdg-desktop-portal-gtk` 的 systemd 用戶單元文件。此外，也可以嘗試通過配置開啟應用程式的原生 Wayland 支持（例如對於 Electron 程序）。

## 參見

- 項目主頁
- 門戶文檔：列出了應用程式和後端可使用的所有接口。

分類：​

- Freedesktop.org

XDG 桌面門戶
新增話題