ew-message 一个基于typescript封装的消息提示框插件

ew-message

一个基于 typescript 而封装的消息提示框插件，可用于不使用ui组件库的中小型网站中。

安装与使用

安装

npm install ew-message --save-dev//或者 yarn add ew-message

引入

<script src="./dist/ew-message.min.js"></script>

消息提示框插件如下:

const msg1 = ewMessage('默认消息提示框');
const msg1 = ewMessage({
  content: '默认消息提示框'
});

option 配置对象有如下参数:

interface ewMessageOption {
  content: string; //消息提示框内容，必传参数
  center?: boolean; //消息提示框内容是否居中
  type?: string; //消息提示框类型，有四种: info,success,warning,error
  duration?: number; //消息提示框消失时间
  showClose?: boolean; //是否显示关闭按钮
  stylePrefix?: string; //消息提示框样式前缀，注意插件有检测如果导入了样式文件，则这个配置无效
  showTypeIcon?: boolean; // 是否显示类型图标，默认为true
  typeIcon?: string; // 自定义类型图标
  closeIcon?: string; // 自定义关闭按钮图标
  container?: string | HTMLElement; // 挂载元素
  immediate?: boolean; // 是否立即渲染消息提示框
  removeClassName?: string; // 移除消息提示框动画类名，目前内置动画类名值: fadeOut与scaleDown
  removeClassNameSymbol?: string; // 指定多个移除动画类名并且分隔符不是空白时传入
}

ps: 推荐使用导入样式文件的方式。

cdn 引入

//样式引入
// CDN:https://www.unpkg.com/ew-message/dist/ew-message.min.css
// CDN:https://www.unpkg.com/ew-message/dist/ew-message.min.js

在组件中使用

import ewMessage from 'ewMessage';
//  导入样式
import 'ew-message/dist/ew-message.min.css';
const msg = ewMessage(option); //option为配置对象，详情见前述

当然也可以不引入样式，插件检测了如果不导入样式文件，则会自动添加样式，并且也可以给样式添加类名前缀自定义样式。

参数接口

这里主要介绍函数的参数类型。

字符串参数

默认参数可以是一个字符串，用作消息提示框的内容，如:

const msg = ewMessage('这是一个默认的消息提示框');

配置对象

配置对象主要有 6 个属性，分别如下:

content

content 是一个字符串，用作消息提示框的内容，默认为空，如果在开发环境下（即导入的是非生产模式的文件 ewMessage.js），则会在控制台给出警告，如:

const msg = ewMessage({ content: '这是一个默认的消息提示框' });

center

center 属性是一个布尔值，表示是否让消息提示框的内容剧中，默认是 false。如:

// 消息提示框内容居中
const msg = ewMessage({ content: '这是一个默认的消息提示框', center: true });

type

type 的值虽然是一个字符串，但只支持"info" | "success" | "warning" | "error"，表示消息提示框的类型，默认是值是"info"。如:

const msg = ewMessage({
  content: '这是一个成功的消息提示框',
  center: true,
  type: 'success' // 成功消息提示框
});

duration

该字段的值是一个数值，表示消息提示框关闭的时间，默认值是 6s，可以自定义修改。如:

const msg = ewMessage({
  content: '这是一个默认的消息提示框',
  center: true,
  type: 'success',
  duration: 2000 // 消息提示框将在2s后关闭
});

需要注意的是，插件内部做了一个小小的规范化，如果传入的时间即 duration 的值小于 1000，则会自动乘以 10。

ps: 0.0.7 版本做了一个优化，如果 duration 不是一个数值，则会在开发环境下提示警告，如果小于等于 0，则会取 1000 作为默认值，默认值也由 6s 变成了 1s。

ps: 不建议将该值设置的过大。

maxDuration (0.0.7 版本新增)

该字段的值也是一个数值，表示消息提示框的最大关闭时间，插件内部会将该值与传入的 duration 值做比较，取两者之间的最小值，默认值是 10s。如:

const msg = ewMessage({
  content: '这是一个默认的消息提示框',
  center: true,
  type: 'success',
  duration: 120000,
  maxDuration: 10000 // 最大关闭时间设置的是10s，因此消息提示框将在10s后关闭，而不是12s后关闭
});

ps: 如果传入的值不是一个数值，也会在开发环境下提示警告，如果小于等于 duration,则会取 duration 作为默认值。

ps: 不建议设置该值。

showClose

该字段的值是一个布尔值，表示是否显示消息提示框的关闭按钮，默认值是 true，可以将值设置为 false。如:

const msg = ewMessage({
  content: '这是一个默认的消息提示框',
  showClose: false
});

ps: 需要注意的是如果将 duration 的值设置为 0,showClose 设置为 false,则在开发环境下会提供警告，然后自动开启消息提示框的关闭按钮。

stylePrefix

该属性是一个字符串，表示样式类名的前缀，默认是'ew-',可以自定义类名，方便自己修改样式。如:

const msg = ewMessage({
  content: '这是一个默认的消息提示框',
  stylePrefix: 'el-'
});

以上代码将会给消息提示框的样式类名前缀变成 el-,比如原本是 ew-message 类名将变成 el-message。

通常来讲这个属性应该是用不到的，只有在确实需要自定义样式的时候可以用到。

showTypeIcon (0.0.8)新增

该属性是一个布尔值，表示是否显示图标，会根据相关的类型来匹配相应的图标，比如 info 类型就是 info 类型的图标,默认值是 true。如下所示:

const msg = ewMessage({
  content: '这是一个默认的消息提示框',
  showTypeIcon: true
});

typeIcon(0.0.8 新增)

该属性用于自定义图标，需要将 showTypeIcon 设置为 true 才行，如果默认的图标不符合需求，可以自己传入一个 img 标签或者 svg 标签自定义一个图标，或者是任意元素，不过需要自己调整图标样式，可以定义${prefix}-message-${type}-icon相关的类名来使用默认的样式,其中 prefix 的值为前缀名默认是 ew,type 为消息提示框类型，如 info。如下所示:

const msg = ewMessage({
  content: '这是一个默认的消息提示框',
  showTypeIcon: true,
  typeIcon:
    '<svg t="1695191942528" class="ew-message-icon ew-message-info-icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="7731" id="mx_n_1695191942529"><path d="M512 1024A512 512 0 1 1 512 0a512 512 0 0 1 0 1024zM448 448v384h128V448H448z m0-256v128h128V192H448z" fill="#1677ff" p-id="7732"></path></svg>'
});

closeIcon(0.0.8 新增)

该属性用于自定义关闭按钮的图标，需要将 showClose 设置为 true 才行，如果默认的关闭按钮图标不符合需求，可以自己传入一个 img 标签或者 svg 标签自定义一个图标，或者是任意元素，不过需要自己调整图标样式，可以定义${prefix}-message-close-icon相关的类名来使用默认的样式,其中 prefix 的值为前缀名，默认是 ew。如:

// 不推荐替换默认的图标
const msg = ewMessage({
  content: '这是一个默认的消息提示框',
  showTypeIcon: true,
  closeIcon:
    '<svg t="1695191942528" class="ew-message-close-icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="7731" id="mx_n_1695191942529"><path d="M512 1024A512 512 0 1 1 512 0a512 512 0 0 1 0 1024zM448 448v384h128V448H448z m0-256v128h128V192H448z" fill="#1677ff" p-id="7732"></path></svg>'
});

container(0.0.9 新增)

该属性用于设置消息提示框挂载的元素，可以传入一个 dom 元素字符串或者是 dom 元素，不满足则会在开发环境下给出警告提示，默认值是 body 元素。如:

const msg = ewMessage({
  content: '这是一个默认的消息提示框',
  container: '#test'
});
// 将消息提示框挂载到页面当中id为test的元素中

immediate(0.0.9 新增)

该属性用于是否立即渲染消息提示框，如果设置为 false，则需要手动调用 render,render 方法可以传也可以不传参数，方法来渲染消息提示框，默认值是 true。如:

const msg = ewMessage({
  content: '这是一个默认的消息提示框',
  immediate: false
});
msg.render(); // 内部会自动获取配置对象并渲染

removeClassName(0.0.9 新增)

该属性用于卸载消息提示框时添加的动画类名，目前内置有 fadeOut 和 scaleDown 动画效果，如指定了正确的动画类名值，当点击关闭或者是自动关闭消息提示框的时候，会有相应的动画效果,默认值是空字符串，即没有动画效果。如:

const msg = ewMessage({
  content: '这是一个默认的消息提示框',
  removeClassName: 'fadeOut' // 或者也可以传入ew-message-fadeOut
});

也可以传入多个类名，多个类名之间可以使用任意值或者空白来隔开，如果不是使用空白隔开，则需要指定 removeClassNameSymbol 的值，例如:

const msg = ewMessage({
  content: '这是一个默认的消息提示框',
  removeClassName: 'fadeOut scaleDown' // 或者也可以传入ew-message-fadeOut ew-message-scaleDown
  // 这里是使用空白隔开，因此不需要指定 removeClassNameSymbol
});

const msg = ewMessage({
  content: '这是一个默认的消息提示框',
  removeClassName: 'fadeOut,scaleDown' // 或者也可以传入ew-message-fadeOut ew-message-scaleDown
  removeClassNameSymbol: ','
  // 这里是使用逗号隔开
});

我们可以结合animate.css来为移除消息提示框添加对应的动画效果，如果页面当中引入了该样式文件，则可以传入相应的类名，如:

// 假设页面引入了animate.css文件
const msg = ewMessage({
  content: '这是一个默认的消息提示框',
  removeClassName: 'animate__animated animate__bounce'
});

removeClassNameSymbol(0.0.9 新增)

用于指定多个 removeClassName 的分隔符，如果 removeClassName 指定的是单个类名或者是多个以空白隔开的类名，则不需要传入该值。如:

const msg = ewMessage({
  content: '这是一个默认的消息提示框',
  removeClassName: 'fadeOut+scaleDown' // 或者也可以传入ew-message-fadeOut ew-message-scaleDown
  removeClassNameSymbol: '+'
  // 这里是使用+隔开
});

messageZIndex(0.1.0 新增)

用于自定义消息提示框的显示层级，是一个 number 值，用于覆盖默认得到 z-index:1000，无默认值。如:

const msg = ewMessage({
  content: '这是一个默认的消息提示框',
  messageZIndex: 2000
});
// 设置消息提示框的显示层级为2000

实例方法接口

除了属性接口之外，我们也可以使用插件的一些实例方法，总结如下。

实例属性

options

消息提示框的配置对象。如:

const msg = ewMessage('这是一个默认的消息提示框');
console.log(msg.options); // { content:"这是一个默认的消息提示框",... }

el

消息提示框的根元素。

closeBtnEl

消息提示框的关闭元素。

实例方法

destroy (0.0.6 版本新增)

该方法将会立即销毁消息提示框实例。如:

const msg = ewMessage('这是一个默认的消息提示框');
msg.destroy(); // 页面将不再看到消息提示框

validateHasStyle

该方法验证消息提示框是否含有样式，如果通过 link 标签导入样式，则该方法返回 true，否则返回 false。如:

const msg = ewMessage('这是一个默认的消息提示框');
msg.validateHasStyle(); // 假设页面引入了消息提示框的样式，则返回true

normalizeOptions

该方法规范化传入的参数，并和默认配置对象合并，最终返回一个消息提示框的配置对象。

getMessageType

该方法返回消息提示框支持的类型值。

getDefaultOption

该方法用于获取消息提示框的默认配置对象。

addMessageStyle

该方法用于添加消息提示框的样式，如果传入了第二个参数，将会将第二个参数的样式作为最终样式添加到页面中，两个参数都是一个字符串。不同的是，第一个参数代表样式前缀名，第二个参数代表一个样式字符串。如:

const msg = ewMessage('这是一个默认的消息提示框');
msg.addMessageStyle('ew-', `body { background: #2396ef; }`); // 第一个参数实际上就没有什么作用了，页面body元素的背景是蓝色
msg.addMessageStyle('el-'); // 会添加消息提示框的默认样式，但类名前缀是el-

render

这个方法就是渲染消息提示框的核心方法，不需要使用，感兴趣可参看源码。

create

该方法表示创建一个消息提示框的元素，返回消息提示框的根元素，不需要使用，感兴趣可参看源码。

setTop

该方法用于设置消息提示框的 top 偏移量，不需要使用，感兴趣可参看源码。

close

该方法用于销毁一个 dom 元素，传入 2 个参数，第一个参数是一个 dom 元素或者是 dom 元素集合，第二个参数是销毁的时间，是一个数值。如:

const msg = ewMessage('这是一个默认的消息提示框');
msg.close(msg.el, 1000); // 将在1s后移除元素

内置工具函数接口

插件内部提供了一些工具函数可供调用，该工具函数定义在 ewMessage 的静态属性 util 上，我们可以通过如下代码来获取:

const util = ewMessage.util;
// 以下的util均指这里

isFunction

该工具函数表示判断是否是一个函数，传入一个需要判断的参数。如:

const testFn = function () {
  console.log('这是一个函数');
};
util.isFunction(testFn); // true
util.isFunction(null); // false

isDom

该工具函数表示判断是否是一个 dom 元素，传入一个需要判断参数。如:

const div = document.querySelector('#app');
util.isDom(div); // true;
util.isDom(1); // false;

isObject

该工具函数表示判断是否是一个对象，传入一个需要判断的参数。如:

util.isObject({}); // true;
util.isObject([]); // true;
util.isObject(function () {
  console.log(1);
}); // false;
util.isObject(111); // false;

isString

该工具函数表示判断是否是一个字符串，传入一个需要判断的参数。如:

util.isString('111'); // true;
util.isString(111); // false

isNumber(0.0.7 版本新增)

该工具函数表示判断是否是一个数值，传入一个需要判断的参数。如:

util.isNumber(123); // true;
util.isNumber(NaN); // false;
util.isNumber('1111'); // false

warn

该函数表示在控制台打印一些警告信息，传入一个需要打印的信息字符串。如:

util.warn('warning: this is not a function');

hasOwn

该工具函数表示某个属性是否在某个对象上，传入 2 个参数，第一个参数是一个对象，第二个参数是一个属性名。如:

const obj = { name: 'eveningwater' };
util.hasOwn(obj, 'name'); // true;
util.hasOwn(obj, 'age'); // false;

toArray

该工具函数用于将伪数组转换成真正的数组，传入一个需要转换的值。如:

// 假设页面有多个<div class="list-item"></div>的元素
const listItems = document.querySelectorAll('.list-item');
util.toArray(listItems); // 一个包含多个div元素的数组

$

该工具函数用于获取 dom 元素，有两个参数，第一个参数是一个字符串，第二个参数是一个 dom 元素。如:

const app = util.$('#app');
util.$('.child', app);

$$

该工具函数用于获取 dom 元素集合即 NodeList,参数同$方法。如:

const app = util.$('#app');
util.$$('.child', app);
util.$$('.child');

createElement(0.0.8 新增)

该工具函数用于根据模板字符串创建一个 dom 元素，模板字符串可以带入子元素，如:

const html = util.createElement(`<div><span></span></div>`);
console.log(html); // 返回div节点

addClass(0.0.9 新增)

该工具函数用于给 dom 元素添加类名，需要传入 2 个参数，如:

const html = util.addClass(`app`, util.$('#app'));
// 给id为app的元素添加app类名

off(0.0.9 新增)

该方法用于给移除一个事件监听器，传入四个参数，第一个为 DOM 元素，第二个为事件名，第三个参数为事件监听器，第四个参数为一个布尔值。如:

const test = document.getElementById('test');
const handler = e => console.log(e.target.tagName);
util.off(test, 'click', handler);

on(0.0.9 新增)

该方法用于添加一个事件监听器，参数等同 off 方法。如:

const test = document.getElementById('test');
const handler = e => console.log(e.target.tagName);
util.on(test, 'click', handler);

更多详情参阅文档官网介绍ew-message;

更新日志

• 0.0.1 \~ 0.0.4: 添加了消息提示框的基本功能。
• 0.0.5: 修改了 ts 类型导入。
• 0.0.6: 消息提示框添加了销毁 destroy 方法。
• 0.0.7: 完善了 ts 类型,新增了最大关闭时间属性 maxDuration,修改了默认关闭时间。
• 0.0.8: 新增了 showTypeIcon 和 typeIcon 属性以及 closeIcon，用于配置图标,新增了工具方法 createElement。
• 0.0.9: 新增了 container、immediate、removeClassName、removeClassNameSymbol 配置属性，新增了 on,off,addClass 工具方法。

以下为示例代码:

jcode