Swift 常用转换工具库默认中文语境默认日期上下文zh_CN Asia/Shanghai Gregorian覆盖单位换算、日期时间、金额、百分比、颜色、字符串校验与格式化、设备与应用信息1. 安装SPM说明通过 Swift Package Manager 引入 SDK。https://github.com/snoux/SwiftUtilityKitimportSwiftUtilityKit// 在代码文件中导入 SDK2. 最简场景调用说明以下示例全部使用默认上下文不传in: cn。2.1 日期格式转换letouttry2026-03-10 08:00:00.dateString(to:.dateMinuteSlash)// 自动识别输入并输出为 yyyy/MM/dd HH:mm2.2 判断是不是昨天String 直调letreftry2026-03-10 12:00:00.date(.dateTime)// 解析参考时间letoktry2026-03-09 12:00:00.isYesterday(ref:ref)// 判断目标时间是否是参考时间的昨天2.3 判断是不是昨天Date 直调letreftry2026-03-10 12:00:00.date(.dateTime)// 解析参考时间lettargettry2026-03-09 12:00:00.date(.dateTime)// 解析目标时间letoktarget.isYesterday(ref:ref)// 直接通过 Date 扩展判断昨天2.4 判断 7 天内letreftry2026-03-10 12:00:00.date(.dateTime)// 参考时间letin7try2026-03-05 12:00:00.relative(to:ref).withinPast(7,.day)// 目标时间是否在参考时间向前 7 天范围内2.5 判断区间letinRangetry2026-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)// 判断字符串时间是否在区间内2.6 时间戳互转lettstry2026-03-10 08:00:00.timestamp(.dateTime)// 日期字符串转秒级时间戳lettexttry1704067200.dateStringFromTimestamp(unit:.second,format:yyyy-MM-dd HH:mm:ss)// 秒级时间戳转日期字符串2.7 金额换算letfentry12.34.convertMoney(from:.major,to:.minor,currency:.cny)// 人民币元转分 - 12342.8 百分比换算letratiotry12.5.percentToRatio()// 百分数 12.5 转比率 0.1252.9 颜色转换lethextryrgba(255,102,0,0.5).normalizedColorHex(includeAlpha:true)// 颜色字符串标准化为 hex2.10 字符串校验letphoneOK13800138000.isValidChineseMobile// 校验是否中国大陆手机号letemailOKdemoexample.com.isValidEmail// 校验邮箱格式2.11 常用字符串扩展letblank \n .isBlank// 判断是否空白字符串letencodeda bc1.urlEncoded()// URL 编码letdecodeda%20b%26c%3D1.urlDecoded()// URL 解码letb64SwiftUtilityKit.base64Encoded()// Base64 编码letrawU3dpZnRVdGlsaXR5S2l0.base64Decoded()// Base64 解码2.12 常用 Date 扩展letdtry2026-03-10 12:34:56.date(.dateTime)// 解析 Dateletstartd.startOfDay()// 当天开始时间 00:00:00letendd.endOfDay()// 当天结束时间 23:59:59letplus7d.adding(7,.day)// 日期加 7 天letsameDayd.isSameDay(as:Date())// 是否同一天2.13 设备与应用信息letsysDeviceInfo.systemVersion// 获取系统版本号letmodelDeviceInfo.modelName// 获取设备机型名称letappDeviceInfo.appVersionWithBuild// 获取当前 App 版本号 构建号letpxDeviceInfo.pixelResolutionText// 获取屏幕物理分辨率像素3. DateKit上下文与日期模式说明DateKit 统一管理“解析/格式化的语言、时区、日历”和“日期格式模式”。3.1 上下文类型DateKit.ContextAPI说明DateKit.defaultContext默认上下文zh_CN Asia/Shanghai GregorianDateKit.Context.cn中文预设上下文DateKit.Context(locale:timeZone:calendar:)自定义上下文3.2 日期模式枚举DateKit.Patterncase格式说明dateTimeyyyy-MM-dd HH:mm:ss常用秒级日期时间dateTimeSlashyyyy/MM/dd HH:mm:ss斜杠版秒级日期时间dateMinuteyyyy-MM-dd HH:mm分钟级日期时间dateMinuteSlashyyyy/MM/dd HH:mm斜杠版分钟级日期时间dateyyyy-MM-dd横杠日期dateSlashyyyy/MM/dd斜杠日期compactDateTimeyyyyMMddHHmmss紧凑日期时间compactDateyyyyMMdd紧凑日期iso8601yyyy-MM-ddTHH:mm:ssZISO8601 秒级iso8601Millisyyyy-MM-ddTHH:mm:ss.SSSZISO8601 毫秒级辅助集合DateKit.commonDatePatterns自动识别输入模式列表顺序即尝试顺序DateKit.commonDateFormats自动识别输入格式字符串列表4. String单位换算与基础转换StringConversion.swift说明当原始输入是字符串时使用这组 API 最方便。API说明convertLength(from:to:)长度换算convertWeight(from:to:)重量换算convertArea(from:to:)面积换算convertVolume(from:to:)体积换算convertTime(from:to:)时间换算compareTime(with:selfUnit:otherUnit:)比较两个时间值timeDifference(to:selfUnit:otherUnit:resultUnit:)计算两个时间值差值other - selfconvertTemperature(from:to:)温度换算convertSpeed(from:to:)速度换算convertRadix(from:to:uppercase:)字符串进制换算2…36toChineseUppercaseNumber()数字转中文大写数字toChineseUppercaseCurrency()数字转中文金额大写chineseUppercaseToDecimal()中文大写转十进制toColorRGBA()颜色字符串转 RGBAnormalizedColorHex(includeAlpha:prefixHash:)颜色字符串转标准 hexcolorToPackedInt(includeAlpha:)颜色字符串转整数颜色值5. String日期 DSLStringUtility.swift说明这是日期处理的主入口支持“明确格式”和“自动识别”两种调用风格。5.1 解析API说明date(_ format: String)按格式解析date(_ pattern: DateKit.Pattern)按内置模式解析date(_ formats: [String])按多个格式依次尝试date(_ patterns: [DateKit.Pattern])按多个模式依次尝试date(patterns:)自动识别解析5.2 格式转换API说明dateString(from:to:)String输入格式 - 输出格式dateString(from:to:)Pattern输入模式 - 输出模式dateString(to:inputFormats:)自动识别输入格式后输出dateString(to:inputPatterns:)自动识别输入模式后输出5.3 比较与差值API说明dateCompare(with:format:)比较两个日期字符串dateDistance(to:format:unit:)计算日期差值other - self5.4 时间戳API说明timestamp(_ format: String, unit:)按格式转时间戳timestamp(_ pattern: DateKit.Pattern, unit:)按模式转时间戳timestamp(unit:patterns:)自动识别后转时间戳timestampString(_ format: String, unit:scale:)转时间戳字符串dateStringFromTimestamp(unit:format:)时间戳字符串转日期字符串convertTimestamp(from:to:scale:)时间戳单位互转5.5 相对时间与区间说明relative(...)返回DateRelativeProxy中间对象它保存target reference用于继续做.isYesterday/.isToday/...等判断。API说明relative(_ format: String, to:)按格式返回相对时间判断对象relative(_ pattern: DateKit.Pattern, to:)按模式返回相对时间判断对象relative(to:patterns:)自动识别后返回相对时间判断对象isBetween(_:and:format:inclusive:)判断字符串时间是否在区间内isYesterday(_ format:ref:)显式格式判断昨天isYesterday(ref:patterns:)自动识别判断昨天isToday(_ format:ref:)显式格式判断今天isToday(ref:patterns:)自动识别判断今天isTomorrow(_ format:ref:)显式格式判断明天isTomorrow(ref:patterns:)自动识别判断明天isDayBeforeYesterday(_ format:ref:)判断前天isLastWeek(_ format:ref:)判断上周isNextWeek(_ format:ref:)判断下周isLastYear(_ format:ref:)判断去年isNextYear(_ format:ref:)判断明年5.6 字符串工具API说明trimmed()去首尾空白和换行removingWhitespacesAndNewlines()去全部空白和换行isIntegerNumber是否整数文本isDecimalNumber是否十进制数字文本digitsOnly()仅保留数字字符formattedWithGrouping(maximumFractionDigits:minimumFractionDigits:)数字千分位格式化safeSubstring(start:length:)安全截取子串isBlank是否空白字符串nilIfBlank()空白转nil否则返回 trim 后内容urlEncoded()URL 编码urlDecoded()URL 解码base64Encoded()Base64 编码UTF-8base64Decoded()Base64 解码UTF-86. Date 默认语义扩展DateUtility.swift说明业务逻辑层推荐直接用Date扩展调用更自然。API说明formatted(_:)Date格式化输出timestamp(unit:)Date转时间戳relative(to:)返回DateRelativeProxystartOfDay()获取当天开始时间endOfDay()获取当天结束时间startOfWeek()获取当周开始时间endOfWeek()获取当周结束时间startOfMonth()获取当月开始时间endOfMonth()获取当月结束时间adding(_:_:)日期加减如加 7 天isSameDay(as:)判断是否同一天isWeekend()判断是否周末days(to:)计算相差自然日天数isInRange(from:to:inclusive:)区间判断isBetween(_:and:inclusive:)区间判断别名isDayBeforeYesterday(ref:)判断前天isYesterday(ref:)判断昨天isToday(ref:)判断今天isTomorrow(ref:)判断明天isLastWeek(ref:)判断上周isNextWeek(ref:)判断下周isLastYear(ref:)判断去年isNextYear(ref:)判断明年isWithinPast(_:_:,ref:inclusive:)判断是否在参考时间向前范围内Date.fromTimestamp(_:unit:)时间戳转DateDateRelativeProxy说明是什么相对时间判断对象内部绑定target与reference何时用需要连续判断多个相对条件时减少重复传参属性isDayBeforeYesterday / isYesterday / isToday / isTomorrow / isLastWeek / isNextWeek / isLastYear / isNextYear方法matches(_:)按标签通用判断方法withinPast(_:_:,inclusive:)范围判断7. 时间戳扩展TimestampConversion.swift说明当时间戳本来就是数值类型时无需先转字符串。适用于BinaryInteger / BinaryFloatingPoint / DecimalconvertTimestamp(from:to:)时间戳单位换算toDate(unit:)时间戳转Date8. 金额换算MoneyConversion.swift MoneyConversion.swift说明仅做同币种单位换算不涉及汇率内部使用Decimal确保精度。8.1 枚举与类型CurrencyCodecny人民币usd美元eur欧元gbp英镑jpy日元MoneyUnitmajor主单位如元/美元tenth十分位单位如角minor百分位单位如分/美分CNYPartsyuan元jiao角fen分8.2 核心 APIMoneyConversion.convert(_:from:to:currency:)MoneyConversion.splitCNY(_:)MoneyConversion.mergeCNY(yuan:jiao:fen:)8.3 扩展入口String / BinaryInteger / BinaryFloatingPoint / DecimalconvertMoney(from:to:currency:)convertMoneyString(from:to:currency:scale:)DecimalsplitCNY()CNYPartstoDecimalYuan()9. 百分比换算PercentageConversion.swift PercentageConversion.swift说明支持“百分数 - 比率”双向转换。9.1 核心 APIPercentageConversion.percentToRatio(_:)PercentageConversion.ratioToPercent(_:)9.2 扩展入口StringpercentToRatio / ratioToPercent / percentToRatioString / ratioToPercentStringBinaryIntegerpercentToRatio / ratioToPercentBinaryFloatingPointpercentToRatio / ratioToPercentDecimalpercentToRatio / ratioToPercent / asPercentString10. 颜色转换SwiftUtilityKit.swift ColorPlatform.swift说明支持颜色字符串、整数、十六进制与系统颜色对象互转。10.1 ColorRGBAinit(red:green:blue:alpha:)parse(_:)fromPackedInt(_:hasAlpha:)hexString(includeAlpha:prefixHash:)packedInt(includeAlpha:)10.2 String / Integer 扩展StringtoColorRGBA / normalizedColorHex / colorToPackedIntBinaryIntegertoColorRGBA(hasAlpha:) / toColorHex(hasAlpha:prefixHash:)10.3 平台桥接ColorRGBAinit(red: CGFloat, green: CGFloat, blue: CGFloat, alpha: CGFloat)fromHex(_:)cgColorinit(cgColor:)uiColorUIKitinit(uiColor:)UIKitswiftUIColorSwiftUIUIColorUIKitinit(_ color: ColorRGBA)toColorRGBA()ColorSwiftUI UIKit 桥接toColorRGBA()11. 设备与应用信息DeviceInfo.swift说明用于获取系统版本、设备机型、App 版本和屏幕分辨率等信息UIKit 平台可用。11.1 核心 APIDeviceInfo.systemName系统名称如 iOSDeviceInfo.systemVersion系统版本号DeviceInfo.modelIdentifier设备机型标识如iPhone16,2DeviceInfo.modelName设备机型名称如iPhone 15 Pro MaxDeviceInfo.appVersionApp 版本号CFBundleShortVersionStringDeviceInfo.appBuildApp 构建号CFBundleVersionDeviceInfo.appVersionWithBuild版本号 构建号如1.2.3(45)DeviceInfo.logicalResolution逻辑分辨率pointDeviceInfo.pixelResolution物理分辨率pixelDeviceInfo.logicalResolutionText逻辑分辨率文本如393x852 ptDeviceInfo.pixelResolutionText物理分辨率文本如1179x2556 pxDeviceInfo.screenScale屏幕缩放倍数DeviceInfo.nativeScale原生缩放倍数11.2 扩展 APIUIDevice.utilityModelIdentifier设备机型标识UIDevice.utilityModelName设备机型名称UIScreen.utilityPixelResolution屏幕像素分辨率11.3 机型映射维护机型映射独立维护在Sources/SwiftUtilityKit/Resources/AppleDeviceList.txt文件格式identifier|name一行一条#开头为注释未命中映射时会自动回退为原始机型标识12. 字符串校验与格式化StringValidation.swift说明用于输入合法性校验和展示脱敏。最简示例letphoneOK13800138000.isValidChineseMobile// 校验大陆手机号letemailOKdemoexample.com.isValidEmail// 校验邮箱leturlOKhttps://example.com/path?a1.isValidURL// 校验 URLletipv6OK2408:8400:9800:31d3:4ff7:f6d2:69f8:77b3.isValidIPv6// 校验 IPv6letcardOK4111111111111111.isValidBankCardNumber// 校验银行卡号LuhnletidOK11010519491231002X.isValidChineseIDCard// 校验身份证号含校验码letcardText6222021234567890123.formattedBankCardNumber()// 银行卡分组格式化letphoneText13800138000.formattedChineseMobile()// 手机号格式化为 XXX-XXXX-XXXXletphoneMask13800138000.maskedChineseMobile()// 手机号脱敏为 XXX****XXXXletidMask11010519491231002X.maskedChineseIDCard()// 身份证脱敏为 前6 **** 后412.1 校验isValidChineseMobileisValidURLisValidEmailisValidIPv6isValidBankCardNumberisValidChineseIDCard12.2 格式化与脱敏formattedBankCardNumber(separator:)formattedChineseMobile(separator:)maskedChineseMobile(mask:)maskedChineseIDCard(mask:)13. 数值扩展NumericConversion.swift说明当数据已是数值类型时直接调用数值扩展更高效。13.1 BinaryInteger单位convertLength / convertWeight / convertArea / convertVolume / convertTime / convertTemperature / convertSpeed时间关系compareTime / timeDifference进制convertRadix(to:uppercase:)中文大写toChineseUppercaseNumber / toChineseUppercaseCurrency颜色toColorRGBA / toColorHex13.2 BinaryFloatingPoint单位convertLength / convertWeight / convertArea / convertVolume / convertTime / convertTemperature / convertSpeed时间关系compareTime / timeDifference中文大写toChineseUppercaseNumber / toChineseUppercaseCurrency13.3 Decimal单位convertLength / convertWeight / convertArea / convertVolume / convertTime / convertTemperature / convertSpeed时间关系compareTime / timeDifference中文大写toChineseUppercaseNumber / toChineseUppercaseCurrency14. 单位枚举完整列表含说明14.1 LengthUnit长度picometer皮米nanometer纳米micrometer微米millimeter毫米centimeter厘米decimeter分米meter米kilometer千米nauticalMile海里mile英里furlong弗隆yard码foot英尺inch英寸li里zhang丈chi尺cun寸fen分liSmall厘hao毫lightYear光年14.2 WeightUnit重量microgram微克milligram毫克gram克kilogram千克ton吨ounce盎司pound磅stone英石jin斤liang两qian钱14.3 AreaUnit面积squareMillimeter平方毫米squareCentimeter平方厘米squareDecimeter平方分米squareMeter平方米squareKilometer平方千米hectare公顷acre英亩squareFoot平方英尺squareInch平方英寸mu亩14.4 VolumeUnit体积milliliter毫升liter升cubicMeter立方米teaspoon茶匙tablespoon汤匙cup杯pint品脱gallon加仑cubicCentimeter立方厘米cubicInch立方英寸14.5 TimeUnit时间nanosecond纳秒microsecond微秒millisecond毫秒second秒minute分钟hour小时day天week周14.6 TemperatureUnit温度celsius摄氏度fahrenheit华氏度kelvin开尔文14.7 SpeedUnit速度meterPerSecond米每秒kilometerPerHour千米每小时milePerHour英里每小时knot节footPerSecond英尺每秒15. 日期相关枚举完整列表含说明15.1 DateConversion.TimestampUnitsecond秒级时间戳如1704067200millisecond毫秒级时间戳如170406720000015.2 DateConversion.DateDifferenceUnitsecond按秒输出差值minute按分钟输出差值hour按小时输出差值day按天输出差值24 小时15.3 DateConversion.RelativeDateTagdayBeforeYesterday前天yesterday昨天today今天tomorrow明天lastWeek上周nextWeek下周lastYear去年nextYear明年16. 错误类型完整列表ConversionErrorinvalidNumber无效数字invalidBase无效进制范围invalidRadixValue进制值不合法overflow溢出invalidChineseNumeral中文数字不合法invalidColor颜色不合法invalidDate日期不合法invalidMoneyUnit币种与金额单位不匹配17. 国际化单位名称本地化localizedName(locale:)错误信息本地化ConversionError.errorDescription