Notification 系统通知

系统级别发送在页面外部显示的通知。

何时使用

• 在智能体执行复杂任务时，可推送系统应用级别通知，使用户随时掌握任务进展。
• 受操作系统通知权限管控，仅用于弱通知使用。

注意

• Notification为系统应用通知，受操作系统通知权限管控，如果系统通知权限被关闭，XNotification 的 open 方法调用将无任何效果。系统权限设置。
• XNotification 是由扩展 window.Notification 实现的，如果浏览器环境不支持 Notification，XNotification 的方法调用将无任何效果。
• XNotification 通知样式与效果均以当前浏览器环境对 Notification 的支持为准，例如 dir 属性会被大部分浏览器忽略。
• XNotification 仅对当前实例下的通知进行关闭管理，实例变更后（例：浏览器页面刷新）对已发送的通知无管理关闭能力。

代码演示

Hooks 调用

Notification permission has been denied, You need to manually reset the notification permissions in the website settings to trigger the permission request pop-up.

Hooks 调用

hooks 调用。发送通知前需要向用户请求通知权限，授权可通知后可发送通知，若授权禁止通知则不可以发送通知。

<script setup lang="tsx">
defineOptions({ name: 'AXNotificationHooksV2' });

import type { XNotificationOpenArgs } from 'ant-design-x-vue';
import { notification } from 'ant-design-x-vue';
import { Button, Flex } from 'ant-design-vue';

const DescribeInfo: Record<NotificationPermission, string> = {
  denied:
    'Notification permission has been denied, You need to manually reset the notification permissions in the website settings to trigger the permission request pop-up.',
  granted:
    'Notification permission has been granted, you can click the "Open a notification" button to push a notification.',
  default: 'Please Request Permission, After the request is approved, you can push notifications.',
};

const openData: XNotificationOpenArgs = {
  title: 'Task completed',
  body: 'The task was completed at 13:12',
  icon: 'https://mdn.alipayobjects.com/huamei_iwk9zp/afts/img/A*eco6RrQhxbMAAAAAAAAAAAAADgCCAQ/original',
  onClick: (event, close) => {
    console.log('onClick', event, close);
    close?.();
  },
  onClose: (event) => {
    console.log('onClose', event);
  },
  onError: (event) => {
    console.log('onError', event);
  },
  onShow: (event) => {
    console.log('onShow', event);
  },
};

const [{ permission }, { open, requestPermission, close }] = notification.useNotification();

defineRender(() => (
  <Flex vertical gap="middle">
    {DescribeInfo[permission.value]}
    <Flex gap="middle">
      <Button
        disabled={permission.value !== 'default'}
        type="primary"
        onClick={() => requestPermission()}
      >
        {permission.value === 'default'
          ? 'Please Request Permission'
          : `Notification permission has been ${permission.value}`}
      </Button>
      <Button
        disabled={permission.value !== 'granted'}
        type="primary"
        onClick={() => open(openData)}
      >
        Open a notification
      </Button>
      <Button danger disabled={permission.value !== 'granted'} onClick={() => close()}>
        Destroy All
      </Button>
    </Flex>
  </Flex>
));
</script>

隐藏源代码

自动关闭延迟

Notification permission has been denied, You need to manually reset the notification permissions in the website settings to trigger the permission request pop-up.

自动关闭延迟

使用 duration 设置通知框自动关闭的延时。

<script setup lang="tsx">
defineOptions({ name: 'AXNotificationDurationV2' });

import { notification } from 'ant-design-x-vue';
import { Button, Flex } from 'ant-design-vue';

const describeInfo: Record<NotificationPermission, string> = {
  denied:
    'Notification permission has been denied, You need to manually reset the notification permissions in the website settings to trigger the permission request pop-up.',
  granted:
    'Notification permission has been granted, you can click the "Open a notification" button to push a notification.',
  default: 'Please Request Permission, After the request is approved, you can push notifications.',
};

const [{ permission }, { open, requestPermission }] = notification.useNotification();

const openClick = () => {
  open({
    title: 'Task completed',
    body: 'The task was completed at 13:12',
    duration: 4.5,
    icon: 'https://mdn.alipayobjects.com/huamei_iwk9zp/afts/img/A*eco6RrQhxbMAAAAAAAAAAAAADgCCAQ/original',
    onClick: (event, close) => {
      console.log('onClick', event, close);
      close?.();
    },
    onClose: (event) => {
      console.log('onClose', event);
    },
    onError: (event) => {
      console.log('onError', event);
    },
    onShow: (event) => {
      console.log('onShow', event);
    },
  });
};

defineRender(() => (
  <Flex vertical gap="middle">
    {describeInfo[permission.value]}
    <Flex gap="middle">
      <Button disabled={permission.value !== 'default'} type="primary" onClick={() => requestPermission()}>
        {permission.value === 'default'
          ? 'Please Request Permission'
          : `Notification permission has been ${permission.value}`}
      </Button>
      <Button disabled={permission.value !== 'granted'} type="primary" onClick={openClick}>
        Open a notification
      </Button>
    </Flex>
  </Flex>
));
</script>

隐藏源代码

关闭指定通知

Notification permission has been denied, You need to manually reset the notification permissions in the website settings to trigger the permission request pop-up.

关闭指定通知

关闭指定 tag 通知框。

<script setup lang="tsx">
defineOptions({ name: 'AXNotificationCloseTagV2' });

import { notification } from 'ant-design-x-vue';
import { Button, Flex } from 'ant-design-vue';

const describeInfo: Record<NotificationPermission, string> = {
  denied:
    'Notification permission has been denied, You need to manually reset the notification permissions in the website settings to trigger the permission request pop-up.',
  granted:
    'Notification permission has been granted, you can click the "Open a notification" button to push a notification.',
  default: 'Please Request Permission, After the request is approved, you can push notifications.',
};

const [{ permission }, { open, close, requestPermission }] = notification.useNotification();

const openClick = () => {
  open({
    title: 'Task completed',
    body: 'The task was completed at 13:12',
    tag: 'tag_task_completed',
    icon: 'https://mdn.alipayobjects.com/huamei_iwk9zp/afts/img/A*eco6RrQhxbMAAAAAAAAAAAAADgCCAQ/original',
    onClick: (event, close) => {
      console.log('onClick', event, close);
      close?.();
    },
    onClose: (event) => {
      console.log('onClose', event);
    },
    onError: (event) => {
      console.log('onError', event);
    },
    onShow: (event) => {
      console.log('onShow', event);
    },
  });
};

defineRender(() => (
  <Flex vertical gap="middle">
    {describeInfo[permission.value]}
    <Flex gap="middle">
      <Button disabled={permission.value !== 'default'} type="primary" onClick={() => requestPermission()}>
        {permission.value === 'default'
          ? 'Please Request Permission'
          : `Notification permission has been ${permission.value}`}
      </Button>
      <Button disabled={permission.value !== 'granted'} type="primary" onClick={openClick}>
        Open a notification
      </Button>
      <Button
        danger
        disabled={permission.value !== 'granted'}
        onClick={() => close(['tag_task_completed'])}
      >
        Destroy tag
      </Button>
    </Flex>
  </Flex>
));
</script>

隐藏源代码

静态方法

静态方法

静态方法调用。发送通知前需要向用户请求通知权限，授权可通知后可发送通知，若授权禁止通知则不可以发送通知。

<script setup lang="tsx">
defineOptions({ name: 'AXNotificationStaticMethodV2' });

import { notification } from 'ant-design-x-vue';
import { Button, Flex } from 'ant-design-vue';
import { ref, onMounted } from 'vue';

const describeInfo: Record<NotificationPermission, string> = {
  denied:
    'Notification permission has been denied, You need to manually reset the notification permissions in the website settings to trigger the permission request pop-up.',
  granted:
    'Notification permission has been granted, you can click the "Open a notification" button to push a notification.',
  default: 'Please Request Permission, After the request is approved, you can push notifications.',
};

const permission = ref<NotificationPermission>();

onMounted(() => {
  permission.value = notification.permission;
});

const request = async () => {
  const result = await notification.requestPermission();
  permission.value = result;
};

const open = () => {
  notification.open({
    title: 'Task completed',
    body: 'The task was completed at 13:12',
    badge:
      'https://mdn.alipayobjects.com/huamei_iwk9zp/afts/img/A*eco6RrQhxbMAAAAAAAAAAAAADgCCAQ/original',
    icon: 'https://mdn.alipayobjects.com/huamei_iwk9zp/afts/img/A*eco6RrQhxbMAAAAAAAAAAAAADgCCAQ/original',
    onClick: (event, close) => {
      console.log('onClick', event, close);
      close?.();
    },
    onClose: (event) => {
      console.log('onClose', event);
    },
    onError: (event) => {
      console.log('onError', event);
    },
    onShow: (event) => {
      console.log('onShow', event);
    },
  });
};

const closeAll = () => {
  notification.close();
};

defineRender(() => (
  <Flex vertical gap="middle">
    {permission.value && describeInfo[permission.value]}
    <Flex gap="middle">
      <Button disabled={permission.value !== 'default'} type="primary" onClick={request}>
        {permission.value === 'default'
          ? 'Please Request Permission'
          : `Notification permission has been ${permission.value}`}
      </Button>
      <Button disabled={permission.value !== 'granted'} type="primary" onClick={open}>
        Open a notification
      </Button>
      <Button danger disabled={permission.value !== 'granted'} onClick={closeAll}>
        Destroy All
      </Button>
    </Flex>
  </Flex>
));
</script>

隐藏源代码

API

成功发送通知需要确保已授权当前域名通知权限。

XNotification

属性	说明	类型	默认值	版本
permission	表明当前用户是否授予当前来源（origin）显示 web 通知的权限。	NotificationPermission	-	-
requestPermission	向用户为当前来源请求显示通知的权限。	() => Promise<NotificationPermission>	-	-
open	向用户推送一个通知	(config: XNotificationOpenArgs) => void	-	-
close	关闭已推送的通知，可以传入 tag 列表关闭指定通知，没有参数则会关闭所有通知	(config?: string[]) => void	-	-

NotificationPermission

type NotificationPermission =
  | 'granted' // 用户已明确授予当前源显示系统通知的权限。
  | 'denied' // 用户已明确拒绝当前源显示系统通知的权限。
  | 'default'; // 用户决定未知；在这种情况下，应用程序的行为就像权限被"拒绝"一样。

XNotificationOpenArgs

type XNotificationOpenArgs = NotificationOptions & {
  title: string;
  onClick?: (event: Event, close?: Notification['close']) => void;
  onClose?: (event: Event) => void;
  onError?: (event: Event) => void;
  onShow?: (event: Event) => void;
  duration?: number;
};

NotificationOptions

interface NotificationOptions {
  badge?: string;
  body?: string;
  data?: any;
  dir?: NotificationDirection;
  icon?: string;
  lang?: string;
  requireInteraction?: boolean;
  silent?: boolean | null;
  tag?: string;
}

useNotification

type useNotification = [
  { permission: NotificationPermission },
  {
    open: XNotification['open'];
    close: XNotification['close'];
    requestPermission: () => Promise<NotificationPermission>;
  },
];

系统权限设置

在 Windows 上更改 通知 设置

在 Windows 系统上不同版本系统的设置路径会有不同，可大概参考路径："开始"菜单 > "设置" > "系统" > 然后在左侧选择 "通知和操作"，之后可以对全局通知以及应用通知等进行操作。

在 Mac 上更改 通知 设置

在 Mac 上，使用 "通知" 设置来指定不想被通知打扰的时段，并控制通知在 "通知中心" 中的显示方式。若要更改这些设置，请选取 "苹果"菜单 > "系统设置"，然后点按边栏中的 "通知"（你可能需要向下滚动）。

FAQ

已经获取了当前来源 origin 显示系统通知的权限，onShow 回调也触发了，为何还是无法展示推送的通知？

Notification 为系统通知，需要确保设备开启了对应浏览器应用的通知权限。