使用通知¶

GNOME 应用程序应该使用通知来告知用户发生了需要他们关注的事情。

通知不应该具有侵入性或分散注意力。

有关何时使用通知的更多信息，您应该遵循人类界面指南。

重要提示

请记住，用户可以为特定应用程序或全局禁用通知。您不应该仅仅依赖通知。

先决条件¶

为了在 GNOME 中使用通知，您需要

使用 GApplication 或 GtkApplication
提供一个与您的应用程序 ID 相同的有效桌面文件
确保您的应用程序可以通过 D-Bus 激活

桌面文件和 D-Bus 激活提供通知持久性，允许桌面将通知与应用程序关联起来，即使应用程序未运行。

通知的结构¶

典型的通知包含许多要素

一行标题
更长、更详细的消息正文（可选）
一个图标（可选）
操作，每个操作都有一个用于按钮的标签（可选）
此外，通知可以标记为紧急

创建通知¶

要发送通知，首先创建一个 GNotification 对象，并将通知的数据添加到其中

g_autoptr(GNotification) notification = g_notification_new ("Lunch is ready");

g_notification_set_body (notification, "Today we have pancakes and salad, and fruit and cake for dessert");

g_autoptr(GFile) file = g_file_new_for_path ("fruitbowl.png");
g_autoptr(GFileIcon) icon = g_file_icon_new (file);

// The notification instance will acquire a reference on the icon
g_notification_set_icon (notification, G_ICON (icon));

notification = Gio.Notification()
notification.set_title("Lunch is ready")
notification.set_body("Today we have pancakes and salad, and fruit and cake for dessert")

file = Gio.File.new_for_path("fruitbowl.png")
icon = Gio.FileIcon(file=file)

notification.set_icon(icon)

var notification = new Notification ("Lunch is ready");

notification.set_body ("Today we have pancakes and salad, and fruit and cake for dessert");

var file = new File.for_path ("fruitbowl.png");

var icon = new FileIcon (file);

// The notification instance will acquire a reference on the icon
notification.set_icon (icon);

const notification = new Gio.Notification();

notification.set_title("Lunch is ready");
notification.set_body(
  "Today we have pancakes and salad, and fruit and cake for dessert",
);

const file = Gio.File.new_for_path("fruitbowl.png");

const icon = new Gio.FileIcon({file});

// The notification instance will acquire a reference on the icon
notification.set_icon(icon);

请注意，标题应该简短；正文可以更长，例如一段文字。图标可能会以较小的尺寸显示（例如，24x24），因此请选择在较小尺寸下仍然可读的图标。

要将您的通知显示给用户，请使用 GApplication 函数来完成此操作

// The application instance will acquire a reference on the
// notification object
g_application_send_notification (application, "lunch-is-ready", notification);

# The Application instance will acquire a reference on the
# notification object
application.send_notification("lunch-is-ready", notification)

// The application instance will acquire a reference on the
// notification object
application.send_notification ("lunch-is-ready", notification);

// The application instance will acquire a reference on the
// notification object
application.send_notification("lunch-is-ready", notification);

您需要为您的通知提供一个 ID。如果想要更新现有的通知，可以使用此 ID：只需发送一个具有相同 ID 的通知即可。请注意，在发送通知后，不需要保留 GNotification 对象；您可以立即释放它。它不是与可见通知关联的“实时”对象。

添加操作¶

通常，您希望用户能够以某种方式对通知做出反应，而不仅仅是关闭它。GNotification 允许您通过将操作与通知关联来实现这一点。这些通常会以弹出窗口中的按钮形式呈现。一个操作具有特殊作用，它是“默认”操作，当用户单击通知而不是特定按钮时会激活该操作。

g_notification_set_default_action (notification, "app.go-to-lunch");
g_notification_add_button (notification, "5 minutes", "app.reply-5-minutes");
g_notification_add_button (notification, "Order takeout", "app.order-takeout");

notification.set_default_action("app.go-to-lunch")
notification.add_button("5 minutes", "app.reply-5-minutes")
notification.add_button("Order takeout", "app.order-takeout")

notification.set_default_action ("app.go-to-lunch");
notification.add_button ("5 minutes", "app.reply-5-minutes");
notification.add_button ("Order takeout", "app.order-takeout");

notification.set_default_action("app.go-to-lunch");
notification.add_button("5 minutes", "app.reply-5-minutes");
notification.add_button("Order takeout", "app.order-takeout");

这里使用带有“app.” 前缀的名称引用这些操作。这表示这些操作必须添加到您的 GApplication 中。您不能在 GNotifications 中使用任何其他操作（具有“win.” 前缀的窗口特定操作，或使用其他前缀的快捷键将不起作用）。

带有参数的操作¶

一种常见模式是将“target”参数传递给操作，该参数包含有关通知的足够详细信息，以便您的应用程序能够以有意义的方式做出反应。

例如，以下是如何为新安装的应用程序提供启动按钮的通知

g_autofree char *title = g_strdup_printf ("%s is now installed", appname);
g_autoptr(GNotification) notification = g_notification_new (title);

g_notification_add_button_with_target (notification, "Launch", "app.launch", "s", appid);

g_application_send_notification (application, "app-installed", notification);

notification = Gio.Notification()
notification.set_title(f"{appname} is now installed")

notification.add_button_with_target("Launch", "app.launch", "s", appid)

application.send_notification("app-installed", notification)

string title = appname + " is now installed";
var notification = new Notification (title);

notification.add_button_with_target ("Launch", "app.launch", "s", appid);

application.send_notification ("app-installed", notification);

const title = appname + " is now installed";
const notification = new Gio.Notification();
notification.set_title(title);

notification.add_button_with_target(
  "Launch",
  "app.launch",
  GLib.Variant.new_string(appid),
);

application.send_notification("app-installed", notification);

为了使之工作，您的应用程序需要具有一个合适的“launch”操作，该操作将应用程序 ID 作为字符串参数。

static GActionEntry actions[] = {
  { "launch", launch_application, "s", NULL, NULL },
    // ...
};

g_action_map_add_action_entries (G_ACTION_MAP (application),
                                 actions, G_N_ELEMENTS (actions),
                                 application);

# The "launch_application" function is defined elsewhere
action = Gio.SimpleAction(name="launch")
action.connect("activate", launch_application)
application.add_action(action)

// the "launch_application" function is defined elsewhere
ActionEntry actions[] = {
  { "launch", launch_application },
  // ...
};

application.add_action_entries (actions, application);

// the "launch_application" function is defined elsewhere
const action = new Gio.SimpleAction({ name: "launch" });
action.connect("activate", launch_application);
application.add_action(action);

过时的通知¶

有时，通知不再相关，不应再持久存在。在这种情况下，您可以显式地撤回它，如下所示

if (now_is_tea_time ())
  g_application_withdraw_notification (application, "lunch-is-ready");

if now_is_tea_time():
    application.withdraw_notification("lunch-is-ready")

if (now_is_tea_time ())
  application.withdraw_notification ("lunch-is-ready");

if (now_is_tea_time()) {
   application.withdraw_notification("lunch-is-ready");
}

禁用通知¶

如果您的应用程序使用通知，您应该允许用户禁用它们。

GNOME 有一个通用的“请勿打扰”模式，但每个应用程序都可以通过“通知”设置面板单独控制。

为了使您的应用程序出现在面板中，请将以下行添加到您的桌面文件中

X-GNOME-UsesNotifications=true