SwiftUtilityKit

中文 | English | 自动选择语言（GitHub Pages）

Swift 常用转换工具库（默认中文语境）：

• 默认日期上下文：zh_CN + Asia/Shanghai + Gregorian
• 覆盖：单位换算、日期时间、金额、百分比、颜色、字符串校验与格式化、设备与应用信息

• 点击观看：SwiftUtilityKit Demo Video

说明：通过 Swift Package Manager 引入 SDK。

https://github.com/snoux/SwiftUtilityKit

import SwiftUtilityKit // 在代码文件中导入 SDK

说明：以下示例全部使用默认上下文（不传 in: cn）。

let out = try "2026-03-10 08:00:00".dateString(to: .dateMinuteSlash) // 自动识别输入并输出为 yyyy/MM/dd HH:mm

let ref = try "2026-03-10 12:00:00".date(.dateTime) // 解析参考时间
let ok = try "2026-03-09 12:00:00".isYesterday(ref: ref) // 判断目标时间是否是参考时间的昨天

let ref = try "2026-03-10 12:00:00".date(.dateTime) // 解析参考时间
let target = try "2026-03-09 12:00:00".date(.dateTime) // 解析目标时间
let ok = target.isYesterday(ref: ref) // 直接通过 Date 扩展判断昨天

let ref = try "2026-03-10 12:00:00".date(.dateTime) // 参考时间
let in7 = try "2026-03-05 12:00:00".relative(to: ref).withinPast(7, .day) // 目标时间是否在参考时间向前 7 天范围内

let inRange = try "2026-03-10 08:00:00".isBetween("2026-03-10 07:00:00", and: "2026-03-10 09:00:00", format: "yyyy-MM-dd HH:mm:ss") // 判断字符串时间是否在区间内

let ts = try "2026-03-10 08:00:00".timestamp(.dateTime) // 日期字符串转秒级时间戳
let text = try "1704067200".dateStringFromTimestamp(unit: .second, format: "yyyy-MM-dd HH:mm:ss") // 秒级时间戳转日期字符串

let fen = try "12.34".convertMoney(from: .major, to: .minor, currency: .cny) // 人民币元转分 -> 1234
let text = try "1234567.8".formattedMoney(scale: 2, useGrouping: true) // 金额千分位格式化 -> 1,234,567.80

let ratio = try "12.5".percentToRatio() // 百分数 12.5 转比率 0.125

let hex = try "rgba(255,102,0,0.5)".normalizedColorHex(includeAlpha: true) // 颜色字符串标准化为 hex

let phoneOK = "13800138000".isValidChineseMobile // 校验是否中国大陆手机号
let emailOK = "[email protected]".isValidEmail // 校验邮箱格式

let blank = " \n ".isBlank // 判断是否空白字符串
let encoded = "a b&c=1".urlEncoded() // URL 编码
let decoded = "a%20b%26c%3D1".urlDecoded() // URL 解码
let b64 = "SwiftUtilityKit".base64Encoded() // Base64 编码
let raw = "U3dpZnRVdGlsaXR5S2l0".base64Decoded() // Base64 解码

let d = try "2026-03-10 12:34:56".date(.dateTime) // 解析 Date
let start = d.startOfDay() // 当天开始时间 00:00:00
let end = d.endOfDay() // 当天结束时间 23:59:59
let plus7 = d.adding(7, .day) // 日期加 7 天
let sameDay = d.isSameDay(as: Date()) // 是否同一天

let sys = DeviceInfo.systemVersion // 获取系统版本号
let model = DeviceInfo.modelName // 获取设备机型名称
let app = DeviceInfo.appVersionWithBuild // 获取当前 App 版本号 + 构建号
let px = DeviceInfo.pixelResolutionText // 获取屏幕物理分辨率（像素）
let battery = DeviceInfo.batteryPercentageText // 获取当前电池百分比文本
let total = DeviceInfo.totalDiskSpaceText // 获取设备总容量文本
let free = DeviceInfo.freeDiskSpaceText // 获取设备剩余容量文本
let used = DeviceInfo.usedDiskSpaceText // 获取设备已用容量文本

let c = try "31.2304,121.4737".coordinate() // 字符串转坐标（默认纬度,经度）
let text = c.string(order: .longitudeLatitude, fractionDigits: 6) // 坐标转字符串（经度,纬度）
let dict = c.dictionary() // 坐标转字典：["latitude":..., "longitude":...]

说明：DateKit 统一管理“解析/格式化的语言、时区、日历”和“日期格式模式”。

辅助集合：

• DateKit.commonDatePatterns：自动识别输入模式列表（顺序即尝试顺序）
• DateKit.commonDateFormats：自动识别输入格式字符串列表

说明：当原始输入是字符串时，使用这组 API 最方便。

说明：这是日期处理的主入口，支持“明确格式”和“自动识别”两种调用风格。

说明：relative(...) 返回 DateRelativeProxy（中间对象），它保存 target + reference，用于继续做 .isYesterday/.isToday/... 等判断。

说明：业务逻辑层推荐直接用 Date 扩展，调用更自然。

DateRelativeProxy 说明：

• 是什么：相对时间判断对象，内部绑定 target 与 reference
• 何时用：需要连续判断多个相对条件时，减少重复传参
• 属性：isDayBeforeYesterday / isYesterday / isToday / isTomorrow / isLastWeek / isNextWeek / isLastYear / isNextYear
• 方法：matches(_:)（按标签通用判断）
• 方法：withinPast(_:_:,inclusive:)（范围判断）

说明：当时间戳本来就是数值类型时，无需先转字符串。

适用于 BinaryInteger / BinaryFloatingPoint / Decimal：

• convertTimestamp(from:to:)：时间戳单位换算
• toDate(unit:)：时间戳转 Date

说明：仅做同币种单位换算（不涉及汇率），内部使用 Decimal 确保精度。

• cny：人民币
• usd：美元
• eur：欧元
• gbp：英镑
• jpy：日元

• major：主单位（如元/美元）
• tenth：十分位单位（如角）
• minor：百分位单位（如分/美分）

• yuan：元
• jiao：角
• fen：分

• MoneyConversion.convert(_:from:to:currency:)
• MoneyConversion.splitCNY(_:)
• MoneyConversion.mergeCNY(yuan:jiao:fen:)
• MoneyConversion.format(_:scale:useGrouping:locale:)

String / BinaryInteger / BinaryFloatingPoint / Decimal：

• convertMoney(from:to:currency:)
• convertMoneyString(from:to:currency:scale:useGrouping:)
• formattedMoney(scale:useGrouping:)

Decimal：

• splitCNY()

CNYParts：

• toDecimalYuan()

说明：支持“百分数 <-> 比率”双向转换。

• PercentageConversion.percentToRatio(_:)
• PercentageConversion.ratioToPercent(_:)

• String：percentToRatio / ratioToPercent / percentToRatioString / ratioToPercentString
• BinaryInteger：percentToRatio / ratioToPercent
• BinaryFloatingPoint：percentToRatio / ratioToPercent
• Decimal：percentToRatio / ratioToPercent / asPercentString

说明：支持颜色字符串、整数、十六进制与系统颜色对象互转。

• init(red:green:blue:alpha:)
• parse(_:)
• fromRGBString(_:)
• fromPackedInt(_:hasAlpha:)
• hexString(includeAlpha:prefixHash:)
• packedInt(includeAlpha:)

• String：toColorRGBA / normalizedColorHex / colorToPackedInt / toCGColor / toUIColor / toSwiftUIColor
• BinaryInteger：toColorRGBA(hasAlpha:) / toColorHex(hasAlpha:prefixHash:)

• colorRGBA(_:)：字符串直接创建 ColorRGBA
• cgColor(_:) / cgcolor(_:)：字符串直接创建 CGColor
• uiColor(_:) / uicolor(_:)：字符串直接创建 UIColor（UIKit）
• swiftUIColor(_:)：字符串直接创建 SwiftUI.Color

ColorRGBA：

• init(red: CGFloat, green: CGFloat, blue: CGFloat, alpha: CGFloat)
• fromHex(_:)
• cgColor
• init(cgColor:)
• uiColor（UIKit）
• init(uiColor:)（UIKit）
• swiftUIColor（SwiftUI）

UIColor（UIKit）：

• init(_ color: ColorRGBA)
• init(hex:)
• init(rgbString:)
• init(colorString:)
• toColorRGBA()

Color（SwiftUI + UIKit 桥接）：

• toColorRGBA()

说明：用于获取系统版本、设备机型、App 版本和屏幕分辨率等信息（UIKit 平台可用）。

• DeviceInfo.systemName：系统名称（如 iOS）
• DeviceInfo.systemVersion：系统版本号
• DeviceInfo.modelIdentifier：设备机型标识（如 iPhone16,2）
• DeviceInfo.modelName：设备机型名称（如 iPhone 15 Pro Max）
• DeviceInfo.appVersion：App 版本号（CFBundleShortVersionString）
• DeviceInfo.appBuild：App 构建号（CFBundleVersion）
• DeviceInfo.appVersionWithBuild：版本号 + 构建号（如 1.2.3(45)）
• DeviceInfo.logicalResolution：逻辑分辨率（point）
• DeviceInfo.pixelResolution：物理分辨率（pixel）
• DeviceInfo.logicalResolutionText：逻辑分辨率文本（如 393x852 pt）
• DeviceInfo.pixelResolutionText：物理分辨率文本（如 1179x2556 px）
• DeviceInfo.screenScale：屏幕缩放倍数
• DeviceInfo.nativeScale：原生缩放倍数
• DeviceInfo.batteryLevel：电池电量（0...1，不可用时为 nil）
• DeviceInfo.batteryPercentage：电池百分比（0...100，不可用时为 nil）
• DeviceInfo.batteryPercentageText：电池百分比文本（如 80%，不可用时为 未知）
• DeviceInfo.batteryState：电池状态（UIDevice.BatteryState）
• DeviceInfo.batteryStateText：电池状态文本（未知 / 未充电 / 充电中 / 已充满）
• DeviceInfo.totalDiskSpace：设备总容量（字节）
• DeviceInfo.freeDiskSpace：设备剩余容量（字节）
• DeviceInfo.usedDiskSpace：设备已用容量（字节）
• DeviceInfo.totalDiskSpaceText：设备总容量文本（如 256 GB）
• DeviceInfo.freeDiskSpaceText：设备剩余容量文本（如 120 GB）
• DeviceInfo.usedDiskSpaceText：设备已用容量文本（如 136 GB）

• UIDevice.utilityModelIdentifier：设备机型标识
• UIDevice.utilityModelName：设备机型名称
• UIScreen.utilityPixelResolution：屏幕像素分辨率

• 机型映射独立维护在：Sources/SwiftUtilityKit/Resources/AppleDeviceList.txt
• 文件格式：identifier|name（一行一条，# 开头为注释）
• 未命中映射时会自动回退为原始机型标识

说明：用于输入合法性校验和展示脱敏。

最简示例：

let phoneOK = "13800138000".isValidChineseMobile // 校验大陆手机号
let emailOK = "[email protected]".isValidEmail // 校验邮箱
let urlOK = "https://example.com/path?a=1".isValidURL // 校验 URL
let ipv6OK = "2408:8400:9800:31d3:4ff7:f6d2:69f8:77b3".isValidIPv6 // 校验 IPv6
let cardOK = "4111111111111111".isValidBankCardNumber // 校验银行卡号（Luhn）
let idOK = "11010519491231002X".isValidChineseIDCard // 校验身份证号（含校验码）

let cardText = "6222021234567890123".formattedBankCardNumber() // 银行卡分组格式化
let phoneText = "13800138000".formattedChineseMobile() // 手机号格式化为 XXX-XXXX-XXXX
let phoneMask = "13800138000".maskedChineseMobile() // 手机号脱敏为 XXX****XXXX
let idMask = "11010519491231002X".maskedChineseIDCard() // 身份证脱敏为 前6 + **** + 后4

• isValidChineseMobile
• isValidURL
• isValidEmail
• isValidIPv6
• isValidBankCardNumber
• isValidChineseIDCard

• formattedBankCardNumber(separator:)
• formattedChineseMobile(separator:)
• maskedChineseMobile(mask:)
• maskedChineseIDCard(mask:)

说明：在可导入 CoreLocation 的平台，支持 CLLocationCoordinate2D 与字符串、元组、字典互转。

• CoordinateOrder.latitudeLongitude：纬度,经度
• CoordinateOrder.longitudeLatitude：经度,纬度

• CLLocationCoordinate2D.parse(_:separator:order:)
• CLLocationCoordinate2D.make(_:order:)
• CLLocationCoordinate2D.make(from:)
• isValidCoordinate
• string(order:separator:fractionDigits:)
• tuple(order:)
• dictionary()
• swappedLatLon()

• coordinate(separator:order:)

说明：当数据已是数值类型时，直接调用数值扩展更高效。

• 单位：convertLength / convertWeight / convertArea / convertVolume / convertTime / convertTemperature / convertSpeed
• 时间关系：compareTime / timeDifference
• 进制：convertRadix(to:uppercase:)
• 中文大写：toChineseUppercaseNumber / toChineseUppercaseCurrency
• 颜色：toColorRGBA / toColorHex

• 单位：convertLength / convertWeight / convertArea / convertVolume / convertTime / convertTemperature / convertSpeed
• 时间关系：compareTime / timeDifference
• 中文大写：toChineseUppercaseNumber / toChineseUppercaseCurrency

• 单位：convertLength / convertWeight / convertArea / convertVolume / convertTime / convertTemperature / convertSpeed
• 时间关系：compareTime / timeDifference
• 中文大写：toChineseUppercaseNumber / toChineseUppercaseCurrency

• picometer：皮米
• nanometer：纳米
• micrometer：微米
• millimeter：毫米
• centimeter：厘米
• decimeter：分米
• meter：米
• kilometer：千米
• nauticalMile：海里
• mile：英里
• furlong：弗隆
• yard：码
• foot：英尺
• inch：英寸
• li：里
• zhang：丈
• chi：尺
• cun：寸
• fen：分
• liSmall：厘
• hao：毫
• lightYear：光年

• microgram：微克
• milligram：毫克
• gram：克
• kilogram：千克
• ton：吨
• ounce：盎司
• pound：磅
• stone：英石
• jin：斤
• liang：两
• qian：钱

• squareMillimeter：平方毫米
• squareCentimeter：平方厘米
• squareDecimeter：平方分米
• squareMeter：平方米
• squareKilometer：平方千米
• hectare：公顷
• acre：英亩
• squareFoot：平方英尺
• squareInch：平方英寸
• mu：亩

• milliliter：毫升
• liter：升
• cubicMeter：立方米
• teaspoon：茶匙
• tablespoon：汤匙
• cup：杯
• pint：品脱
• gallon：加仑
• cubicCentimeter：立方厘米
• cubicInch：立方英寸

• nanosecond：纳秒
• microsecond：微秒
• millisecond：毫秒
• second：秒
• minute：分钟
• hour：小时
• day：天
• week：周

• celsius：摄氏度
• fahrenheit：华氏度
• kelvin：开尔文

• meterPerSecond：米每秒
• kilometerPerHour：千米每小时
• milePerHour：英里每小时
• knot：节
• footPerSecond：英尺每秒

• second：秒级时间戳（如 1704067200）
• millisecond：毫秒级时间戳（如 1704067200000）

• second：按秒输出差值
• minute：按分钟输出差值
• hour：按小时输出差值
• day：按天输出差值（24 小时）

• dayBeforeYesterday：前天
• yesterday：昨天
• today：今天
• tomorrow：明天
• lastWeek：上周
• nextWeek：下周
• lastYear：去年
• nextYear：明年

• invalidNumber：无效数字
• invalidBase：无效进制范围
• invalidRadixValue：进制值不合法
• overflow：溢出
• invalidChineseNumeral：中文数字不合法
• invalidColor：颜色不合法
• invalidDate：日期不合法
• invalidCoordinate：坐标不合法
• invalidMoneyUnit：币种与金额单位不匹配

• 单位名称本地化：localizedName(locale:)
• 错误信息本地化：ConversionError.errorDescription