SEPG框架-通用组件使用手册

返回目录

SEPG框架-通用组件使用手册

  • 框架版本: 2.1.0
  • 文档版本: 1.0.0
  • 生成时间: 2026-03-19 10:58:18

1. Emitter - 事件总线组件

1.1 组件概述

Emitter是一个事件总线组件，提供事件的监听、触发、移除等功能，支持单例模式和多实例模式。

1.2 导出函数

1.2.1 getEmitterInstance

获取单例事件总线实例。

function getEmitterInstance(): Emitter

返回值: Emitter实例
示例:

import { getEmitterInstance } from "sepg";
const emitter = getEmitterInstance();
emitter.on('event-name', callback);
emitter.emit('event-name', data);

1.2.2 getUniqueEmitter

获取唯一标识的事件总线实例。

function getUniqueEmitter(key: string): Emitter

参数:

import { getUniqueEmitter } from "sepg";
const emitter = getUniqueEmitter('my-module');
emitter.on('event-name', callback);

1.2.3 delUniqueEmitter

删除指定标识的事件总线。

function delUniqueEmitter(key: string): void

参数:

import { delUniqueEmitter } from "sepg";
delUniqueEmitter('my-module');

1.2.4 clearUniqueEmitter

清空唯一标识的事件总线栈。

function clearUniqueEmitter(): void

示例:

import { clearUniqueEmitter } from "sepg";
clearUniqueEmitter();

1.3 Emitter类方法

1.3.1 on

监听事件。

on(event: string, cb: Function): Emitter

参数:

emitter.on('click', (data) => {
  console.log('Clicked:', data);
});

1.3.2 emit

触发指定事件。

emit<T>(event: string, ...data: T[]): Emitter

参数:

emitter.emit('click', { x: 100, y: 200 });

1.3.3 emitAll

触发所有监听事件。

emitAll(): Emitter

返回值: Emitter实例（支持链式调用）
示例:

emitter.emitAll();

1.3.4 keep

保留指定事件，移除其他所有事件。

keep(event: string | string[]): Emitter

参数:

// 保留单个事件
emitter.keep('click');
// 保留多个事件
emitter.keep(['click', 'hover']);

1.3.5 off

移除指定事件。

off(event: string): Emitter

参数:

emitter.off('click');

1.3.6 offAll

移除全部监听事件。

offAll(): Emitter

返回值: Emitter实例（支持链式调用）
示例:

emitter.offAll();

2. Toast - 消息提示组件

2.1 组件概述

Toast是一个消息提示组件，用于在页面中显示提示信息，支持自定义样式、位置、动画等配置。

2.2 接口定义

ToastConfig

Toast配置接口。

interface ToastConfig {
  /** 弹框提示信息 */
  msg?: string;
  /** 页面弹框最大个数 */
  maxCount?: number;
  /** 容器id */
  containerId?: string;
  /** 宽度 */
  width?: string;
  /** 超时隐藏的毫秒数 */
  timeout?: number;
  /** 圆角度radius */
  borderRadius?: string;
  /** 背景 */
  background?: string;
  /** 文字对齐方式 */
  align?: TAlign;
  /** 内边距 */
  padding?: string;
  /** 外边距 */
  margin?: string;
  /** 显示浮动距离 */
  floatHeight?: number;
  /** 偏移间距 */
  floatSpacing?: number;
  /** 字体大小 */
  fontSize?: string;
  /** 文字颜色 */
  color?: string;
  /** 显示位置 */
  position?: TPosition;
  /** 是否淡入淡出 */
  fade?: boolean;
}

配置项说明:

配置项 类型 默认值 说明
msg string '' 弹框提示信息
maxCount number 1 页面弹框最大个数
containerId string 'default' 容器id
width string 'auto' 宽度
timeout number 3000 超时隐藏的毫秒数
borderRadius string '5px' 圆角度
background string 'rgba(35, 35, 35, 0.9)' 背景颜色
align TAlign 'center' 文字对齐方式
padding string '30px 100px' 内边距
margin string '25px' 外边距
floatHeight number 100 显示浮动距离
floatSpacing number 20 偏移间距
fontSize string '30px' 字体大小
color string '#ffffff' 文字颜色
position TPosition 'bottom-center' 显示位置
fade boolean true 是否淡入淡出

2.3 导出函数

2.3.1 showToast

显示Toast提示信息。

function showToast(config: ToastConfig | string): Toast

参数:

import { showToast } from "sepg";
// 使用默认配置
showToast('这是toast提示');
// 使用自定义配置
showToast({
  msg: '这是toast提示',
  fontSize: '50px',
  background: 'rgba(255, 0, 0, 0.8)'
});

2.3.2 buildToast

构建Toast实例。

function buildToast(config?: ToastConfig): Toast

参数:

import { buildToast } from "sepg";
const toast = buildToast({
  msg: '准备就绪',
  fontSize: '40px'
});
toast.toast();

2.3.3 setGlobalToastConfig

设置全局默认配置。

function setGlobalToastConfig(config: ToastConfig): void

参数:

import { setGlobalToastConfig, showToast } from "sepg";
setGlobalToastConfig({
  fontSize: '36px',
  timeout: 5000,
  background: 'rgba(0, 0, 0, 0.8)'
});
showToast('使用全局配置的提示');

2.4 Toast类方法

2.4.1 setConfig

配置toast参数。

setConfig(config: ToastConfig | string): Toast

参数:

toast.setConfig({
  msg: '新消息',
  fontSize: '40px'
});

2.4.2 toast

执行toast显示。

toast(msg?: string): Toast

参数:

toast.toast('显示提示');

2.4.3 dismiss

取消并移除toast。

dismiss(): Toast

返回值: Toast实例（支持链式调用）
示例:

toast.dismiss();

3. Storage - 存储操作组件

3.1 组件概述

Storage组件提供了对Cookie、localStorage、sessionStorage的统一操作接口，支持设置、获取、删除、清空等操作。

3.2 Cookie对象

3.2.1 setItem

设置Cookie键值。

setItem(key: string, value: string): void

参数:

import { Cookie } from "sepg";
Cookie.setItem('username', 'admin');

3.2.2 getItem

获取Cookie值。

getItem(key: string): string | null

参数:

const username = Cookie.getItem('username');
console.log(username);

3.2.3 getKeys

获取全部键。

getKeys(): string[]

返回值: 键数组
示例:

const keys = Cookie.getKeys();
console.log(keys);

3.2.4 removeItem

移除Cookie值。

removeItem(key: string): void

参数:

Cookie.removeItem('username');

3.2.5 clear

清除所有Cookie值。

clear(): void

示例:

Cookie.clear();

3.3 StorageTool对象

3.3.1 uesLocalStorage

使用localStorage存储（默认是采用sessionStorage）。

uesLocalStorage(): void

示例:

import { StorageTool } from "sepg";
StorageTool.uesLocalStorage();

3.3.2 setItem

设置存储键值。

setItem(key: string, value: string): void

参数:

StorageTool.setItem('token', 'abc123');

3.3.3 getItem

获取存储值。

getItem(key: string): string | null

参数:

const token = StorageTool.getItem('token');

3.3.4 getKeys

获取全部键。

getKeys(): string[]

返回值: 键数组
示例:

const keys = StorageTool.getKeys();

3.3.5 removeItem

移除存储值。

removeItem(key: string): void

参数:

StorageTool.removeItem('token');

3.3.6 clear

清除所有存储值。

clear(): void

示例:

StorageTool.clear();

4. Loader - 加载器组件

4.1 组件概述

Loader是一个加载器组件，用于在页面中显示加载动画，支持自定义样式、位置、内容等配置。

4.2 类型定义

LoaderConfig

Loader配置类型。

type LoaderConfig = Partial<{
  /** 持有的dom元素 */
  element: ExtendHTMLElement | null;
  /** 容器元素 */
  container: Element;
  /** 定位left值 */
  left: number | string;
  /** 定位top值 */
  top: number | string;
  /** 宽度 */
  width: number | string;
  /** 高度 */
  height: number | string;
  /** 缩放比例 */
  zoom: number;
  /** 背景圆角度 */
  radius: string;
  /** 显示字体颜色 */
  color: string;
  /** 层级 */
  zIndex: number;
  /** 指定的显示内容或返回内容的函数 */
  content: Content;
  /** 延迟显示时间ms */
  time: number;
}>

配置项说明:

配置项 类型 默认值 说明
element ExtendHTMLElement | null null 持有的dom元素
container Element document.body 容器元素
left number | string '50%' 定位left值
top number | string '50%' 定位top值
width number | string 60 宽度
height number | string 60 高度
zoom number 1 缩放比例
radius string - 背景圆角度
color string '#ffffff' 显示字体颜色
zIndex number 999 层级
content Content - 指定的显示内容或返回内容的函数
time number 500 延迟显示时间ms

4.3 导出函数

4.3.1 createLoader

生成loader实例。

function createLoader(config?: LoaderConfig): Loader

参数:

import { createLoader } from "sepg";
// 使用默认配置
const loader = createLoader();
// 显示loader
loader.show();
// 隐藏loader
loader.hide();
// 使用自定义配置
const customLoader = createLoader({
  container: document.getElementById('my-container'),
  width: 100,
  height: 100,
  color: '#ff0000',
  time: 1000
});
customLoader.show();

4.4 Loader类方法

4.4.1 show

显示loader组件。

show(): void

示例:

loader.show();

4.4.2 hide

隐藏loader组件。

hide(): void

示例:

loader.hide();

4.4.3 remove

移除loader组件。

remove(): void

示例:

loader.remove();

5. CycleStack - 循环栈组件

5.1 组件概述

CycleStack是一个循环栈组件，用于管理页面路由历史记录，支持入栈、出栈、获取状态等操作，常用于页面导航管理。

5.2 CycleStack对象方法

5.2.1 setMaxRecord

设置最大记录数。

setMaxRecord(value: number): void

参数:

import { CycleStack } from "sepg";
// 设置最大记录数为20
CycleStack.setMaxRecord(20);

5.2.2 setChangeListener

设置路由切换回调。

setChangeListener(listener: Listener): void

参数:

CycleStack.setChangeListener((next, from, to) => {
  console.log('从', from, '跳转到', to);
  // 执行跳转
  next();
});

5.2.3 has

是否存在记录。

has(): boolean

返回值: 是否存在记录
示例:

if (CycleStack.has()) {
  console.log('存在历史记录');
}

5.2.4 getFromUrl

获取来源链接。

getFromUrl(): string

返回值: 来源链接
示例:

const fromUrl = CycleStack.getFromUrl();
console.log('来源:', fromUrl);

5.2.5 pushState

跳转目标链接并入栈。

pushState(url: string, data: any, save: boolean = true): void

参数:

CycleStack.pushState('/detail', { id: 123, returnUrl: '/list' });

5.2.6 replaceState

跳转目标链接（不入栈）。

replaceState(url: string, save: boolean = true): void

参数:

CycleStack.replaceState('/home');

5.2.7 getState

获取链接参数。

getState(url?: string, decode?: boolean): object

参数:

const params = CycleStack.getState();
console.log(params.id);

5.2.8 backState

出栈。

backState(returnUrl?: string, delta: number = -1, remove: boolean = true): void

参数:

// 返回上一步
CycleStack.backState();
// 返回指定地址
CycleStack.backState('/home');
// 返回上两步
CycleStack.backState(undefined, -2);

5.2.9 clearState

清空栈。

clearState(): void

示例:

CycleStack.clearState();

5.2.10 getStackList

获取栈列表。

getStackList(): string[]

返回值: 栈列表（字符串数组）
示例:

const stackList = CycleStack.getStackList();
console.log(stackList);

6. Marquee - 文字滚动组件

6.1 组件概述

Marquee是一个文字滚动组件，支持上下左右四个方向的滚动，支持自定义速度、间距、渐隐效果等配置。

6.2 接口定义

MarqueeConfig

Marquee配置接口。

interface MarqueeConfig {
  /** 滚动文字间的像素间距 */
  space?: number;
  /** 延迟滚动毫秒数 */
  delay?: number;
  /** 滚动方向 */
  direction?: TKeyDir;
  /** 速度 */
  speed?: number;
  /** 是否显示左右渐隐效果 */
  shadow?: boolean;
  /** 是否强制js执行 */
  forceJs?: boolean;
  /** 是否是维语文字 */
  wy?: boolean;
  /** 持有的dom元素 */
  element?: ExtendHTMLElement;
  /** 是否降级marquee标签做滚动 */
  tag?: boolean;
}

配置项说明:

配置项 类型 默认值 说明
space number 50 滚动文字间的像素间距
delay number 1000 延迟滚动毫秒数
direction TKeyDir 'left' 滚动方向
speed number 10 速度
shadow boolean true 是否显示左右渐隐效果
forceJs boolean false 是否强制js执行
wy boolean false 是否是维语文字
element ExtendHTMLElement - 持有的dom元素
tag boolean false 是否降级marquee标签做滚动

6.3 导出函数

6.3.1 createMarquee

生成文字滚动实例。

function createMarquee(config: MarqueeConfig): Marquee

参数:

import { createMarquee } from "sepg";
const dom = document.getElementById('marquee-container');
const marqueeObj = createMarquee({ 
  element: dom,
  direction: 'left',
  speed: 15
});
marqueeObj.move(); // 开始滚动
marqueeObj.stop(); // 停止滚动

6.3.2 setGlobalMarqueeConfig

设置全局默认配置。

function setGlobalMarqueeConfig(config: MarqueeConfig): void

参数:

import { setGlobalMarqueeConfig, createMarquee } from "sepg";
setGlobalMarqueeConfig({
  speed: 20,
  shadow: false
});
const marquee = createMarquee({ element: dom });

6.4 Marquee类方法

6.4.1 update

更新配置。

update(config: MarqueeConfig): Marquee

参数:

marquee.update({
  direction: 'right',
  speed: 20
});

6.4.2 move

开始滚动。

move(): Marquee

返回值: Marquee实例（支持链式调用）
示例:

marquee.move();

6.4.3 stop

停止滚动。

stop(): Marquee

返回值: Marquee实例（支持链式调用）
示例:

marquee.stop();

附录

A. 类型定义汇总

TAlign

文字对齐方式类型。

type TAlign = 'left' | 'center' | 'right';

TPosition

显示位置类型。

type TPosition = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';

TKeyDir

滚动方向类型。

type TKeyDir = 'left' | 'right' | 'up' | 'down';

Content

内容类型。

type Content = string | (() => string);

ExtendHTMLElement

type Content = string | string[] | ExtendHTMLElement | (() => string | string[] | ExtendHTMLElement);
interface ExtendHTMLElement extends HTMLElement {
  /**
   * 添加事件监听
   * @param type 事件名
   * @param listener 监听函数
   * @param option 监听配置
   */
  addEvent<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
  addEvent(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
  /**
   * 移除事件监听
   * @param type 事件名
   * @param listener 监听函数
   */
  removeEvent<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
  removeEvent(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
  /**
   * 显示dom
   */
  block(): this;
  /**
   * 隐藏dom
   */
  none(): this;
  /**
   * 显示dom
   */
  visible(): this;
  /**
   * 隐藏dom
   */
  unvisible(): this;
  /**
   * dom是否可见
   */
  active(): boolean;
  /**
   * 设置不透明度
   * @param {number} opacity 不透明度 0-1
   */
  setOpacity(opacity: number): this;
  /**
   * 淡入动画
   * @param {number} duration 动画时间ms
   * @param {() => void} complete 动画结束回调
   * @default 1000
   */
  fadeIn(duration?: number, complete?: () => void): this;
  /**
   * 淡出动画
   * @param {number} duration 动画时间ms
   * @param {() => void} complete 动画结束回调
   * @default 1000
   */
  fadeOut(duration?: number, complete?: () => void): this;
  /**
   * 图片加载淡入淡出动画
   * @param {string} src 图片加载路径
   * @param {number} duration 动画时间ms
   * @param {boolean} immediate 首次加载时是否需要动画
   * @param {() => void} complete 动画结束回调
   */
  fadeImg(src: string, duration?: number, immediate?: boolean, complete?: () => void): this;
  /**
   * 获取当前淡入的图片路径
   */
  getFadeImg(): string;
  /**
   * 结尾追加html
   * @param html html字符串或dom
   */
  appendHtml(html: Content): this;
  /**
   * 开头追加html
   * @param html html字符串或dom
   */
  prependHtml(html: Content): this;
  /**
   * 挂载数据
   * @param {string} key 键
   * @param {string} val 值
   * @example
   * const dom = SEpg.Util.$('area0_list_0');
   * dom.data('name', 'value');// 内存中设置name="value"
   * dom.data('name');// 获取name的值
   */
  data<T>(key: string, val?: T): T | null;
  /**
   * 设置或获取data属性值
   * @param {string} key 键
   * @param {string} val 值
   * @example
   * const dom = SEpg.Util.$('area0_list_0');
   * dom.pack('name', 'value');// 设置data-name="value"
   * dom.pack('name');// 获取data-name的值
   */
  pack(key: string, val?: string | number): string | null;
  /**
   * 设置或获取dom属性值
   * @param {string} key 键
   * @param {string} val 值
   * @example
   * const dom = SEpg.Util.$('area0_list_0');
   * dom.attr('style', 'left:12px;top:20px');// 设置style样式
   * dom.attr('name');// 获取name属性的值
   */
  attr(key: string, val?: string): string | this;
  /**
   * 设置默认滑动速度
   * @param speed 速度
   */
  defaultSpeed(speed: number): this;
  /**
   * 宽度伸缩动画
   * @param {number} width 目标宽度
   * @param {number} [speed] 速度
   * @param {TTimeFunction} [time_function='ease'] 滑动的速度曲线 
   */
  widthChange(width: number, speed?: number, complete?: () => void, time_function?: TTimeFunction): this;
  /** 滑动开始回调 */
  slideStart?: (() => void) | null;
  /** 滑动结束回调 */
  slideEnd?: (() => void) | null;
  /**
   * 设置dom元素滑动
   * @param {number} distance 滑动距离
   * @param {'h'|'v'} [slideDir] 横向还是纵向(h开头为横向，v开头为纵向，默认v)
   * @param {number} [speed] 速度
   * @param {number} [delay=0] 延迟
   * @param {any} [keepVal] 不动轴的值 传非数值时自动获取
   * @param {TTimeFunction} [time_function='ease'] 滑动的速度曲线
   * @example
   * const dom = SEpg.Util.$('area0_list_0');
   * // dom在竖直方向上按'ease'时间曲线函数移动到translateY=100处，过度时间200ms。
   * dom.slide(100, 'v', 200, 0, false, 'ease');
   */
  slide(distance: number, slideDir?: TScrollDir, speed?: number, delay?: number, keepVal?: any, time_function?: TTimeFunction): this;
  /**
   * 设置dom元素滑动(双轴同时滑动)
   * @param {number} x 横轴距离
   * @param {number} y 纵轴距离
   * @param {number} [speed] 速度
   * @param {number} [delay=0] 延迟
   * @param {TTimeFunction} [time_function='ease'] 滑动的速度曲线
   * @example
   * const dom = SEpg.Util.$('area0_list_0');
   * // dom按'ease'时间曲线函数移动到translateX=100、translateY=100处，过度时间200ms。
   * dom.slide(100, 100, 200, 0, 'ease');
   */
  freeSlide(x: number, y: number, speed?: number, delay?: number, time_function?: TTimeFunction): this;
  /**
   * 轮播图式滑动切换
   * @param {string | ExtendHTMLElement} slideContainer 滑动元素的类名或滑动元素
   * @param {number} [timeout=5000] 滑动间隔(最低1000)
   * @param {number} [speed=500] 滑动速度
   * @example
   * const dom = SEpg.Util.$('text');
   * const banner = dom.bannerSlide('scroll');
   * banner.move();// 开始滚动
   * banner.stop();// 停止滚动
   */
  bannerSlide(slideContainer: string | ExtendHTMLElement, timeout?: number, speed?: number): {
  /** 启用滚动 */ move(): void; /** 停止滚动 */ stop(): void
  };
  /**
   * 获取transform对应坐标轴的translate值（前提使用translate3d）
   * @param {TTranslateDir} [translateDir='x'] 获取的坐标轴
   * @example
   * const dom = SEpg.Util.$('area0_list_0');
   * let translateX = dom.getTranslateVal();// 获取translateX值
   * let translateY = dom.getTranslateVal('y');// 获取translateY值
   * let translateZ = dom.getTranslateVal('z');// 获取translateZ值
   */
  getTranslateVal(translateDir?: TTranslateDir): number;
  /**
   * 获取style某属性值
   * @param {keyof CSSStyleDeclaration} prop 属性
   */
  getStyle(prop: keyof CSSStyleDeclaration): string;
  /** 强制js实现标识 */
  forceJs: boolean;
  /** 焦点元素定位索引 */
  index: number;
  /** 从属的区域控制器实例 */
  area: any;
  /** SafeDOMRect数据 */
  rect: SafeDOMRect | null;
  /** 已扩展标识 */
  _extend_: boolean;
  /** 复制元素标识 */
  _copy_: boolean;
  /** 当前元素所在屏幕序号, 用于处理多屏元素的焦点计算 */
  screen: number;
  /** 定制dom焦点样式 */
  focusClass: string;
  /** 定制dom失焦样式 */
  blurClass: string;
  /** 定制dom驻留样式 */
  selectClass: string;
  /**
   * 强制js实现
   */
  doForceJs(): this;
  /**
   * 取消强制js实现
   */
  undoForceJs(): this;
  /**
   * getBoundingClientRect方法兼容(结果会自动四舍五入)
   */
  getBoundingClientRectSafe(): SafeDOMRect;
  /**
   * 检测当前元素是否在指定视口内(需要完全进入视口)
   * @param {ExtendHTMLElement} viewPoint 视口元素
   */
  enterView(viewPoint?: ExtendHTMLElement): boolean;
  /**
   * 检测当前元素是否进入指定视口(与视口有重叠即可)
   * @param {ExtendHTMLElement} viewPoint 视口元素
   * @param {number} [offset=0] 视口偏移值(在实际的尺寸下的偏移量, 用于做预加载判断)
   * @param {'v' | 'h'} [origin='v'] 重叠方向(一般同页面滑动方向)
   */
  contactView(viewPoint?: ExtendHTMLElement, offset?: number, origin?: 'v' | 'h'): boolean;
  /** 内容置空 */
  empty(): this;
  /** 内容是否为空 */
  isEmpty(): boolean;
  /**
   * 填充元素html内容
   * @param {Content} html 字符串或html元素
   */
  html(html?: Content): string;
  /**
   * 设置动画
   * @param options 动画配置
   * @param time_function 时间函数
   */
  motion(options: AnimateOptions & { zoom?: number }, time_function?: TTimeFunction): this;
  [key: string]: any;
}

B. 使用建议

  1. Emitter: 适用于组件间通信、事件解耦场景
  2. Toast: 适用于消息提示、操作反馈场景
  3. Storage: 适用于数据持久化、用户偏好设置场景
  4. Loader: 适用于异步加载、数据请求等待场景
  5. CycleStack: 适用于页面导航管理、历史记录管理场景
  6. Marquee: 适用于公告、新闻滚动、字幕滚动场景