From 41a0bc954ec368fed341f7a4b33bb30378da5578 Mon Sep 17 00:00:00 2001
From: Carl Chen <ccheartszzz@gmail.com>
Date: Fri, 1 May 2026 23:43:47 +0800
Subject: [PATCH] docs(notification): improve system notification docs

---
 .../notification/demo/close-tag.vue           | 49 +++++++---
 .../components/notification/demo/duration.vue | 41 +++++++--
 .../components/notification/demo/hooks.vue    | 92 ++++++++++++-------
 .../notification/demo/static-method.vue       | 59 ++++++++----
 .../components/notification/index.en-US.md    | 34 ++++++-
 .../components/notification/index.zh-CN.md    | 35 ++++++-
 6 files changed, 226 insertions(+), 84 deletions(-)

diff --git a/packages/docs/src/pages/components/notification/demo/close-tag.vue b/packages/docs/src/pages/components/notification/demo/close-tag.vue
index c65943d..1672072 100644
--- a/packages/docs/src/pages/components/notification/demo/close-tag.vue
+++ b/packages/docs/src/pages/components/notification/demo/close-tag.vue
@@ -2,9 +2,12 @@
 import { Notification as notification } from "@antdv-next/x";
 
 const describeInfo: Record<NotificationPermission, string> = {
-  denied: "通知权限已被拒绝，你需要在浏览器网站设置中手动重置通知权限。",
-  granted: "通知权限已授予，你可以点击「发送通知」按钮来推送一条通知。",
-  default: "请先请求权限，授权后即可推送通知。",
+  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 }] =
@@ -12,46 +15,64 @@ const [{ permission }, { open, close, requestPermission }] =
 
 const openClick = () => {
   open({
-    title: "任务完成",
-    body: "任务于 13:12 完成",
+    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, closeFn) => {
-      console.log("onClick", event, closeFn);
-      closeFn?.();
+    icon: "https://x.antdv-next.com/x.svg",
+    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);
+    },
   });
 };
 </script>
 
 <template>
   <a-flex vertical gap="middle">
-    <span>{{ describeInfo[permission] }}</span>
+    {{ describeInfo[permission] }}
     <a-flex gap="middle">
       <a-button
         type="primary"
         :disabled="permission !== 'default'"
-        @click="requestPermission()"
+        @click="requestPermission"
       >
-        {{ permission === "default" ? "请求权限" : `通知权限：${permission}` }}
+        {{
+          permission === "default"
+            ? "Please Request Permission"
+            : `Notification permission has been ${permission}`
+        }}
       </a-button>
       <a-button
         type="primary"
         :disabled="permission !== 'granted'"
         @click="openClick"
       >
-        发送通知
+        Open a notification
       </a-button>
       <a-button
         danger
         :disabled="permission !== 'granted'"
         @click="close(['tag_task_completed'])"
       >
-        按 Tag 关闭
+        Destroy tag
       </a-button>
     </a-flex>
   </a-flex>
 </template>
+
+<docs lang="zh-CN">
+关闭指定`tag`通知框。
+</docs>
+
+<docs lang="en-US">
+Close the specified `tag` notification box.
+</docs>
diff --git a/packages/docs/src/pages/components/notification/demo/duration.vue b/packages/docs/src/pages/components/notification/demo/duration.vue
index 2471f05..798b73b 100644
--- a/packages/docs/src/pages/components/notification/demo/duration.vue
+++ b/packages/docs/src/pages/components/notification/demo/duration.vue
@@ -2,9 +2,12 @@
 import { Notification as notification } from "@antdv-next/x";
 
 const describeInfo: Record<NotificationPermission, string> = {
-  denied: "通知权限已被拒绝，你需要在浏览器网站设置中手动重置通知权限。",
-  granted: "通知权限已授予，你可以点击「发送通知」按钮来推送一条通知。",
-  default: "请先请求权限，授权后即可推送通知。",
+  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 }] =
@@ -12,10 +15,10 @@ const [{ permission }, { open, requestPermission }] =
 
 const openClick = () => {
   open({
-    title: "任务完成",
-    body: "任务于 13:12 完成（4.5 秒后自动关闭）",
+    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",
+    icon: "https://x.antdv-next.com/x.svg",
     onClick: (event, close) => {
       console.log("onClick", event, close);
       close?.();
@@ -23,28 +26,46 @@ const openClick = () => {
     onClose: event => {
       console.log("onClose", event);
     },
+    onError: event => {
+      console.log("onError", event);
+    },
+    onShow: event => {
+      console.log("onShow", event);
+    },
   });
 };
 </script>
 
 <template>
   <a-flex vertical gap="middle">
-    <span>{{ describeInfo[permission] }}</span>
+    {{ describeInfo[permission] }}
     <a-flex gap="middle">
       <a-button
         type="primary"
         :disabled="permission !== 'default'"
-        @click="requestPermission()"
+        @click="requestPermission"
       >
-        {{ permission === "default" ? "请求权限" : `通知权限：${permission}` }}
+        {{
+          permission === "default"
+            ? "Please Request Permission"
+            : `Notification permission has been ${permission}`
+        }}
       </a-button>
       <a-button
         type="primary"
         :disabled="permission !== 'granted'"
         @click="openClick"
       >
-        发送通知（自动关闭）
+        Open a notification
       </a-button>
     </a-flex>
   </a-flex>
 </template>
+
+<docs lang="zh-CN">
+使用`duration`设置通知框自动关闭的延时。
+</docs>
+
+<docs lang="en-US">
+Use 'duration' to set the delay for the notification box to automatically close.
+</docs>
diff --git a/packages/docs/src/pages/components/notification/demo/hooks.vue b/packages/docs/src/pages/components/notification/demo/hooks.vue
index b868367..838f379 100644
--- a/packages/docs/src/pages/components/notification/demo/hooks.vue
+++ b/packages/docs/src/pages/components/notification/demo/hooks.vue
@@ -1,58 +1,88 @@
 <script setup lang="ts">
-import type { XNotificationOpenArgs } from "@antdv-next/x";
-
 import { Notification as notification } from "@antdv-next/x";
+import { onMounted, ref } from "vue";
 
 const describeInfo: Record<NotificationPermission, string> = {
-  denied: "通知权限已被拒绝，你需要在浏览器网站设置中手动重置通知权限。",
-  granted: "通知权限已授予，你可以点击「发送通知」按钮来推送一条通知。",
-  default: "请先请求权限，授权后即可推送通知。",
+  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>();
+
+const open = () => {
+  notification.open({
+    title: "Task completed",
+    body: "The task was completed at 13:12",
+    badge: "https://x.antdv-next.com/x.svg",
+    icon: "https://x.antdv-next.com/x.svg",
+    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 openData: XNotificationOpenArgs = {
-  title: "任务完成",
-  body: "任务于 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 close = () => {
+  notification.close();
 };
 
-const [{ permission }, { open, requestPermission, close }] =
-  notification.useNotification();
+const request = async () => {
+  permission.value = await notification.requestPermission();
+};
+
+onMounted(() => {
+  permission.value = notification.permission;
+});
 </script>
 
 <template>
   <a-flex vertical gap="middle">
-    <span>{{ describeInfo[permission] }}</span>
+    <template v-if="permission">
+      {{ describeInfo[permission] }}
+    </template>
     <a-flex gap="middle">
       <a-button
         type="primary"
         :disabled="permission !== 'default'"
-        @click="requestPermission()"
+        @click="request"
       >
-        {{ permission === "default" ? "请求权限" : `通知权限：${permission}` }}
+        {{
+          permission === "default"
+            ? "Please Request Permission"
+            : `Notification permission has been ${permission}`
+        }}
       </a-button>
       <a-button
         type="primary"
         :disabled="permission !== 'granted'"
-        @click="open(openData)"
+        @click="open"
       >
-        发送通知
+        Open a notification
       </a-button>
-      <a-button danger :disabled="permission !== 'granted'" @click="close()">
-        关闭所有
+      <a-button danger :disabled="permission !== 'granted'" @click="close">
+        Destroy All
       </a-button>
     </a-flex>
   </a-flex>
 </template>
+
+<docs lang="zh-CN">
+hooks调用。发送通知前需要向用户请求通知权限，授权可通知后可发送通知， 若授权禁止通知则不可以发送通知。
+</docs>
+
+<docs lang="en-US">
+hooks call.Before sending notifications, it is necessary to request notification permission from the user. Once authorized, notifications can be sent. If authorization prohibits notifications, notifications cannot be sent.
+</docs>
diff --git a/packages/docs/src/pages/components/notification/demo/static-method.vue b/packages/docs/src/pages/components/notification/demo/static-method.vue
index 699f805..1239ac9 100644
--- a/packages/docs/src/pages/components/notification/demo/static-method.vue
+++ b/packages/docs/src/pages/components/notification/demo/static-method.vue
@@ -1,25 +1,24 @@
 <script setup lang="ts">
 import { Notification as notification } from "@antdv-next/x";
+import { onMounted, ref } from "vue";
 
 const describeInfo: Record<NotificationPermission, string> = {
-  denied: "通知权限已被拒绝，你需要在浏览器网站设置中手动重置通知权限。",
-  granted: "通知权限已授予，你可以点击「发送通知」按钮来推送一条通知。",
-  default: "请先请求权限，授权后即可推送通知。",
+  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.",
 };
 
-// 静态方法：不使用 useNotification()，直接调用实例方法
-// permission 仍通过 useNotification 获取响应式状态
-const [{ permission }] = notification.useNotification();
-
-const request = async () => {
-  await notification.requestPermission();
-};
+const permission = ref<NotificationPermission>();
 
 const open = () => {
   notification.open({
-    title: "任务完成",
-    body: "任务于 13:12 完成",
-    icon: "https://mdn.alipayobjects.com/huamei_iwk9zp/afts/img/A*eco6RrQhxbMAAAAAAAAAAAAADgCCAQ/original",
+    title: "Task completed",
+    body: "The task was completed at 13:12",
+    badge: "https://x.antdv-next.com/x.svg",
+    icon: "https://x.antdv-next.com/x.svg",
     onClick: (event, close) => {
       console.log("onClick", event, close);
       close?.();
@@ -36,32 +35,54 @@ const open = () => {
   });
 };
 
-const closeAll = () => {
+const close = () => {
   notification.close();
 };
+
+const request = async () => {
+  permission.value = await notification.requestPermission();
+};
+
+onMounted(() => {
+  permission.value = notification.permission;
+});
 </script>
 
 <template>
   <a-flex vertical gap="middle">
-    <span>{{ describeInfo[permission] }}</span>
+    <template v-if="permission">
+      {{ describeInfo[permission] }}
+    </template>
     <a-flex gap="middle">
       <a-button
         type="primary"
         :disabled="permission !== 'default'"
         @click="request"
       >
-        {{ permission === "default" ? "请求权限" : `通知权限：${permission}` }}
+        {{
+          permission === "default"
+            ? "Please Request Permission"
+            : `Notification permission has been ${permission}`
+        }}
       </a-button>
       <a-button
         type="primary"
         :disabled="permission !== 'granted'"
         @click="open"
       >
-        发送通知
+        Open a notification
       </a-button>
-      <a-button danger :disabled="permission !== 'granted'" @click="closeAll">
-        关闭所有
+      <a-button danger :disabled="permission !== 'granted'" @click="close">
+        Destroy All
       </a-button>
     </a-flex>
   </a-flex>
 </template>
+
+<docs lang="zh-CN">
+静态方法调用。发送通知前需要向用户请求通知权限，授权可通知后可发送通知， 若授权禁止通知则不可以发送通知。
+</docs>
+
+<docs lang="en-US">
+Static method invocation.Before sending notifications, it is necessary to request notification permission from the user. Once authorized, notifications can be sent. If authorization prohibits notifications, notifications cannot be sent.
+</docs>
diff --git a/packages/docs/src/pages/components/notification/index.en-US.md b/packages/docs/src/pages/components/notification/index.en-US.md
index 06e4e20..6c6835e 100644
--- a/packages/docs/src/pages/components/notification/index.en-US.md
+++ b/packages/docs/src/pages/components/notification/index.en-US.md
@@ -1,19 +1,27 @@
 ---
 title: Notification
 subtitle: System Notification
-description: A wrapper around the browser's native Notification API for pushing system-level notifications.
+description: Send system-level notifications that are displayed outside the page.
 ---
 
 ## When To Use
 
-Use when you need to push browser system notifications in AI scenarios, such as task completion or error alerts.
+- When the agent is performing complex tasks, system-level application notifications can be pushed to keep users informed of the task progress.
+- Controlled by the operating system's notification permissions, it is only used for weak notifications.
+
+## Note
+
+- **`Notification` is a system application notification and is controlled by the operating system's notification permissions. If the system notification permission is turned off, the `open` method call of XNotification will have no effect. [System Permission Settings](#system-permission-settings).**
+- XNotification is implemented by extending `window.Notification`. If the browser environment does not support Notification, the method calls of XNotification will have no effect.
+- The style and effect of XNotification notifications are subject to the current browser environment's support for Notification. For example, the `dir` attribute will be ignored by most browsers.
+- XNotification only manages the closing of notifications under the current instance. After the instance changes (for example, the browser page is refreshed), it has no ability to manage and close the sent notifications.
 
 ## Examples
 
-<demo src="./demo/hooks.vue">Hooks Usage</demo>
+<demo src="./demo/hooks.vue">Hooks Call</demo>
+<demo src="./demo/duration.vue">Auto Close Delay</demo>
+<demo src="./demo/close-tag.vue">Close Specified Notification</demo>
 <demo src="./demo/static-method.vue">Static Method</demo>
-<demo src="./demo/duration.vue">Auto Close</demo>
-<demo src="./demo/close-tag.vue">Close by Tag</demo>
 
 ## API
 
@@ -54,3 +62,19 @@ type UseNotificationType = [
   },
 ];
 ```
+
+## System Permission Settings
+
+### Change `Notification` settings on Windows
+
+The setting path for different versions of the Windows system will be different. You can refer to the approximate path: "Start" menu > "Settings" > "System" > and then select "Notifications & actions" on the left, after which you can operate on global notifications and application notifications.
+
+### Change `Notification` settings on Mac
+
+On a Mac, use the "Notifications" settings to specify the period during which you do not want to be disturbed by notifications, and control how notifications are displayed in the "Notification Center". To change these settings, choose "Apple" menu > "System Settings", then click "Notifications" in the sidebar (you may need to scroll down).
+
+## FAQ
+
+### I have obtained the permission for the current `origin` to display system notifications, and the `onShow` callback has also been triggered. Why can't the pushed notification be displayed?
+
+`Notification` is a system-level feature. Please ensure that notifications are enabled for the browser application on your device.
diff --git a/packages/docs/src/pages/components/notification/index.zh-CN.md b/packages/docs/src/pages/components/notification/index.zh-CN.md
index 3e0b091..6541326 100644
--- a/packages/docs/src/pages/components/notification/index.zh-CN.md
+++ b/packages/docs/src/pages/components/notification/index.zh-CN.md
@@ -1,19 +1,28 @@
 ---
 title: Notification
 subtitle: 系统通知
-description: 封装浏览器原生 Notification API，用于向用户推送系统级通知。
+description: 系统级别发送在页面外部显示的通知。
 ---
 
 ## 何时使用
 
-需要在 AI 场景中（如任务完成、异常告警等）推送浏览器系统通知时使用。
+- 在智能体执行复杂任务时，可推送系统应用级别通知，使用户随时掌握任务进展。
+- 受操作系统通知权限管控，仅用于弱通知使用。
+
+## 注意
+
+- **`Notification`为系统应用通知，受操作系统通知权限管控，如果系统通知权限被关闭，XNotification的 `open` 方法调用将无任何效果。[系统权限设置](#系统权限设置)。**
+- XNotification 是由扩展 `window.Notification`实现的，如果浏览器环境不支持Notification，XNotification的方法调用将无任何效果。
+
+- XNotification 通知样式与效果均已当前浏览器环境对Notification的支持为准，例如`dir`属性会被大部分浏览器忽略。
+- XNotification 仅对当前实例下的通知进行关闭管理，实例变更后（例：浏览器页面刷新）对已发送的通知无管理关闭能力。
 
 ## 代码演示
 
-<demo src="./demo/hooks.vue">Hooks 用法</demo>
+<demo src="./demo/hooks.vue">Hooks调用</demo>
+<demo src="./demo/duration.vue">自动关闭延迟</demo>
+<demo src="./demo/close-tag.vue">关闭指定通知</demo>
 <demo src="./demo/static-method.vue">静态方法</demo>
-<demo src="./demo/duration.vue">自动关闭</demo>
-<demo src="./demo/close-tag.vue">按 Tag 关闭</demo>
 
 ## API
 
@@ -54,3 +63,19 @@ type UseNotificationType = [
   },
 ];
 ```
+
+## 系统权限设置
+
+### 在 Windows 上更改 `通知` 设置
+
+在 Windows 系统上不同版本系统的设置路径会有不同，可大概参考路径：“开始”菜单 > “设置”> “系统” > 然后在左侧选择 “通知和操作”，之后可以对全局通知以及应用通知等进行操作。
+
+### 在 Mac 上更改 `通知` 设置
+
+在 Mac 上，使用 ”通知“ 设置来指定不想被通知打扰的时段，并控制通知在 ”通知中心“ 中的显示方式。若要更改这些设置，请选取 ”苹果“菜单> ”系统设置“，然后点按边栏中的 ”通知”（你可能需要向下滚动）。
+
+## FAQ
+
+### 已经获取了当前来源 `origin` 显示系统通知的权限，`onShow` 回调也触发了，为何还是无法展示推送的通知？
+
+`Notification` 为系统通知，需要确保设备开启了对应浏览器应用的通知权限。