title: Compass 工具函数库 description: Compass 通用工具函数库 permalink: /utils/ headerDepth: 4

@compass-aiden/utils

工具函数库

快速上手

npm install @compass-aiden/utils 安装依赖

ESModule 环境使用:

import { VERSION } from '@compass-aiden/utils';
console.log('Current utils version is %s', VERSION);

Commonjs 环境使用:

const { VERSION } = require('@compass-aiden/utils');
console.log('Current utils version is %s', VERSION);

UMD 环境使用:

<script src="https://cdn.jsdelivr.net/npm/@compass-aiden/utils/dist/main.umd.min.js"></script>
<script>
  const { VERSION } = window.CompassUtils;
  console.log('Current utils version is %s', VERSION);
</script>

可用实用程序列表

String

encodePhoneNumber

版本:

1.6.3

描述:

加密手机号码,脱敏处理

类型:

type encodePhoneNumber = (
  /** 手机号码或国际号码 */
  phone: string,
  /** 配置 */
  option?: {
    /**
     * @description 加密字符的长度
     * @default 4
     */
    encodeLength?: number;
    /**
     * @description 向右偏移长度,影响加密块离左边的距离
     * @default 3
     */
    offsetLength?: number;
    /**
     * @description 是否为国际号码
     * @default false
     */
    isCountry?: boolean;
    /**
     * @description 国际区号后的分割符, 如 +86 176的分割符为' '
     * @default ' '
     */
    countryAfterSymbol?: string;
    /**
     * @description 掩码的替换字符
     * @default *
     */
    maskChar?: string;
  },
) => string;

示例:

encodePhoneNumber('13533334444'); // => 135****4444
encodePhoneNumber('+86 13533334444', { isCountry: true }); // => +86 135****4444

replaceVariablesInString

版本:

1.6.3

描述:

替换字符串中包裹起来的变量

类型:

type replaceVariablesInString = (
  /** 字符串模板 */
  templateString: string,
  /** 参数对象 */
  params: Record<string, string>,
) => string;

示例:

const str = 'This is test {{ test }} string.';
replaceVariablesInString(str, { test: 'hello' }); // => 'This is test hello string.'

Function

promiseTask

版本:

1.6.3

描述:

异步事务处理, 捕获异常不阻塞程序

类型:

type promiseTask = <Result = unknown, ExtraProperty extends object = object>(
  /**
   * @description 异步任务
   */
  promise: Promise<Result>,
  /**
   * @description 将数据属性额外附加在错误信息的属性内
   */
  errorExt?: ExtraProperty,
) => Promise<[(Error & ExtraProperty) | Error | null, Result | null]>;

成功时返回[null, Result],失败则返回[(Error & ExtraProperty) | Error, null]

示例:

const asyncTask = Promise.all([]);
const asyncTask2 = Promise.all([]);
async function invoke() {
  const [error, result] = await promiseTask(asyncTask);
  if (error) {
    // handle error
    return;
  }
  // handle result

  const [error2, result2] = await promiseTask(asyncTask2, { code: 'custom_error' });
  if (error2?.code === 'custom_error') {
    // handle custom error
    return;
  }
  if (result2) {
    // handle result
  }
}
invoke();

Date

formatDate

版本:

1.7.0

描述:

时间格式化

类型:

/**
 * @description 时间格式化
 * @param date
 * @param format 格式化字符串; YYYY-年, MM 月, DD 日, hh 时, mm 分, ss 秒, SSS 毫秒
 * @param [option] 配置项
 * @param [option.isPadStart=true] 是否填充字符
 * @param [option.padSymbol='0'] 填充字符
 */
declare function formatDate(
  date?: string | number | Date,
  format?: string,
  option?: {
    isPadStart?: boolean;
    padSymbol?: string;
  },
): string;

示例:

import { formatDate } from '@compass-aiden/utils';

formatDate(); // 返回当前时间,格式为 'YYYY-MM-DD hh:mm:ss'
formatDate('2020/03/12'); // 指定可被Date处理的时间字符串,格式为 'YYYY-MM-DD hh:mm:ss'
formatDate(Date.now(), 'YYYY/MM/DD'); // 指定可被Date处理的时间戳,格式为 'YYYY/MM/DD'

Class

ThemeManager

版本:

1.6.2

描述:

基于 CSS variables 与 DOM 的主题管理器

类型:

type ThemeVariables = Record<string, string | number>;
type TMToggleCallback = (themeName: string | undefined, themeData: ThemeVariables | null) => void;
interface TMConstructor {
  /**
   * @description 主题变量挂载的根节点
   * @default 'html'
   * @example
   *   '#id', '.class', document.querySelector('.anyElement')
   */
  root?: string | Element | null;
  /** 会被各主题继承的公共主题变量 */
  baseVariables?: ThemeVariables;
  hooks?: {
    /** 切换主题后触发, 当置为空,不应用任何主题时传入的是 (undefined, null) => void */
    afterToggle?: TMToggleCallback;
    /** 系统主题变更后触发 */
    afterSystemThemeChange?: (systemTheme: 'light' | 'dark') => void;
  };
  /**
   * @description 是否禁用 在未设置主题或主题为 default 情况下自动跟随系统主题
   * @todo 自动跟随系统主题时,会自动应用名为 light 或 dark 对应的主题数据,不存在则不应用主题
   */
  disableFollowSystemTheme?: boolean;
}
declare class ThemeManager {
  /** 当前系统主题 */
  systemTheme: 'light' | 'dark';
  constructor(opt: TMConstructor);
  /** 注册主题 */
  register(themeName: string, themeData: ThemeVariables): this;
  /** 取消注册主题 */
  unregister(themeName: string): this;
  /** 切换主题 */
  toggle(themeName?: string): this;
  /** 获取当前主题 */
  getCurrentTheme(): string | null;
  /** 获取主题数据 */
  getThemeData(themeName?: string): ThemeVariables | null;
  /** 注销主题数据 */
  destroy(): void;
}

示例:

const theme = new ThemeManager({
  baseVariables: { '--scope-font-color': '#212121' }, // 声明基础的公共变量,被所有注册主题继承
});
// 主题注册
theme
  .register('light', {
    '--scope-page-background-color': '#FFFFFF',
  })
  .register('dark', {
    '--scope-page-background-color': 'black',
    '--scope-font-color': '#FFFFFF',
  });
theme.toggle('light'); // 切换light主题
theme.toggle(); // 切换为空,不应用任何主题,或指定为'default',且未使用disableFollowSystemTheme时自动跟随主题
theme.getCurrentTheme(); // 获取当前使用的主题标识, 例如: 'light'
theme.getThemeData(); // 返回当前使用主题的数据
theme.getThemeData('dark'); // 获取指定主题变量,不提供参数,则默认返回当前使用主题的数据
theme.unregister('purple'); // 移除已注册的主题
theme.destroy(); // 移除主题管理器,释放内部引用资源

Logger

版本:

1.7.0

描述:

日志记录器

类型:

/** 日志配置选项 */
interface LoggerOption {
  /** 业务域标题 */
  subject: string;
  /** 日志输出级别, debug级别最低,error级别最高,大于等于指定级别均会打印日志 */
  logLevel: 'debug' | 'log' | 'info' | 'success' | 'warn' | 'error';
  /** 标题前缀 */
  prefix: string;
  /** 标题后缀 */
  suffix: string;
  /** 日志格式化字符串 */
  dateFormat: string | boolean;
  /** 日期不足位数是否补0 */
  isDatePadZero: boolean;
  /** 各日志样式 */
  styles: {
    debug: string;
    log: string;
    info: string;
    success: string;
    warn: string;
    error: string;
  };
  /** 打印后的hook函数,可以用来自行实现日志堆栈或node写日志文件 */
  afterPrintln?: (...args: unknown[]) => void;
}
/**
 * @description 日志记录器
 */
declare class Logger {
  static config: LoggerOption;
  config: LoggerOption;
  static updateConfig(option?: Partial<LoggerOption>): void;
  updateConfig(option?: Partial<LoggerOption>): void;
  static debug(...args: unknown[]): void;
  debug(...args: unknown[]): void;
  static log(...args: unknown[]): void;
  log(...args: unknown[]): void;
  static info(...args: unknown[]): void;
  info(...args: unknown[]): void;
  static success(...args: unknown[]): void;
  success(...args: unknown[]): void;
  static warn(...args: unknown[]): void;
  warn(...args: unknown[]): void;
  static error(...args: unknown[]): void;
  error(...args: unknown[]): void;
}

示例:

import { Logger } from '@compass-aiden/utils';
// 单例模式使用
console.log(Logger.config); // 默认配置项
Logger.config.logLevel = 'debug'; // 修改单个配置
Logger.updateConfig({
  logLevel: 'debug',
  dateFormat: 'YYYY-MM-DD hh:mm:ss:SSS',
}); // 批量修改配置
Logger.debug('Hello world');
Logger.log('Hello world');
Logger.info('Hello world');
Logger.success('Hello world');
Logger.warn('Hello world');
Logger.error('Hello world');

// 多例模式使用
const loggerMulti = new Logger();
console.log(loggerMulti.config); // 默认配置项
loggerMulti.config.logLevel = 'debug'; // 修改单个配置
loggerMulti.updateConfig({
  subject: 'Aiden2',
  logLevel: 'debug',
  dateFormat: 'YYYY-MM-DD hh:mm:ss',
}); // 批量修改配置
loggerMulti.debug('Hello world');
loggerMulti.log('Hello world');
loggerMulti.info('Hello world');
loggerMulti.success('Hello world');
loggerMulti.warn('Hello world');
loggerMulti.error('Hello world');

Util

compareVersion

版本:

1.6.3

描述:

比较两个版本的大小

类型:

(currentVersion: string, comparedVersion: string, trimSymbolPattern?: RegExp): 1 | -1 | 0

currentVersion 当前版本
comparedVersion 比较的版本
trimSymbolPattern 可选, 为正则表达式,符合条件的字符在移除后进行比较,默认匹配 v 字符

返回值:

1 大于比较版本;

-1 小于比较版本;

0 等于比较版本.

示例:

import { compareVersion } from '@compass-aiden/utils';

compareVersion('v1.0.0', '2.0.0'); // => -1
compareVersion('a2.0.0', 'B1.0.0', /a|b/gi); // => 1
compareVersion('v1.0.0', 'V1.0.0'); // => 0

downloadFile

版本:

1.6.3

描述:

文件下载方法

类型:

(data: BlobPart, filename: string, blobOption: BlobPropertyBag): void

data 可被 Blob 处理的数据
filename 指定的文件名
blobOption blob 处理 data 时的配置选项

示例:

downloadFile(excelData, 'example.xlsx');

Properties

VERSION

版本:

1.6.3

描述:

当前使用的 @compass-aiden/utils 版本

类型:

string

示例:

import { VERSION } from '@compass-aiden/utils';

console.log('Current utils version is %s', VERSION);

@compass-aiden/utils

title: Compass 工具函数库 description: Compass 通用工具函数库 permalink: /utils/ headerDepth: 4

@compass-aiden/utils

快速上手

可用实用程序列表

String

encodePhoneNumber

replaceVariablesInString

Function

promiseTask

Date

formatDate

Class

ThemeManager

Logger

Util

compareVersion

downloadFile

Properties

VERSION

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

@compass-aiden/utils

title: Compass 工具函数库 description: Compass 通用工具函数库 permalink: /utils/ headerDepth: 4

@compass-aiden/utils

快速上手

可用实用程序列表

String

encodePhoneNumber

replaceVariablesInString

Function

promiseTask

Date

formatDate

Class

ThemeManager

Logger

Util

compareVersion

downloadFile

Properties

VERSION

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads