Global API

一个提供全局 toast、loading、modal、action sheet 的纯 JS 库，无依赖。

安装

npm i x-global-api --save

使用

Toast

提供各种形式的 toast。特性如下：

• 默认图标支持 'success' | 'error' | 'warning' | 'loading' | 'custom' | 'none' ，可自定义图标（图标设置为 custom）；
• 支持纯图标或纯文本提示；
• 支持图标及文本横向或纵向显示；
• 支持 toast 垂直方向上，中，下显示；
• 支持配置默认参数。

import { Toast, showToast, hideToast, ToastConfig, ToastOptions } from 'x-global-api';

// es 模块导入使用，手动引入 css 文件
import 'x-global-api/dist/esm/index.css';

// toast 默认会自动关闭
// 如不需要自动关闭，可设置 duration 为 0，或设置一个超大的值
// 默认参数 Toast.defaultConfig
// {
//   icon: 'none',
//   mask: false,
//   duration: 2000,
//   maxWidth: 'calc(100vw - 32px)',
//   place: 'center',
//   layout: 'block',
//   animation: 'fade',
//   zIndex: 'auto',
//   multiLine: false,
//   iconMap: {
//     success: 'xxx', // success icon 的地址，默认用了一个base64图标，太长，所以这里用xxx表示，下面的 error，warning 一样
//     error: 'xxx',
//     warning: 'xxx',
//     loading: '',
//     custom: '',
//     none: '',
//   },
// };

// 可通过静态方法 setConfig 更新默认配置
Toast.setconfig(config: ToastConfig);

showToast(options: ToastOptions); // ToastOptions 见下面 TS 类型
hideToast();

Loading

loading 属于 toast 的特例。toast 默认会自动消失，但是 loading 不会，需要主动调用 hideLoading。

默认 loading 是用 CSS 画的一个简单图标，可以通过 Toast.setconfig 指定 loading icon。

import { showLoading, hideLoading, LoadingOptions } from 'x-global-api';

showLoading(options: LoadingOptions); // LoadingOptions 见下面 TS 类型
hideLoading();

Modal

import { Modal, showModal, ModalConfig, ModalOptions } from 'x-global-api';

// 默认参数 Modal.defaultConfig
// {
//   width: '300px',
//   footerButtons: [{ text: '取消', key: 'cancel' }, { text: '确认', key: 'confirm' }],
//   footerLayout: 'inline',
//   maskCanClose: true,
//   animation: 'fade',
//   isDarkModel: false,
//   zIndex: 'auto',
// }

// 可通过静态方法 setConfig 更新默认配置
Modal.setConfig(config: ModalConfig);

showModal(options: ModalOptions); // ModalOptions 见下面 TS 类型

ActionSheet

import { ActionSheet, showActionSheet, ActionSheetConfig, ActionSheetOptions } from 'x-global-api';

// 默认参数 ActionSheet.defaultConfig
// {
//   cancel: { text: '取消', key: 'cancel' },
//   animation: 'slide',
//   maskCanClose: true,
//   isDarkModel: false,
//   safeArea: true,
//   zIndex: 'auto',
// }

// 可通过静态方法 setConfig 更新默认配置
ActionSheet.setConfig(config: ActionSheetConfig);

showActionSheet(options: ActionSheetOptions); // ActionSheetOptions 见下面 TS 类型

详细说明

TS 类型

// toast
// -----------------------------------------
export type ToastIconType = 'success' | 'error' | 'warning' | 'loading' | 'custom' | 'none';
export type ToastIconMap = Record<ToastIconType, string>;
export type ToastPlace = 'top' | 'center' | 'bottom';
export type ToastLayout = 'inline' | 'block';
export type ToastAnimation = 'fade' | 'down' | 'up' | 'none' | string;
export type LoadingOptions = Partial<Omit<ToastOptions, 'duration' | 'icon'>>;

export interface ToastConfig {
  icon?: ToastIconType; // 图标类型
  mask?: boolean;
  duration?: number;
  maxWidth?: string;
  place?: ToastPlace; // toast 出现未知，默认居中
  layout?: ToastLayout; // icon 与 title 的布局，inline 表示是同一行显示，block 表示各自独立一行显示
  animation?: ToastAnimation; // 使用什么动画
  iconMap?: ToastIconMap; // 图标类型所使用的图片
  zIndex?: number | 'auto';
  multiLine?: boolean; // 开启多行，不然会单行省略
}

export interface ToastOptionsExcludeConfig {
  parent?: Element; // 插入的父元素节点，默认为 body
  iconUrl?: string; // 当图片类型为 'custom' 时，自定义的图标地址。其余情况该地址无效。
  title?: string;
  wrapClass?: string; // 添加 className
  offset?: string; // 当 place 为 top 或 bottom 时，偏移顶部或底部的距离，默认为 15px
  safeArea?: boolean; // 当开启 safeArea，place 为 top 或 bottom 时，偏移的距离会再加上安全距离
  onAfterLeave?(): void; // toast 消失之后的回调
}

// show 方法参数 options
export type ToastOptions = ToastConfig & ToastOptionsExcludeConfig;

// modal
// -----------------------------------------
export type ModalFooterButton = { text: string; color?: string; key?: string };
export type ModalFooterButtonCallback = (key: string) => void | boolean; // key 对应 ModalFooterButton 中的 key，如没有，则为 index 值。
export type ModalFooterLayout = 'inline' | 'block';

export interface ModalConfig {
  width?: string;
  footerButtons?: ModalFooterButton[]; // 底部按钮
  footerLayout?: ModalFooterLayout; // 底部按钮布局，inline 所有按钮一行显示，block 表示各自一行
  maskCanClose?: boolean;
  animation?: 'scale' | 'none' | string; // 动画
  isDarkModel?: boolean; // 是否使用黑暗模式
  zIndex?: number | 'auto';
}

export interface ModalOptionsExcludeConfig {
  title?: string;
  content?: string;
  callback?: ModalFooterButtonCallback; // 按钮点击对应的回调，如果 return true 则不关闭该弹窗
  parent?: Element;
  wrapClass?: string; // 添加的 class
  onAfterLeave?(): void; // modal 消失之后的回调
}

// show 方法参数 options
export type ModalOptions = ModalConfig & ModalOptionsExcludeConfig;

// action-sheet
// -----------------------------------------
export type ActionSheetItem = { text: string; color?: string; key?: string } | string;
export type ActionSheetCallback = (key: string) => void | boolean; // key 对应 ActionSheetItem 中的 key，如没有，则为 index 值。

export interface ActionSheetConfig {
  cancel?: ActionSheetItem | false;
  animation?: 'slide' | 'none' | string;
  maskCanClose?: boolean;
  isDarkModel?: boolean;
  safeArea?: boolean;
  zIndex?: number | 'auto';
}

export interface ActionSheetOptionsExcludeConfig {
  title?: string;
  items?: ActionSheetItem[];
  callback?: ActionSheetCallback;
  parent?: Element;
  wrapClass?: string;
  onAfterLeave?(): void;
}

export type ActionSheetOptions = ActionSheetConfig & ActionSheetOptionsExcludeConfig;

export type ActionSheetInstanceOptions = Required<ActionSheetConfig> & ActionSheetOptionsExcludeConfig;

修改样式说明

第一种方法：通过修改 css 变量的值。

默认提供的如下的 css 变量，可通过修改变量的值来修改样式。

:root {
  --global-api-toast-bg-color: rgba(0, 0, 0, 0.7);
  --global-api-toast-text-color: #fff;
  --global-api-toast-loading-border-color: rgba(256, 256, 256, 0.5); // 默认 loading 图标四分之三的颜色
  --global-api-toast-loading-border-bottom-color: #fff; // 默认 loading 图标四分之一的颜色
  --global-api-toast-radius: 8px;
  --global-api-toast-z-index: 6000;

  --global-api-modal-overlay-bg-color: rgba(0, 0, 0, 0.7);
  --global-api-modal-bg-color: #fff;
  --global-api-modal-bg-active-color: #ededed;
  --global-api-modal-text-color: #000;
  --global-api-modal-radius: 8px;
  --global-api-modal-z-index: 5000;
  --global-api-modal-btn-border-color: #ededed;

  --global-api-action-sheet-overlay-bg-color: rgba(0, 0, 0, 0.7);
  --global-api-action-sheet-bg-color: #fff;
  --global-api-action-sheet-divide-bg-color: #f7f7f7;
  --global-api-action-sheet-bg-active-color: #ededed;
  --global-api-action-sheet-font-size: 16px;
  --global-api-action-sheet-title-color: #999;
  --global-api-action-sheet-text-color: #000;
  --global-api-action-sheet-radius: 8px;
  --global-api-action-sheet-z-index: 5000;
}

第二种方法：自定义 class

通过 wrapClass 属性自定义 class，来覆盖样式。

动画说明

• Toast 根据显示位置上、中、下，提供了 3 组动画，分别为 fade in/out，down in/out，up in/out。可自定义动画样式；
• Modal 只提供一种 scale in/out 动画；
• ActionSheet 只提供了一种 slide in/out 动画；
• 如不需要动画，则设置参数 animation 为 none 即可。

自定义动画

自定义 animation 属性的值，就会生成对应的 class。然后以此 class 就可以自定义动画，注意动画应该使用 animation 关键帧动画，不能使用 transition 动画。

以自定义 modal 的动画为例。设置 animation 的值为 scale，将会以该值添加对应的进入和离开动画 class，进入的 class 为 .global-api-modal-scale-in，对应的离开 class 为 .global-api-modal-scale-out。（如果为 toast，则相应的为 class 把 modal 关键词换成 toast 即可。）

不论是 toast，modal，还是 actionSheet，其实都是一个容器，然后包括主体内容和遮罩两部分。

<!-- toast 结构 -->

<!-- 动画的进入和离开 class 挂着该节点上-->
<div class="global-api-toast">
  <!-- 如果 mask 为 true 则有，否则没有该层 -->
  <div class="global-api-toast-overlay"></div>
  <div class="global-api-toast-main">...</div>
</div>

<!-- modal 结构 -->
<!-- 动画的进入和离开 class 挂着该节点上-->
<div class="global-api-modal">
  <div class="global-api-modal-overlay"></div>
  <div class="global-api-modal-main">...</div>
</div>

<!-- modal 结构 -->
<!-- 动画的进入和离开 class 挂着该节点上-->
<div class="global-api-action-sheet">
  <div class="global-api-action-sheet-overlay"></div>
  <div class="global-api-action-sheet-main">...</div>
</div>

由于动画涉及到两层，遮罩层和主体内容层，对于遮罩层来说，一个渐隐渐现动画即可，而内容主体就可以搞各种动画了。所以如果要自定义动画，其实应该有两个动画，一个是全局的渐隐渐现动画，一个是内容主体的动画。以上面的 modal 的 scale 为例：

/* animation: scale in/out */
/* -------------------------------------- */
/* 整体 fade 动画 */
.global-api-modal-scale-in {
  animation: globalApiModalFadeIn 0.3s ease-in-out both;
}

.global-api-modal-scale-out {
  animation: globalApiModalFadeIn 0.3s ease-in-out reverse both;
}

/* 主题内容 scale 动画 */
.global-api-modal-scale-in .global-api-modal-main {
  animation: globalApiModalScaleIn 0.3s ease-in-out both;
}

.global-api-modal-scale-out .global-api-modal-main {
  animation: globalApiModalScaleIn 0.3s ease-in-out reverse both;
}

@keyframes globalApiModalFadeIn {
  from {
    opacity: 0;
  }
  to {
    opacity: 1;
  }
}

@keyframes globalApiModalScaleIn {
  from {
    transform: scale(0.5);
  }
  to {
    transform: scale(1);
  }
}

查看 demo

运行命令，开启本地服务：

npm run dev

访问 example 目录中的 html 文件即可预览，如预览 toast demo： http://127.0.0.1:5173/example/toast.html

注意事项

• toast 和 loading 公用一个实例，每次只能有一个出现，如果有新的要 show，那么老的就会被移除掉。
• 该库 TS 编译的 target 为 ES2015（即为最基础版本的 es6）。
• 如果为 es 模块导入使用，则需要手动引入 css 文件，如果是 umd 使用，则已经自动打包，不需要再手动引入