XDG 桌面 Portal

相关文章

• Flatpak
• PipeWire#WebRTC 屏幕共享

来自 Flatpak 文档

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

Portal 专为与通过 Flatpak 沙箱化的应用程序一起使用而设计，但任何应用程序都可以使用 portal 来提供对功能的统一访问，而无需考虑桌面和工具包。这通常用于，例如，在 Wayland 上通过 PipeWire 允许屏幕共享，或在 Firefox 上 使用文件打开和保存对话框，这些对话框使用与当前桌面环境相同的工具包。

安装

安装 xdg-desktop-portal 和一个或多个后端。该软件包包含一个 systemd/User 服务，该服务将通过 D-Bus 自动启动。

后端

当应用程序向 portal 发送请求时，它由 xdg-desktop-portal 处理，然后将其转发到后端实现。这允许实现提供适合用户桌面环境的合适用户界面，并访问特定于环境的 API 以进行打开 URI 或录制屏幕等请求。可以同时安装和使用多个后端。例如，Sway 设置可以使用 xdg-desktop-portal-wlr 以获得屏幕共享支持，并使用 xdg-desktop-portal-gtk 作为 xdg-desktop-portal-wlr 未实现的所有其他接口的后备。

Portal 后端定义位于 /usr/share/xdg-desktop-portal/portals/*.portal 中。每个 portal 后端文件都包含它可以处理的接口列表，以及它支持的桌面环境。

后端和接口列表

下表列出了所有可用的后端及其对某些常见接口的支持。

后端	支持的环境	工具包	访问 portal	账户 portal	应用选择器 portal	后台 portal	剪贴板 portal	动态启动器 portal	邮件 portal	文件选择器 portal	全局快捷键 portal	抑制 portal	输入捕获 portal	通知 portal	打印 portal	远程桌面 portal	屏幕广播 portal	屏幕截图 portal	密钥 portal	设置 portal	壁纸 portal
xdg-desktop-portal-cosmic	COSMIC	iced	是	否	否	否	否	否	否	是	否	否	否	否	否	否	是	是	否	是	否
xdg-desktop-portal-dde	Deepin	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 实现了设置 portal 后端（仅用于配色方案设置）。
• gnome-keyring 实现了密钥 portal 后端。
• kwallet 实现了密钥 portal 后端。
• xdg-desktop-portal-shana^AUR 实现了文件选择器 portal 后端。它将请求重定向到 GNOME/GTK/KDE/LXQt 后端。
• xdg-desktop-portal-termfilechooser-git^AUR 实现了文件选择器 portal 后端。它允许使用终端文件管理器作为文件选择器。

配置

发出请求时，xdg-desktop-portal 将使用 /usr/share/xdg-desktop-portal/DE-portals.conf 文件，其中 DE 基于 XDG_CURRENT_DESKTOP 环境变量。这些文件由桌面环境本身提供，并确定在特定环境运行时应使用哪些后端。

如果要覆盖桌面环境默认值，或者桌面环境未提供默认配置，则可以在 $XDG_CONFIG_HOME/xdg-desktop-portal/portals.conf 中创建一个 portal 配置文件，以确定要使用哪些后端，无论是通用后端还是每个单独接口的后端。如果使用多个桌面环境，您还可以为每个环境创建多个 $XDG_CONFIG_HOME/xdg-desktop-portal/DE-portals.conf 文件。

例如，如果您的桌面环境没有 portal 后端，并且您想使用 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 用户单元 使用 drop-in snippet 设置 XDG_CURRENT_DESKTOP 环境变量来实现。例如，要使用与 KDE 关联的后端

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

[Service]
Environment="XDG_CURRENT_DESKTOP=KDE"

故障排除

Portal 未启动

为了使 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 检查是否设置了这些变量。如果未设置，请在启动合成器之前运行以下命令，将这些环境变量导入到 systemd 用户会话和 dbus 中（例如，将它们包含在合成器的配置文件中）。

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

注意： 这些环境变量需要在合成器启动之前设置。这通常通过合成器自己的配置完成，请参阅其文档以了解详细信息。

提示

• Sway 提供了一个 drop-in 文件，可以自动执行此操作，请参阅 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。

KDE Plasma 上 GTK 应用字体渲染不良

一些 GTK 应用程序在 Plasma 上需要 xdg-desktop-portal-gtk 才能正确渲染字体。安装它然后运行

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

GTK (或其他) 文件选择器无法工作

如果应用程序通过 xwayland 在 X 上运行（检查的最简单方法是运行 xeyes 并查看它们是否跟随鼠标在有问题的应用程序上），那么 xdg-desktop-portal-gtk 将按需显示，但是在您选择文件后，什么也不会发生。在这种情况下，将 DISPLAY=:0 添加到 xdg-desktop-portal-gtk 环境可能会有所帮助。为此，您可以按照上面关于 import-environment 的说明进行操作，或者只是编辑 xdg-desktop-portal-gtk 的 systemd 用户单元文件。或者，您可以强制应用程序在 wayland 下运行（即，如果它使用 electron）。

参见

• 项目主页
• Portal 文档：列出应用程序和后端可以实现的所有 API。