格式化

Number

1. formatNumber

整数格式化，默认在加上单位后保留一位小数（e.g. 1.3万, 1.4亿）

与 formatFloat 不同的是，本函数的输出结果是一个整数，即不会出现 1.33330万 的情况

定义：

export declare const formatNumber: (num: number, fixed?: number) => string;

2. formatFloat

浮点数格式化

定义：

export declare const formatFloat: (num: number, fixed?: number) => string;

3. formatDistance

距离格式化（e.g. 1.3, 1.4km）

定义：

export declare const formatDistance: (num: number, fixed?: number) => string;

4. formatNumberCN

亿级阿拉伯数字整数转为中文数字

定义：

export interface FormatNumberCNOptions {
    oneTen?: boolean;
    cnNumbers?: string;
}
export declare const formatNumberCN: (num: number, opts?: FormatNumberCNOptions | undefined) => string;

用法：

test('15', () => expect(formatNumberCN(15)).toBe('十五'))
test('15 oneTen', () => expect(formatNumberCN(15, { oneTen: true })).toBe('一十五'))
test('421751012', () => expect(formatNumberCN(421751012, { oneTen: true, cnNumbers: '零壹贰叁肆伍陆柒捌玖拾佰仟万亿' }))
    .toBe('肆亿贰仟壹佰柒拾伍万壹仟零壹拾贰'))

Date

DateMeta

本模块各种转化的核心数据结构

• toDateMeta: 负责将各类数据转成 DateMeta
• standardDateMeta: 负责处理进位
• formatDateMeta: 【核心】格式化函数

定义：

export interface DateMeta {
    years: number;
    months: number;
    days: number;
    hours: number;
    minutes: number;
    seconds: number;
    milliseconds: number;
}
export declare type DateMetaKeys = keyof DateMeta;
export declare type Duration = Partial<DateMeta>;

export declare const toDateMeta: (time?: string | number | Date | null | undefined) => {
    years: number;
    months: number;
    days: number;
    hours: number;
    minutes: number;
    seconds: number;
    milliseconds: number;
};
export declare const standardDateMeta: (d?: Partial<DateMeta> | undefined) => DateMeta;
export declare const formatDateMeta: (date: DateMeta | number, fmt?: string) => string;

// https://date-fns.org/v2.22.1/docs/format
// 支持以下部分
// y year
// M month
// d Day of month
// [todo] D Day of year
// [todo] a AM/PM
// [todo] h Hour [1-12]
// H Hour [0-23]
// [todo] K Hour [0-11]
// [todo] k Hour [1-24]
// m Minute
// s Second
// S Fraction of second
// t Seconds timestamp
// T Milliseconds timestamp

Format

1. formatDate

格式化日期时间

定义：

export declare const formatDate: (time?: string | number | Date | null | undefined, fmt?: string) => string;

用法：

formatDate(1624519406447) // '2021/06/24 15:23:26
formatDate(1624519406447， 'yy.MM.dd') // '21.06.24

2. slugFormatDuration

格式化持续时间

与 date-fns 的 formatDuration 不同之处在于，本函数将以指定模板格式化，且会执行进位

定义：

export declare const slugFormatDuration: (d?: Partial<DateMeta> | undefined, fmt?: string) => string;

用法：

slugFormatDuration({ hours: 1, minutes: 66 }, 'H:m') // '2:6'

3. formatDuration

格式化持续时间

参考：date-fns formatDuration

定义：

export declare const formatDuration: (d?: Partial<DateMeta> | undefined, opts?: {
    format?: ("years" | "months" | "days" | "hours" | "minutes" | "seconds" | "milliseconds")[] | undefined;
    zero?: boolean | undefined;
    delimiter?: string | undefined;
} | undefined) => string;

用法：

formatDuration({ years: 2, months: 9 }, { delimiter: ', ' }) // '2 年, 9 月'

4. slugFormatDateDistance

格式化时间间隔，适合倒计时使用

定义：

export interface SlugFormatDateDistance {
    fmt?: string;
    beforeFmt?: string;
}
export declare const slugFormatDateDistance: (date?: string | number | Date | null | undefined, baseDate?: string | number | Date | null | undefined, opts?: SlugFormatDateDistance | undefined) => string;

用法：

const t1 = 1624519406447
const t2 = 1724526892846

slugFormatDateDistance(t2, t1, { fmt: 'dd 天 HH:mm:ss.SSS 后' })
// '1157 天 11:51:26.399 后'

5. formatDateDistanceStrict

格式化时间间隔，适合展示发布时间等信息

参考：date-fns formatDistanceStrict

定义：

export declare type DateRoundingMethod = typeof Math.round;
export declare const formatDateDistanceStrict: (date?: string | number | Date | null | undefined, baseDate?: string | number | Date | null | undefined, opts?: {
    addSuffix?: boolean | undefined;
    unit?: "years" | "months" | "days" | "hours" | "minutes" | "seconds" | "milliseconds" | undefined;
    roundingMethod?: ((x: number) => number) | "floor" | "ceil" | "round" | undefined;
} | undefined) => string;

用法：

formatDateDistanceStrict(
  new Date(1986, 3, 4, 10, 33, 1),
  new Date(1986, 3, 4, 10, 32, 0),
) // '1 分钟'

formatDateDistanceStrict(
  new Date(1986, 3, 4, 10, 33, 1),
  new Date(1986, 3, 4, 10, 32, 0),
  { addSuffix: true }
) // '1 分钟后'

formatDateDistanceStrict(
  new Date(1986, 3, 4, 10, 32, 0),
  new Date(1986, 3, 4, 10, 33, 1),
  { addSuffix: true }
) // '1 分钟前'

formatDateDistanceStrict() // '0 秒'

// 注意，有别于 date-fns，并非显示 '0 秒前'
formatDateDistanceStrict(0,0, { addSuffix: true }) // '现在'