message.js

message.js - 一个小巧实用的 JavaScript 提示信息工具库。

<script src="https://cdn.jsdelivr.net/gh/yaohaixiao/message.js/message.min.js"></script>
Download Zip

Options

message.js 有者丰富的配置选项，以不同的展示方式展示提示信息。

beforeClose

Description

Type：
Function
Default：
null

可选，用来指定提示信息关闭之前执行的回调函数。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

const message = new Message({
  beforeClose: () => {
    Message.warning({
      message: 'message.js 提示窗口即将关闭'
    })
  },
  message: '可选，beforeClose 用来指定提示信息关闭之前执行的回调函数。'
})

closable

Description

Type：
Boolean
Default：
true

可选，指定是否有关闭按钮；

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

const message = new Message({
  // 提示信息界面没有关闭按钮
  closable: false,
  message: '可选，closable 指定是否有关闭按钮'
})

customClass

Description

Type：
String
Default：
''

可选，如果 message.js 中自带的 UI 样式无法满足开发中的应用场景的要求可以添加 customClass 以扩展修改界面样式。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

const message = new Message({
  // 设置深色样式
  customClass: 'theme-dark',
  message: '可选，如果 message.js 中自带的 UI 样式无法满足开发中的应用场景的要求可以添加 customClass 以扩展修改界面样式。'
})

dangerouslyUseHTMLString

Description

Type：
Boolean
Default：
false

可选，用来显示的提示信息文本是否允许有 HTML 字符串。

默认提示信息应该为普通的文本，在需要显示 HTML 字符的时候配置 dangerouslyUseHTMLString，否则 HTML 字符串将通过 encodeHTML() 方法转义 HTML 字符。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

// 默认将转义 message 中的 HTML 的 < 转义为 &lt;，> 转义为 &gt;
const message = new Message({
  message: '可选，<a href="#beforeClose">beforeClose</a> 用来指定提示信息关闭之前执行的回调函数。'
})

// message 中的 HTML 链接将可以点击
const message = new Message({
  dangerouslyUseHTMLString: true,
  message: '可选，<a href="#beforeClose">beforeClose</a> 用来指定提示信息关闭之前执行的回调函数。'
})

destroyAfterClosed

Description

Type：
Boolean
Default：
true

可选，用来指定提示信息关闭后，是否自动销毁。默认关闭后是自动销毁的。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

const message = new Message({
  // 设置为 false，message 可以反复使用
  destroyAfterClosed: false
  message: '可选，<a href="#beforeClose">beforeClose</a> 用来指定提示信息关闭之前执行的回调函数。'
})

// 调整配置后，再次打开
message.open({
  type: 'success',
  message: '调整配置后，再次打开'
})

delay

Description

Type：
Number
Default：
2

可选，指定鼠标离开提示信息区域后，提示信息延迟关闭的时间（单位：秒）。

提示显示展示期间，用户将鼠标光标放置于提示信息区域时，提示信息将不会自动收起关闭，delay 指定的是鼠标离开提示信息区域后，提示信息延迟关闭的时间。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

const message = new Message({
  // 鼠标离开提示信息区域 4 秒后，将自动关闭
  delay: 4,
  message: '可选，指定鼠标离开提示信息区域后，提示信息延迟关闭的时间（单位：秒）。'
})

duration

Description

Type：
Number
Default：
6

可选，执行提示信息展示的时间（单位：秒），设置 duration: 0，则不会自动关闭。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

const message = new Message({
  // 提示信息区将在 14 秒后自动关闭
  duration: 14,
  message: '可选，执行提示信息展示的时间（单位：秒）。'
})

const message = new Message({
  // 设置 duration: 0，则不会自动关闭
  duration: 0,
  message: '可选，执行提示信息展示的时间（单位：秒）。'
})

effect

Description

Type：
String
Default：
'default'

可选，指定提示信息的 UI 效果类型。

  • default：默认类型，图标深色主题色底色，图标白色；
  • light: 图标没有底色，图标都有圆圈，图标颜色为主题色；
  • plain：无图标纯文本模式，提示框左边框有主题色，提示框有浅色背景色；
// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

// 不设置 effect，则为默认 default UI 效果
const message = new Message({
  message: '可选，指定提示信息的 UI 效果类型。'
})

// light UI 效果
const message = new Message({
  effect: 'light',
  type: 'success',
  message: '可选，指定提示信息的 UI 效果类型。'
})

// plain UI 效果
const message = new Message({
  effect: 'plain',
  type: 'warning',
  message: '可选，指定提示信息的 UI 效果类型。'
})

id

Description

Type：
String
Default：
''

可选，指定 Message 对象实例的 id 值，可以通过 Message.close(id) 静态方法手动关闭提示信息。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

const message = new Message({
  id: 'info-message-001',
  message: '可选，指定 Message 对象实例的 id 值，可以通过 Message.close(id) 静态方法手动关闭提示信息。'
})

message

Description

Type：
String
Default：
''

可选，提示信息文本字符串。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

// 默认将转义 message 中的 HTML 的 < 转义为 &lt;，> 转义为 &gt;
const message = new Message({
  message: '可选，<a href="#beforeClose">beforeClose</a> 用来指定提示信息关闭之前执行的回调函数。'
})

// message 中的 HTML 链接将可以点击
const message = new Message({
  dangerouslyUseHTMLString: true,
  message: '可选，<a href="#beforeClose">beforeClose</a> 用来指定提示信息关闭之前执行的回调函数。'
})

offset

Description

Type：
Number
Default：
30

可选，用来指定提示信息距离窗口顶部的 top 数值，单位：px。

说明：如果使用 Message.info()、Message.success()、Message.warning() 和 Message.error() 4 个静态方法配置 offset 值，message.js 会自动定位多个提示框的 offset 值。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

// 不设置则为默认：30
const message = new Message({
  id: 'info-message-001',
  message: '可选，用来指定提示信息距离窗口顶部的 top 数值。'
})

const message = new Message({
  id: 'info-message-002',
  offset: 40,
  message: '可选，用来指定提示信息距离窗口顶部的 top 数值。'
})

round

Description

Type：
Boolean
Default：
false

可选，用来指定提示框是的边角是否以圆形展示。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

// default UI 效果，并且是圆形边框
const message = new Message({
  round: true,
  message: '可选，指定提示信息的 UI 效果类型。'
})

// light UI 效果，并且是圆形边框
const message = new Message({
  effect: 'light',
  round: true,
  type: 'success',
  message: '可选，指定提示信息的 UI 效果类型。'
})

// plain UI 效果，并且是圆形边框
const message = new Message({
  effect: 'plain',
  round: true,
  type: 'warning',
  message: '可选，指定提示信息的 UI 效果类型。'
})

type

Description

Type：
String
Default：
'info'

可选，指定提示信息的类型，message.js 有 4 中类型提示：

  • info：普通提示信息；
  • success：成功提示信息；
  • warning：警告提示信息；
  • error：错误提示信息；

另外，message.js 还提供了 Message.info()、Message.success()、Message.warning() 和 Message.error() 4 个静态方法，以对应的类型显示提示信息。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

// default UI 效果，普通提示信息
const message = new Message({
  round: true,
  message: '可选，指定提示信息的 UI 效果类型。'
})

// light UI 效果，成功提示信息
const message = new Message({
  effect: 'light',
  round: true,
  type: 'success',
  message: '可选，指定提示信息的 UI 效果类型。'
})

// light UI 效果，错误提示信息
const message = new Message({
  effect: 'light',
  round: true,
  type: 'error',
  message: '可选，指定提示信息的 UI 效果类型。'
})

// plain UI 效果，警告提示信息
const message = new Message({
  effect: 'plain',
  round: true,
  type: 'warning',
  message: '可选，指定提示信息的 UI 效果类型。'
})

visible

Description

Type：
Boolean
Default：
true

可选，指定提示信息创建后是否可见，即是否立即显示。如果设置 false，则需要手动调用 open() 方法显示。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

// 默认自动显示
const message = new Message({
  round: true,
  message: '可选，指定提示信息创建后是否可见，即是否立即显示。'
})

// 默认自动显示
const message = new Message({
  round: true,
  visible: false,
  message: '可选，指定提示信息创建后是否可见，即是否立即显示。'
})

// 需要手动调用 open() 方法显示
message.open()

Properties

message.js 对外放 4 个重要的属性：$el、attrs、id 和 offset。另外还提供一个静态属性：DEFAULTS。

$el

Description

Type：
HTMLElement

$el 属性是 message.js 创建的提示信息框最外层的 DOM 元素。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

const message = new Message({
  message: '$el 属性是 message.js 创建的提示信息框最外层的 DOM 元素'
})

console.log(message.$el)
// $el 的完整 DOM 结构
// <div class="mjs-message mjs-message_info mjs-message_default mjs-message_visible" style="top: 30px;">
//   <i class="mjs-icon mjs-message__icon">
//     <svg aria-hidden="true" class="mjs-icon__svg" style="width:16px;height:16px;">
//       <use xlink:href="#mjs-icon-info"></use>
//     </svg>
//   </i>
//   <p class="mjs-message__content">$el 属性是 message.js 创建的提示信息框最外层的 DOM 元素</p>
//   <i class="mjs-icon mjs-message__close">
//     <svg aria-hidden="true" class="mjs-icon__svg" style="width:18px;height:18px;">
//       <use xlink:href="#mjs-icon-close"></use>
//     </svg>
//   </i>
// </div>

attrs

Description

Type：
Object

存储的是 Message 对象当前使用中的配置选项：

说明：建议使用 attr(prop) 方法来获取属性，避免直接调用属性。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

// 设置默认配置项
const message = new Message(Message.DEFAULTS)

// 查看全部配置信息
// 建议实用 message.attr() 方法获取完整的配置信息
message.attrs

id

Description

Type：
String

Message 对象实例的 id 字符串。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

const message = new Message({
  id: 'mjs-message-info'
  message: '$el 属性是 message.js 创建的提示信息框最外层的 DOM 元素'
})

console.log(message.id) // => 'mjs-message-info'

offset

Description

Type：
Number
Default：
30

指定 Message 提示信息距离浏览器窗口顶部部的 top 值。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

const message = new Message({
  id: 'mjs-message-info'
  // 默认值：30
  offset: 50
  message: '$el 属性是 message.js 创建的提示信息框最外层的 DOM 元素'
})

console.log(message.offset) // => 50

Message.DEFAULTS

Description

Type：
Object

静态属性，存储的是 Message 对象默认配置选项：

Message.DEFAULTS = {
  id: '',
  type: 'info',
  effect: 'default',
  round: false,
  offset: 30,
  duration: 6,
  delay: 2,
  message: '',
  customClass: '',
  closable: true,
  visible: true,
  dangerouslyUseHTMLString: false,
  destroyAfterClosed: true,
  beforeClose: null
}

Methods

message.js 的提供了 6 个公共方法和 4 个静态方法：

attr([prop, value])

Description

attr() 方法用来设置或者获取初始化时配置的 attrs 信息的。

Parameters

prop
Type：
String|HTMLElement

（可选）options 中的属性名称或者要配置的 attrs 信息。

value
Type：
Any

（可选）要设置的 prop 属性的值

  • 不传递任何参数：返回完整的 attrs 配置信息；
  • 仅传递 prop：
    • String: 返回 attrs 配型信息中与 prop 对应的值；
    • Object: 用来设置 attrs 配置信息；
  • 同时传递 prop 和 value 参数：设置 attrs 配置信息中的某个属性值；

Returns

Type：
Any

配置信息 attrs 的属性值或者 Message 对象。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

const message = new Message({
   type: 'success',
   duration: 0,
   message: 'attr() 方法用来设置或者获取初始化时配置的 attrs 信息的。'
})

outline.attr('type') // -> 'success'
outline.attr('message', '导入 Message 模块') // -> 设置 message 配置信息的值为 '导入 Message 模块'
outline.attr() // -> 返回完整配置参数 attrs 信息

close()

Description

close() 方法用于手动关闭提示信息。

Returns

Type：
Message

Message 对象，便于链式方法调用。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

const message = new Message({
   type: 'success',
   duration: 0,
   message: 'close() 方法用于手动关闭提示信息。'
})

message.close()

destroy()

Description

destroy() 方法用于移除所有绘制的 DOM 节点，并移除绑定的事件处理器，同时重置所有 attrs 配置信息和重置 property 属性。

Returns

Type：
Message

Message 对象，便于链式方法调用。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

const message = new Message({
  duration: 0,
  message: '可选，执行提示信息展示的时间（单位：秒）。'
})

message.destroy()

isClosed()

Description

isClosed() 方法返回 Message 实例的 closed 属性，用于判断提示是否已关闭。

Returns

Type：
Boolean

是否被关闭。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

const message = new Message({
  duration: 0,
  message: 'isClosed() 方法返回 Message 实例的 closed 属性，用于判断提示是否已关闭。'
})

console.log(message.isClosed()) // -> false
message.close()
console.log(message.isClosed()) // -> true

open([options])

Description

open() 方法用于手动显示提示信息。

Parameters

options
Type：
Object|String
  • Object：请参考 API 文档中 Options 参数的说明；
  • String: message.js 会将参数调整为 { message: options }，直接将参数文本作为 message 输出；

Returns

Type：
Message

Message 对象，便于链式方法调用。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

const message = new Message({
   type: 'success',
   // 不会自动显示
   visible: false,
   duration: 0,
   message: 'open() 方法用于手动显示提示信息。'
})

// 手动显示提示信息。
// 无参数
message.open()

const tip = new Message({
   // 只有 destroyAfterClosed 参数为 false 时，
   // 才能保留 Message 实例创建的 DOM 元素，从而
   // 多次使用 open() 方法显示信息
   destroyAfterClosed: false,
   type: 'success',
   // 不会自动显示
   visible: false,
   duration: 0,
   message: 'open() 方法用于手动显示提示信息。'
})

// String 类型参数
tip.open('String 类型参数')

// Object 类型参数
tip.open({
  // 将显示为普通类型提示信息
  type: 'info',
  message: 'Object 类型参数'
})

reload(options)

Description

reload() 方法是（根据新的配置信息）重启程序方法：

  1. 先移除所有绘制的 DOM 元素和绑定的事件处理器；
  2. 重新初始化程序；

Parameters

options
Type：
Object

（可选）初始化的配置参数。

Returns

Type：
Message

Message 对象，便于链式方法调用。

// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

const message = new Message({
  type: 'success',
  // 不会自动显示
  visible: false,
  duration: 0,
  essage: 'open() 方法用于手动显示提示信息。'
})

message.reload({
  type: 'error',
  // 自动显示
  visible: true,
  duration: 0,
  message: 'reload() 方法是（根据新的配置信息）重启程序方法。'
})

$emit(topic[, data, async = true])

Description

$emit()方法用来发布订阅主题信息。

message.js 默认是采用异步方式发布的。以确保在消费者处理主题时，主题的发起者不会被阻止。 当然 $emit() 方法也支持同步主题发布。

Category：
Core

Parameters

topic
Type：
String

（必须）主题名称。

data
Type：
Object

（可选）消息传递的数据对象。

async
Type：
Boolean
Default：
true

(可选) 是否异步发布。默认值：true。

  • 当 async 设置为 true（默认） 时，异步发布；
  • 当 async 设置为 false 时，同步发布；

Returns

Type：
Message

Message 对象，以便实现链式调用。

const message = new Message({
  message: '$emit()方法用来发布订阅主题信息。'
})

const handler = (msg) => {
  console.log(msg)
}

message.$on('created', handler)
message.$on('mounted', handler)

// 异步发布
message.$emit('mounted') // -> 'ok'

// 同步发布
// 延迟10毫秒：应该看输出 ok 后输出
message.$emit('created')

$on(topic, handler)

Description

$on() 方法用来订阅主题，并给出处理器函数。

Category：
Core

Parameters

topic
Type：
String

（必须）主题名称。

handler
Type：
Function

（（必须）主题的处理器函数。

Returns

Type：
String。

唯一的 token 字符串，例如：'guid-1'。

const message = new Message({
  message: '$off() 用来取消订阅主题。'
})

const handler = function(attrs) {
  // this 上下文指向 outline 实例
  this.attr()
  console.log('attrs: ', attrs)
}

message.$on('created', handler)

// 手动触发 created 事件
message.$emit('created')

$off(topic[, token])

Description

$off() 用来取消订阅主题。

Category：
Core

Parameters

topic
Type：
String

（必须）主题名称。

token
Type：
Function | String

（可选）订阅主题的处理器函数或者唯一 Id 值。

  • 为传递 token 参数：取消指定 topic 的订阅；
  • 传递 token 参数：仅删除 topic 订阅信息中与 token 对应的事件处理器

Returns

Type：
Message

Message 对象，以便实现链式调用。

const message = new Message({
  message: '$off() 用来取消订阅主题。'
})

const handler = (msg) => {
  console.log('handler:', msg)
}

message.$on('created')

// 取消订阅 author 主题
message.$off('created')

// 不会有任何反应，因为已经取消订阅了
message.$emit('created')

Message.info(options)

Description

（静态方法）Message.info() 方法专门用来显示普通类型提示信息。

Parameters

options
Type：
Object|String
  • Object：请参考 API 文档中 Options 参数的说明；
  • String: message.js 会将参数调整为 { message: options }，直接将参数文本作为 message 输出；
// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

// Object 类型参数
Message.info({
  round: true,
  message: 'Message.info() 方法专门用来显示普通类型提示信息。'
})

// String 类型参数
Message.error('Message.info() 方法专门用来显示普通类型提示信息。')

Message.warning(options)

Description

（静态方法）Message.warning() 方法专门用来显示警告类型提示信息。

Parameters

options
Type：
Object|String
  • Object：请参考 API 文档中 Options 参数的说明；
  • String: message.js 会将参数调整为 { message: options }，直接将参数文本作为 message 输出；
// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

// Object 类型参数
Message.warning({
  round: true,
  message: 'Message.warning() 方法专门用来显示警告类型提示信息。'
})

// String 类型参数
Message.warning('Message.warning() 方法专门用来显示警告类型提示信息。')

Message.success(options)

Description

（静态方法）Message.success() 方法专门用来显示成功类型提示信息。

Parameters

options
Type：
Object|String
  • Object：请参考 API 文档中 Options 参数的说明；
  • String: message.js 会将参数调整为 { message: options }，直接将参数文本作为 message 输出；
// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

// Object 类型参数
Message.success({
  round: true,
  message: 'Message.success() 方法专门用来显示成功类型提示信息。'
})

// String 类型参数
Message.success('Message.success() 方法专门用来显示成功类型提示信息。')

Message.error(options)

Description

（静态方法）Message.error() 方法专门用来显示错误类型提示信息。

Parameters

options
Type：
Object|String
  • Object：请参考 API 文档中 Options 参数的说明；
  • String: message.js 会将参数调整为 { message: options }，直接将参数文本作为 message 输出；
// 导入 Message 模块
import Message from '@yaohaixiao/message.js/message'

// Object 类型参数
Message.error({
  round: true,
  message: 'Message.error() 方法专门用来显示错误类型提示信息。'
})

// String 类型参数
Message.error('Message.error() 方法专门用来显示错误类型提示信息。')

Events

message.js 从 0.3.0 开始提供了 9 事件。通过 message.js 在 0.3.0 新添加的 $on() 方法监听。

created

事件名称说明回调参数
createdMessage 实例配置信息初始化完成后触发，此时 DOM 元素还没有绘制。返回实例最终的 attrs 配置属性的（对象）值。

Usage

const message = new Message()

message.$on('created', function(attrs) {
  // this 上下文就是 outline 实例
  // attrs === outline.attr()
})

// 当 message 实例的配置信息初始化完毕，就会触发 created 事件
message.initialize(Message.DEFAULTS)

mounted

事件名称说明回调参数
mountedMessage 实例的所有 DOM 元素绘制完毕后触发。--

Usage

const message = new Message()

message.$on('mounted', function() {
  // do something
})

// 当 message 实例的所有 DOM 绘制完毕，就会触发 mounted 事件
message.initialize(Outline.DEFAULTS)

beforeOpen

事件名称说明回调参数
beforeOpenMessage 实例显示前事件，在调用 Message 对象的实例 open() 方法后会触发。--

Usage

const message = new Message(Message.DEFAULTS)

outline.$on('beforeOpen', function() {
  // this 上下文就是 message 实例
  console.log('this', this)
})

opened

事件名称说明回调参数
openedMessage 实例显示后事件，在调用 Message 对象的实例 open() 方法后会触发。--

Usage

const message = new Message(Message.DEFAULTS)

outline.$on('opened', function() {
  // this 上下文就是 message 实例
  console.log('this', this)
})

beforeOpen

事件名称说明回调参数
beforeOpenMessage 实例显示前事件，在调用 Message 对象的实例 open() 方法后会触发。--

Usage

const message = new Message(Message.DEFAULTS)

outline.$on('beforeOpen', function() {
  // this 上下文就是 message 实例
  console.log('this', this)
})

opened

事件名称说明回调参数
openedMessage 实例显示后事件，在调用 Message 对象的实例 open() 方法后会触发。--

Usage

const message = new Message(Message.DEFAULTS)

outline.$on('opened', function() {
  // this 上下文就是 message 实例
  console.log('this', this)
})

closed

事件名称说明回调参数
closedMessage 实例显示后事件，在调用 Message 对象的实例 close() 方法后会触发。--

Usage

const message = new Message(Message.DEFAULTS)

outline.$on('closed', function() {
  // this 上下文就是 message 实例
  console.log('this', this)
})

beforeDestroy

事件名称说明回调参数
beforeDestroyMessage 实例销毁前事件，在调用 Message 对象的实例 destroy() 方法后会触发。--

Usage

const message = new Message(Message.DEFAULTS)

message.$on('beforeDestroy', function() {
  // this 上下文就是 message 实例
  console.log('this', this)
})

message.destroy()

destroyed

事件名称说明回调参数
destroyedMessage 实例销毁后事件，在调用 Message 对象的实例 destroy() 方法后会触发。--

Usage

const message = new Message(Message.DEFAULTS)

message.$on('destroyed', function() {
  // this 上下文就是 message 实例
  console.log('this', this)
})

message.destroy()