XDG 桌面门户

门户是一种用于安全地访问应用程序沙箱外部资源的框架。它们为应用程序提供了一系列常见的功能，包括：确定网络状态、使用文件选择器打开文件、打开URI、进行屏幕截图或录屏[...]

门户（Portals）是为了 Flatpak 应用程序使用而设计的，但是任何应用程序都可以使用门户来统一访问独立于桌面和工具包的功能。例如，在Wayland上通过 PipeWire 实现屏幕共享，在 Firefox 上使用和您当前的桌面环境相同的打开和保存文件对话框。

安装[编辑 | 编辑源代码]

安装 xdg-desktop-portal^包以及至少一个后端。此软件包包含一个会自动通过 D-Bus 启动的 systemd/用户服务。

当一个软件通过XDG桌面门户发起请求时， xdg-desktop-portal 会自动将这个请求转发至可用后端实现。这可在不同的桌面环境中访问特定桌面环境的 API，例如打开URI或录制屏幕等请求。你也可以安装多个后端进行使用：例如使用 Sway 的用户可以安装 xdg-desktop-portal-wlr^包用于屏幕共享的支持，同时安装 xdg-desktop-portal-gtk^包作为后备，以处理 xdg-desktop-portal-wlr 未实现的接口。

门户后端配置储存在 /usr/share/xdg-desktop-portal/portals/*.portal 中。每一个门户后端配置文件都包含了其支持的接口，以及其支持的桌面环境。

一些后端以及其支持情况[编辑 | 编辑源代码]

以下列出了所有的可用后端以及其接口的支持情况。

后端	支持的桌面环境	框架	对话框	账户信息	应用程序选择器	后台活动	剪贴板	创建桌面启动项	电子邮件	文件选择器	创建全局快捷键	用户会话管理	输入设备捕获	系统通知	打印	远程桌面	屏幕录制	截屏	密钥	系统设置	壁纸
xdg-desktop-portal-cosmic^包	COSMIC	iced	是	否	否	否	否	否	否	是	否	否	否	否	否	否	是	是	否	是	否
xdg-desktop-portal-dde^包	Deepin	Qt 5	是	是	是	是	否	否	否	是	是	是	否	是	否	否	否	是	是	是	是
xdg-desktop-portal-gnome^包	GNOME	GTK 4	是	是	是	是	是	是	否	Yes	否	否	是	是	是	是	是	是	否	是	是
xdg-desktop-portal-gtk^包	generic	GTK 3	是	是	是	否	否	是	是	是	否	是	否	是	是	否	否	否	否	是	否
xdg-desktop-portal-hyprland^包	Hyprland¹	Qt 6	否	否	否	否	否	否	否	否	是	否	是	否	否	否	是	是	否	否	否
xdg-desktop-portal-kde^包	KDE Plasma	Qt 6	是	是	是	是	否	是	是	是	是	是	是	是	是	是	是	是	否	是	否
xdg-desktop-portal-liri-git^AUR	Liri	Qt 5	是	是	是	是	否	否	是	是	否	是	否	是	是	否	是	是	否	是	是
xdg-desktop-portal-lxqt^包	LXQt	Qt 6	否	否	否	否	否	否	否	是	否	否	否	否	否	否	否	否	否	否	否
xdg-desktop-portal-td^AUR	theDesk	Qt 6	是	是	否	否	否	否	否	是	否	否	否	是	否	否	否	是	否	是	否
xdg-desktop-portal-wlr^包	wlroots	–	否	否	否	否	否	否	否	否	否	否	否	否	否	否	是	是	否	否	否
xdg-desktop-portal-xapp^包	Cinnamon²	–	否	否	否	是	否	否	否	否	否	是	否	否	否	否	否	是	否	是	是

适用于所有基于wlroots的混成器，但是其与 Hyprland 配合使用时提供额外功能，例如共享单个窗口。
其也为MATE和Xfce提供部分支持。

除此以外，以下软件包可以提供特定的后端服务，而不特定于桌面环境：

darkman^包实现了系统设置门户后端(仅限于颜色方案设置)。
gnome-keyring^包实现了密匙门户后端。
kwallet^包实现了密钥门户后端。
xdg-desktop-portal-shana^AUR 实现了文件选择器门户后端，其会将请求重定向至 GNOME/GTK/KDE/LXQt 后端。
xdg-desktop-portal-termfilechooser-git^AUR 实现了文件选择器门户后端，其允许使用终端文件选择器作为文件选择器。

配置[编辑 | 编辑源代码]

当收到请求时，xdg-desktop-portal 将会使用位于 /usr/share/xdg-desktop-portal/DE-portals.conf 的配置文件，其中DE由环境变量 XDG_CURRENT_DESKTOP 决定。这些文件由桌面环境提供，其决定了在不同的桌面环境中应当使用哪些后端。

如果你想使用自定义配置，或者你使用的桌面环境并没有提供默认配置，你可以创建门户配置文件 $XDG_CONFIG_HOME/xdg-desktop-portal/portals.conf 以决定全局或者特定接口使用的后端。如果你使用多个桌面环境，你也可以根据对应的桌面环境创建文件 $XDG_CONFIG_HOME/xdg-desktop-portal/DE-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"

注意，如果你不是通过 systemctl 修改的配置单元文件，请进行一次 daemon-reload 操作。

疑难解答[编辑 | 编辑源代码]

xdg-desktop-portal-wlr 在sway上不会自动启动[编辑 | 编辑源代码]

要让 xdg-desktop-portal-wlr 或 xdg-desktop-portal-hyprland^包正常运行，你需要在systemd 用户会话中设置环境变量 XDG_CURRENT_DESKTOP 和 WAYLAND_DISPLAY。其中 XDG_CURRENT_DESKTOP 需要设置为你使用的混成器，例如 XDG_CURRENT_DESKTOP=sway。WAYLAND_DISPLAY 应当由混成器自动设置。

你可以通过命令 systemctl --user show-environment 来检查这些环境变量是否被设置。如果没有，请在启动混成器之前运行以下命令，以将这些环境变量导入到system用户会话以及dbus中(例如将其包含在混成器的配置文件中)。

$ systemctl --user import-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP
$ dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=compositor_name

注意： 这些环境变量需要在合成器启动之前设置。通常通过合成器自身的配置来完成，详情请参阅其文档。

提示：

Sway 提供了一个配置文件以自动设置这些变量，参见 Sway#配置。
Hyprland 可能不会自动设置这些环境变量，这种情况下你需要手动设置环境变量，参见 Hyprland Wiki。

详见 [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。

GTK应用在KDE Plasma中字体渲染很差[编辑 | 编辑源代码]

在KDE桌面环境中，一些GTK应用需要 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)。

参见[编辑 | 编辑源代码]

项目主页
门户文档：列出应用程序和后端可使用的所有 API。