FxNotification 通知

悬浮出现在页面角落（默认右上角），用于主动推送较重要的通知。不依赖任何 UI 框架，样式统一走 @fx/styles token，图标走 @fx-core/icon。

基础用法

title 设置标题，message 设置内容（可为字符串 / VNode / 返回 VNode 的函数），duration 控制自动关闭时长（默认 4500ms，设 0 不自动关）。

<template>
  <div class="flex flex-wrap gap-3">
    <FxBtn class="!ml-0" plain @click="open1">自动关闭</FxBtn>
    <FxBtn class="!ml-0" plain @click="open2">不自动关闭</FxBtn>
  </div>
</template>

<script setup lang="ts">
import { h } from "vue"
import { fxNotification } from "@fx/components"

const open1 = () => {
  fxNotification({
    title: "提示",
    message: h("i", { style: "color: teal" }, "这是一条提醒消息"),
  })
}

const open2 = () => {
  fxNotification({
    title: "提示",
    message: "这条消息不会自动关闭",
    duration: 0,
  })
}
</script>

不同类型

fxNotification.primary / .success / .warning / .info / .error 快捷方法，自动带对应类型图标与配色。

<template>
  <div class="flex flex-wrap gap-3">
    <FxBtn class="!ml-0" plain @click="open5">Primary</FxBtn>
    <FxBtn class="!ml-0" plain @click="open1">Success</FxBtn>
    <FxBtn class="!ml-0" plain @click="open2">Warning</FxBtn>
    <FxBtn class="!ml-0" plain @click="open3">Info</FxBtn>
    <FxBtn class="!ml-0" plain @click="open4">Error</FxBtn>
  </div>
</template>

<script setup lang="ts">
import { fxNotification } from "@fx/components"

const open1 = () => {
  fxNotification({
    title: "Success",
    message: "这是一条成功消息",
    type: "success",
  })
}

const open2 = () => {
  fxNotification({
    title: "Warning",
    message: "这是一条警告消息",
    type: "warning",
  })
}

const open3 = () => {
  fxNotification({
    title: "Info",
    message: "这是一条信息消息",
    type: "info",
  })
}

const open4 = () => {
  fxNotification({
    title: "Error",
    message: "这是一条错误消息",
    type: "error",
  })
}

const open5 = () => {
  fxNotification({
    title: "Primary",
    message: "这是一条主要消息",
    type: "primary",
  })
}
</script>

出现位置

position 控制：top-right（默认）/ top-left / bottom-right / bottom-left。

<template>
  <div class="flex flex-wrap gap-3">
    <FxBtn class="!ml-0" plain @click="open1">右上</FxBtn>
    <FxBtn class="!ml-0" plain @click="open2">右下</FxBtn>
    <FxBtn class="!ml-0" plain @click="open3">左下</FxBtn>
    <FxBtn class="!ml-0" plain @click="open4">左上</FxBtn>
  </div>
</template>

<script setup lang="ts">
import { fxNotification } from "@fx/components"

const open1 = () => {
  fxNotification({
    title: "自定义位置",
    message: "我在右上角",
  })
}

const open2 = () => {
  fxNotification({
    title: "自定义位置",
    message: "我在右下角",
    position: "bottom-right",
  })
}

const open3 = () => {
  fxNotification({
    title: "自定义位置",
    message: "我在左下角",
    position: "bottom-left",
  })
}

const open4 = () => {
  fxNotification({
    title: "自定义位置",
    message: "我在左上角",
    position: "top-left",
  })
}
</script>

带偏移

offset 控制距边缘的额外偏移（同一方位的多条会自动堆叠，间距 16px）。

<template>
  <FxBtn plain @click="open">带偏移的通知</FxBtn>
</template>

<script setup lang="ts">
import { fxNotification } from "@fx/components"

const open = () => {
  fxNotification.success({
    title: "Success",
    message: "这是一条带偏移的成功消息",
    offset: 100,
  })
}
</script>

不自动关闭

duration 设为 0 时不自动关闭，需手动关闭。

<template>
  <FxBtn plain @click="open">不自动关闭</FxBtn>
</template>

<script setup lang="ts">
import { fxNotification } from "@fx/components"

const open = () => {
  fxNotification({
    title: "提示",
    message: "duration 设为 0 不自动关闭，需手动点击关闭按钮",
    duration: 0,
  })
}
</script>

隐藏关闭按钮

showClose 设为 false 隐藏右上角关闭按钮。

<template>
  <FxBtn plain @click="open">隐藏关闭按钮</FxBtn>
</template>

<script setup lang="ts">
import { fxNotification } from "@fx/components"

const open = () => {
  fxNotification.success({
    title: "Info",
    message: "这是一条没有关闭按钮的消息",
    showClose: false,
  })
}
</script>

使用 HTML 内容

dangerouslyUseHTMLString 使 message 作为 HTML 渲染（注意 XSS 风险，message 内容应是可信的，切勿直接渲染用户输入）。

<template>
  <FxBtn plain @click="open">使用 HTML 内容</FxBtn>
</template>

<script setup lang="ts">
import { fxNotification } from "@fx/components"

const open = () => {
  fxNotification({
    title: "HTML 内容",
    dangerouslyUseHTMLString: true,
    message: "<strong>这是 <i>HTML</i> 字符串</strong>",
  })
}
</script>

使用 VNode 内容

message 可直接传 VNode，或传一个返回 VNode 的函数（含动态 props 时必须用函数形式）。

<template>
  <div class="flex flex-wrap gap-3">
    <FxBtn class="!ml-0" plain @click="open">普通 VNode</FxBtn>
    <FxBtn class="!ml-0" plain @click="open1">动态 props</FxBtn>
  </div>
</template>

<script setup lang="ts">
import { h, ref } from "vue"
import { fxNotification } from "@fx/components"

const open = () => {
  fxNotification({
    title: "VNode 内容",
    message: h("p", null, [
      h("span", null, "message 可以是 "),
      h("i", { style: "color: teal" }, "VNode"),
    ]),
  })
}

const open1 = () => {
  const checked = ref<boolean | string | number>(false)
  fxNotification({
    title: "VNode 内容",
    // VNode 含动态 props 时必须传函数
    message: () =>
      h("input", {
        type: "checkbox",
        checked: checked.value === true,
        style: "margin-right: 6px",
        onChange: (e: Event) => {
          checked.value = (e.target as HTMLInputElement).checked
        },
      }),
    duration: 0,
  })
}
</script>

局部引入

import { fxNotification } from "@fx/components"

fxNotification(options)
fxNotification.primary(options)
fxNotification.success(options)
fxNotification.warning(options)
fxNotification.info(options)
fxNotification.error(options)

// 关闭所有
fxNotification.closeAll()

// 单个实例关闭
const handle = fxNotification({ message: "hi" })
handle.close()

API

Options

名称	说明	类型	默认值
title	标题	string	—
message	内容	string | VNode | (() => VNode)	—
type	类型	'primary' | 'success' | 'info' | 'warning' | 'error'	—
icon	自定义图标名（被 type 覆盖）	string（IconString，如 ep:bell）	—
closeIcon	自定义关闭图标名	string（IconString）	ep:close
duration	自动关闭时长 ms（0 不自动关）	number	4500
position	出现位置	'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'	top-right
offset	距边缘偏移	number	0
showClose	是否显示关闭按钮	boolean	true
dangerouslyUseHTMLString	message 是否作为 HTML 渲染	boolean	false
customClass	自定义类名（追加到根节点）	string	—
customStyle	自定义样式（合并到根节点 style）	CSSProperties	—
zIndex	自定义层级（不传则自动递增）	number	—
onClick	点击通知时的回调	() => void	—
onClose	关闭时的回调	(vm: VNode) => void	—
appendTo	挂载容器，传非法值回退到 document.body	string | HTMLElement	body

fxNotification.success(...) 等快捷方法等同于 fxNotification({ ...options, type: 'success' })，也支持直接传字符串或 VNode 作为 message。

Slots

名称	说明	参数
default	自定义内容区，覆盖 message	—

Events

名称	说明	回调参数
destroy	通知完全离场（动画结束后）触发，内部用于清理 DOM	—

Methods

名称	说明
fxNotification.closeAll()	关闭所有方位的全部通知
fxNotification.updateOffsets(position?)	重新计算指定方位（默认 top-right）的堆叠偏移
返回值.close()	关闭单个通知（走完整离场动画生命周期）

Expose（组件实例）

名称	说明
visible	是否可见（Ref<boolean>）
close	关闭当前通知

全局属性

安装插件后可在模板中通过 $fxNotification / $fxNotify 调用。

实现说明

• 命令式挂载：fxNotification 通过 createVNode + render 在运行时创建实例并挂载到 appendTo 指定容器，不依赖任何全局组件注册。message 为函数时作为 children render prop（含动态 props 的 VNode 必须用此形式），为 VNode 时包一层返回函数，否则按字符串 / HTML 渲染。
• 方位分桶堆叠：内部按 4 个方位各自维护实例队列，新实例的纵向偏移 = 已有实例高度累加 + 16px 间距；某条关闭时，其后方的实例自动回收高度并更新 offset，从而平滑上滑/下滑（top/bottom 过渡）。
• 关闭生命周期：返回值的 close() 仅把内部 visible 置为 false，让 <transition> 走完整离场动画，@before-leave 时回收堆叠偏移、调用用户 onClose，@after-leave 触发 destroy 清理 DOM，避免内存泄漏。
• 图标方案（fx）：类型图标与关闭图标统一用 @fx-core/icon（FxIcon，图标名为 IconString，如 ep:success-filled），类型配色通过 --color-* token 注入；type 与 icon 同时存在时 type 优先。
• 样式取值（fx）：宽 / 内边距 / 圆角 / 阴影 / 边框 / 字号 / 字重等规格均与设计基准一致，圆角走 --radius-lg、阴影走 --shadow-popup、边框走 --color-border、字重走 --fw-bold，不引用任何第三方 UI 库 CSS 变量。
• 层级管理（fx 增强）：未传 zIndex 时自动从全局 nextZIndex() 取值并递增，避免多实例层级错乱。
• 键盘交互：监听 delete / backspace 暂停计时，esc 关闭当前通知，其余按键恢复自动关闭计时。