format

格式化工具，提供日期格式化参数、模板变量替换、插件模板解析、日期格式化、文件大小格式化和压缩率计算功能。

导入方式

// 子模块独立导入（推荐）
import { getDateFormatParams, parseTemplate, parseTemplateWithDelimiter, parsePluginTemplate, formatDate, formatFileSize, calcRatio } from '@meng-xi/vite-plugin/common/format'
import type { DateFormatOptions } from '@meng-xi/vite-plugin/common/format'

// barrel 导入
import { getDateFormatParams, parseTemplate, parseTemplateWithDelimiter, parsePluginTemplate, formatDate, formatFileSize, calcRatio } from '@meng-xi/vite-plugin/common'
import type { DateFormatOptions } from '@meng-xi/vite-plugin/common'

类型导出

DateFormatOptions

日期格式化参数接口。

interface DateFormatOptions {
	[key: string]: string // 支持任意键名，便于自定义占位符
	YYYY: string // 四位年份
	YY: string   // 两位年份
	MM: string   // 两位月份
	DD: string   // 两位日期
	HH: string   // 两位小时（24小时制）
	mm: string   // 两位分钟
	ss: string   // 两位秒数
	SSS: string  // 三位毫秒
	timestamp: string // 时间戳（毫秒）
}

---

getDateFormatParams

获取日期格式化参数对象。

function getDateFormatParams(date?: Date): DateFormatOptions

参数

参数	类型	默认值	说明
date	Date	new Date()	日期对象

返回值

DateFormatOptions - 日期格式化参数对象

示例

const params = getDateFormatParams(new Date())
// { YYYY: '2026', MM: '02', DD: '03', HH: '15', mm: '30', ss: '00', ... }

---

parseTemplate

替换模板字符串中的 {{key}} 占位符。

function parseTemplate(template: string, values: Record<string, string>): string

参数

参数	类型	说明
template	string	包含 {{key}} 占位符的模板字符串
values	Record<string, string>	占位符键值映射，支持合并多组变量（后者覆盖前者）

返回值

string - 替换占位符后的字符串

说明

• 键名中的正则特殊字符会被自动转义
• 值中的 $ 也会被安全处理，避免正则替换问题

示例

parseTemplate('Hello {{name}}!', { name: 'World' })
// 'Hello World!'

parseTemplate('{{YYYY}}-{{MM}}-{{DD}}', getDateFormatParams())
// '2026-06-06'

---

parseTemplateWithDelimiter

替换模板字符串中的变量占位符（自定义分隔符），是 parseTemplate 的通用版本。

function parseTemplateWithDelimiter(
  template: string,
  values: Record<string, string>,
  leftDelimiter?: string,
  rightDelimiter?: string
): string

参数

参数	类型	默认值	说明
template	string	-	包含占位符的模板字符串
values	Record<string, string>	-	占位符键值映射
leftDelimiter	string	'{{'	左分隔符
rightDelimiter	string	'}}'	右分隔符

返回值

string - 替换占位符后的字符串

说明

• 通用模板解析函数，支持自定义分隔符
• 键名中的正则特殊字符会被自动转义
• 值中的 $ 也会被安全处理，避免正则替换问题

示例

parseTemplateWithDelimiter('Hello {{name}}!', { name: 'World' })
// 'Hello World!'

parseTemplateWithDelimiter('Hello {name}!', { name: 'World' }, '{', '}')
// 'Hello World!'

// formatDate 内部使用此函数，分隔符为 { 和 }
parseTemplateWithDelimiter('{YYYY}-{MM}-{DD}', getDateFormatParams(), '{', '}')
// '2026-06-06'

---

formatDate

格式化日期字符串，使用 {key} 单花括号占位符。

function formatDate(date: Date, format: string): string

参数

参数	类型	说明
date	Date	日期对象
format	string	格式字符串，支持 {YYYY}、{MM}、{DD}、{HH}、{mm}、{ss} 等占位符

返回值

string - 格式化后的日期字符串

示例

formatDate(new Date(), '{YYYY}-{MM}-{DD}T{HH}:{mm}:{ss}')
// '2026-06-06T15:30:00'

formatDate(new Date(), '{YYYY}.{MM}.{DD}')
// '2026.06.06'

---

parsePluginTemplate

解析插件文件头模板，支持日期、自定义字段、插件名称和版本占位符。主要供 generateRouter 的 headerTemplate 使用。

function parsePluginTemplate(
  template: string,
  params: {
    name?: string
    version?: string
    customFields?: Record<string, string>
    defaultDateFormat?: string
  }
): string

参数

参数	类型	说明
template	string	模板字符串
params	object	解析参数
params.name	string	插件名称，替换 {name}
params.version	string	插件版本，替换 {version}
params.customFields	Record<string, string>	自定义字段键值对，替换 {custom:KEY}
params.defaultDateFormat	string	默认日期格式，默认 YYYY-MM-DD HH:mm:ss

返回值

string - 解析后的字符串

支持的占位符

占位符	说明	示例
{date}	默认格式日期时间	2026-06-25 14:30:00
{date:FORMAT}	自定义格式日期（FORMAT 为裸占位符，如 YYYY-MM-DD）	{date:YYYY/MM/DD} → 2026/06/25
{custom:KEY}	自定义字段，未提供时保留原占位符	{custom:author} → MengXi Studio
{name}	插件名称	generate-router
{version}	插件版本	0.2.7

日期格式说明

{date:FORMAT} 中的 FORMAT 使用裸占位符（如 YYYY-MM-DD），函数内部会自动将其包裹为大括号形式再调用 formatDate，因此无需手动写成 {YYYY}-{MM}-{DD}。

示例

parsePluginTemplate('{name} v{version} ({date:YYYY-MM-DD})', {
  name: 'generate-router',
  version: '0.2.7',
  customFields: { author: 'MengXi Studio' }
})
// 'generate-router v0.2.7 (2026-06-25)'

parsePluginTemplate('{custom:author} - {date}', {
  customFields: { author: 'MengXi Studio' }
})
// 'MengXi Studio - 2026-06-25 14:30:00'

// customFields 中未提供的键保留原占位符
parsePluginTemplate('{custom:author}', {})
// '{custom:author}'

---

formatFileSize

将字节数格式化为人类可读的文件大小字符串。

function formatFileSize(bytes: number): string

参数

参数	类型	说明
bytes	number	文件大小（字节）

返回值

string - 格式化后的文件大小字符串

转换规则

范围	格式	示例
小于 1KB	xB	512B
小于 1MB	x.xKB	1.5KB
大于等于 1MB	x.xxMB	2.35MB

示例

formatFileSize(512) // '512B'
formatFileSize(1536) // '1.5KB'
formatFileSize(2461726) // '2.35MB'

---

calcRatio

计算压缩率百分比。

function calcRatio(originalSize: number, compressedSize: number): number

参数

参数	类型	说明
originalSize	number	原始大小（字节）
compressedSize	number	压缩后大小（字节）

返回值

number - 压缩率百分比（0-100），如 65.2 表示体积减少 65.2%

说明

• 计算公式：(1 - compressedSize / originalSize) * 100，保留一位小数
• 当 originalSize 为 0 时返回 0，避免除零错误

示例

calcRatio(10000, 6000)  // 40.0
calcRatio(10000, 10000) // 0
calcRatio(0, 0)         // 0