@mm-custom/notify

目录

• 概述
• 安装与引入
• 配置接口
• 效果类型
• 实例方法
• 使用实例
• 浏览器通知使用实例

概述

通知库，提供网页标题动画、favicon 状态指示、音频提醒和浏览器通知等功能。

安装与引入

// ES6 模块引入
import Notify from '@mm-custom/notify';

// 或者使用单例模式
import { createNotify } from '@mm-custom/notify';

// 全局变量方式（如果通过 script 标签引入）
// const Notify = window.Notify;

配置接口

NotifyConfig

主配置接口，用于初始化通知实例。

| 属性 | 类型 | 默认值 | 描述 | |--------------------|-----------------------------------------|------------------|-----------------| | interval | number | 100 | 效果动画间隔时间（毫秒） | | effect | 'flash' \| 'scroll' \| 'bounce' | 'flash' | 标题动画效果类型 | | title | string | document.title | 页面原始标题 | | message | string | title | 显示的消息内容 | | onclick | (notification?: Notification) => void | undefined | 通知点击回调函数 | | openurl | string | undefined | 点击通知时打开的 URL | | disableFavicon | boolean | false | 是否禁用 favicon 功能 | | updateFavicon | FaviconConfig | 见下文 | favicon 配置 | | audio | AudioConfig | undefined | 音频配置 | | notification | NotificationOptions | 见下文 | 浏览器通知配置 | | icon | string | undefined | 通知图标 URL | | maxNotifications | number | 3 | 最大同时显示的通知数量 |

FaviconConfig

Favicon 配置接口。

| 属性 | 类型 | 默认值 | 描述 | |-------------------|--------------------|-------------|---------------| | id | string | 'favicon' | favicon 元素 ID | | textColor | string | '#fff' | 文字颜色 | | backgroundColor | string | '#057b5e' | 背景颜色 | | num | string \| number | undefined | 显示的内容 |

AudioConfig

音频配置接口。

| 属性 | 类型 | 默认值 | 描述 | |----------|----------------------|---------|-------------------| | file | string \| string[] | - | 音频文件 URL 或 URL 数组 | | loop | boolean | false | 是否循环播放 | | volume | number | 1 | 音量（0-1） |

NotifyOptions

浏览器通知配置接口。

| 属性 | 类型 | 默认值 | 描述 | |----------------------|-----------------------------------------|------------------|------------------------------------| | badge | string | '' | 包含图像 URL 的字符串，用于在没有足够空间显示通知本身时表示通知 | | body | string | 'new message.' | 通知正文 | | data | any | null | 任意你想要与通知关联的数据 | | dir | 'auto' \| 'ltr' \| 'rtl' | 'auto' | 文字方向 | | icon | string | favicon URL | 通知图标 | | lang | string | '' | 通的语言 | | requireInteraction | boolean | false | 通知保活状态 | | silent | boolean \| null | null | 通知是否静音 | | tag | string | '' | 通知识别标签 | | title | string | mm-notify!' | 通知标题 | | openurl | string | '' | 点击打开的 URL | | onshow | (notification: Notification) => void | undefined | 显示时回调 | | onclose | (notification: Notification) => void | undefined | 关闭时回调 | | onerror | (notification: Notification) => void | undefined | 错误时回调 | | onclick | (notification?: Notification) => void | undefined | 点击时回调 | | autoClose | number | undefined | 通知自动关闭时间（毫秒） |

效果类型

• flash (闪烁)：在原始标题和消息之间快速切换
• scroll (滚动)：消息文字水平滚动显示
• bounce (弹跳)：基于时间交替显示两个标题

实例方法

所有方法都支持链式调用，返回当前实例（除非另有说明）。

核心方法

| 方法 | 参数 | 返回值 | 描述 | |-------------------|---------------------|--------|-------------| | init(config) | NotifyConfig | this | 初始化或重新配置实例 | | setTitle(title) | string \| boolean | this | 设置标题消息或启用效果 | | render() | - | this | 手动触发效果渲染 | | addTimer() | - | this | 启动效果定时器 | | clearTimer() | - | this | 清除效果定时器 |

音频控制

| 方法 | 参数 | 返回值 | 描述 | |---------------|----------------------|--------|------------| | setURL(url) | string \| string[] | this | 设置音频文件 URL | | player() | - | this | 播放音频 | | stopPlay() | - | this | 停止音频播放 | | loopPlay() | - | this | 循环播放音频 |

通知管理

| 方法 | 参数 | 返回值 | 描述 | |-------------------------|--------------------------------|-----------------------------------|----------| | notify(config?) | Partial<NotificationOptions> | this | 显示浏览器通知 | | close() | - | void | 关闭当前通知 | | closeAll() | - | this | 关闭所有活动通知 | | isPermissionGranted() | - | boolean | 检查通知权限 | | requestPermission() | - | Promise<NotificationPermission> | 请求通知权限 |

Favicon 控制

| 方法 | 参数 | 返回值 | 描述 | |------------------------------------|--------------------|--------|-----------------| | setFavicon(content) | string \| number | this | 设置 favicon 显示内容 | | setFaviconColor(color) | string | this | 设置 favicon 文字颜色 | | setFaviconBackgroundColor(color) | string | this | 设置 favicon 背景颜色 | | faviconClear() | - | this | 恢复原始 favicon |

状态管理

| 方法 | 参数 | 返回值 | 描述 | |--------------|----|----------|----------| | getState() | - | object | 获取当前实例状态 | | reset() | - | this | 重置到初始状态 | | destroy() | - | void | 完全销毁实例 |

使用实例

基础使用

import Notify from '@mm-custom/notify';

// 创建实例
const notify = new Notify({
  effect: 'flash',
  message: '您有新消息!',
  interval: 500
});

// 启动标题闪烁效果
notify.setTitle(true);

// 5秒后停止效果
setTimeout(() => {
  notify.clearTimer();
}, 5000);

单例模式使用

import { createNotify } from '@mm-custom/notify';

// 获取全局单例（推荐在应用中使用）
const globalNotify = createNotify({
  effect: 'scroll',
  message: '全局通知'
});

// 在任何地方使用同一个实例
function showNewMessage(message: string) {
  globalNotify
    .setTitle(message)
    .notify({ body: message })
    .player();
}

// 检查权限状态
if (!globalNotify.isPermissionGranted()) {
  globalNotify.requestPermission().then(permission => {
    console.log('通知权限:', permission);
  });
}

浏览器通知使用实例

以下是一个专注于浏览器通知的使用示例，包括权限请求和事件处理：

基础通知示例

import Notify from '@mm-custom/notify';

// 创建通知实例
const notify = new Notify({
  notification: {
    title: '我的网站',
    body: '欢迎访问我们的网站！',
    icon: '/path/to/icon.png'
  }
});

// 简单通知
notify.notify({
  body: '您有一条新消息，请查收！'
});