整个 KMP 的日期时间工具

import kotlinx.datetime.*
import kotlin.time.Duration
import kotlin.time.DurationUnit
import kotlin.time.toDuration

/**
 * Kotlin Multiplatform 日期时间工具类
 * 基于 kotlinx-datetime，提供时间戳转换、格式化、计算等常用功能
 */
object DateTimeUtils {
    /**
     * 获取当前时间戳（毫秒）
     */
    val currentTimestamp: Long
        get() = Clock.System.now().toEpochMilliseconds()

    /**
     * 获取当前时间的 Instant 对象（UTC 时间）
     */
    fun getCurrentInstant(): Instant = Clock.System.now()

    /**
     * 获取当前系统默认时区的 LocalDateTime
     */
    fun getCurrentLocalDateTime(): LocalDateTime =
        getCurrentInstant().toLocalDateTime(TimeZone.currentSystemDefault())

    /**
     * 获取当前日期字符串（格式：yyyy-MM-dd）
     */
    fun getCurrentDateString(): String =
        getCurrentLocalDateTime().date.toString() // 输出示例: 2025-09-29

    /**
     * 获取当前时间字符串（格式：HH:mm:ss）
     */
    fun getCurrentTimeString(): String =
        getCurrentLocalDateTime().time.toString() // 输出示例: 16:26:51

    /**
     * 将毫秒时间戳转换为指定时区的 LocalDateTime
     * @param timestamp 毫秒时间戳
     * @param timeZone 目标时区，默认为系统时区
     */
    fun timestampToLocalDateTime(
        timestamp: Long,
        timeZone: TimeZone = TimeZone.currentSystemDefault()
    ): LocalDateTime =
        Instant.fromEpochMilliseconds(timestamp).toLocalDateTime(timeZone)

    /**
     * 将 LocalDateTime 转换为毫秒时间戳
     * @param localDateTime 本地日期时间对象
     * @param timeZone 该 LocalDateTime 所对应的时区，默认为系统时区
     */
    fun localDateTimeToTimestamp(
        localDateTime: LocalDateTime,
        timeZone: TimeZone = TimeZone.currentSystemDefault()
    ): Long =
        localDateTime.toInstant(timeZone).toEpochMilliseconds()

    /**
     * 格式化 LocalDateTime 为字符串
     * @param localDateTime 要格式化的日期时间
     * @param pattern 格式模式，例如 "yyyy-MM-dd HH:mm:ss"
     */
    fun formatLocalDateTime(localDateTime: LocalDateTime, pattern: String): String {
        // 根据不同的模式返回相应的格式化结果
        return when (pattern) {
            PATTERN_DEFAULT -> "${localDateTime.year}-${
                localDateTime.monthNumber.toString().padStart(2, '0')
            }-${localDateTime.dayOfMonth.toString().padStart(2, '0')} " +
                    "${
                        localDateTime.hour.toString().padStart(2, '0')
                    }:${
                        localDateTime.minute.toString().padStart(2, '0')
                    }:${localDateTime.second.toString().padStart(2, '0')}"

            PATTERN_YYYY_MM_DD_HH_MM -> "${localDateTime.year}-${
                localDateTime.monthNumber.toString().padStart(2, '0')
            }-${localDateTime.dayOfMonth.toString().padStart(2, '0')} " +
                    "${
                        localDateTime.hour.toString().padStart(2, '0')
                    }:${localDateTime.minute.toString().padStart(2, '0')}"

            PATTERN_DATE_ONLY -> "${localDateTime.year}-${
                localDateTime.monthNumber.toString().padStart(2, '0')
            }-${localDateTime.dayOfMonth.toString().padStart(2, '0')}"

            PATTERN_TIME_ONLY -> "${
                localDateTime.hour.toString().padStart(2, '0')
            }:${localDateTime.minute.toString().padStart(2, '0')}:${
                localDateTime.second.toString().padStart(2, '0')
            }"

            PATTERN_DATE_ONLY_ -> "${localDateTime.year}/${
                localDateTime.monthNumber.toString().padStart(2, '0')
            }/${localDateTime.dayOfMonth.toString().padStart(2, '0')}"

            PATTERN_CHINESE_DATE -> "${localDateTime.year}年${
                localDateTime.monthNumber.toString().padStart(2, '0')
            }月${localDateTime.dayOfMonth.toString().padStart(2, '0')}日"

            PATTERN_HH_MM_ONLY -> "${
                localDateTime.hour.toString().padStart(2, '0')
            }:${localDateTime.minute.toString().padStart(2, '0')}"

            PATTERN_YEAR_MONTH -> "${localDateTime.year}-${
                localDateTime.monthNumber.toString().padStart(2, '0')
            }"

            PATTERN_MONTH_DAY -> "${
                localDateTime.monthNumber.toString().padStart(2, '0')
            }-${localDateTime.dayOfMonth.toString().padStart(2, '0')}"

            PATTERN_MONTH_DAY_ -> "${
                localDateTime.monthNumber.toString().padStart(2, '0')
            }/${localDateTime.dayOfMonth.toString().padStart(2, '0')}"

            else -> localDateTime.toString()
        }
    }

    /**
     * 计算两个时间点之间的日历差异（年、月、日等）
     * @param start 开始时间
     * @param end 结束时间
     * @param timeZone 计算差异时所基于的时区，默认为系统时区
     */
    fun getDateTimePeriod(
        start: Instant,
        end: Instant,
        timeZone: TimeZone = TimeZone.currentSystemDefault()
    ): DateTimePeriod =
        start.periodUntil(end, timeZone)

    /**
     * 计算两个时间点之间的持续时间（总小时、总分钟、总秒等）
     * @param start 开始时间
     * @param end 结束时间
     */
    fun getDurationBetween(start: Instant, end: Instant): Duration =
        end - start // Kotlin 运算符重载，直接相减得到 Duration
}

// region 实用扩展函数
/**
 * 为 Instant 添加扩展函数，快速转换为指定时区的 LocalDateTime
 */
fun Instant.toLocalDateTimeIn(timeZone: TimeZone = TimeZone.currentSystemDefault()): LocalDateTime =
    this.toLocalDateTime(timeZone)

/**
 * 为 Long (毫秒时间戳) 添加扩展函数，快速转换为 Instant
 */
fun Long.toInstant(): Instant = Instant.fromEpochMilliseconds(this)

/**
 * 为 LocalDateTime 添加扩展函数，快速转换为指定时区的 Instant
 */
fun LocalDateTime.toInstantIn(timeZone: TimeZone = TimeZone.currentSystemDefault()): Instant =
    this.toInstant(timeZone)
// endregion

// region 核心转换扩展
/**
 * 将毫秒时间戳转换为 Instant 对象
 */
val Long.instant: Instant
    get() = Instant.fromEpochMilliseconds(this)

/**
 * 将毫秒时间戳转换为系统默认时区的 LocalDateTime
 */
val Long.localDateTime: LocalDateTime
    get() = this.instant.toLocalDateTime(TimeZone.currentSystemDefault())

/**
 * 将毫秒时间戳转换为指定时区的 LocalDateTime
 */
fun Long.toLocalDateTimeIn(timeZone: TimeZone): LocalDateTime =
    this.instant.toLocalDateTime(timeZone)

/**
 * 将 LocalDateTime 转换回毫秒时间戳
 */
fun LocalDateTime.toTimestamp(timeZone: TimeZone = TimeZone.currentSystemDefault()): Long =
    this.toInstant(timeZone).toEpochMilliseconds()
// endregion

// region 日期时间部件扩展属性
/**
 * 从时间戳获取年份
 */
val Long.year: Int
    get() = this.localDateTime.year

/**
 * 从时间戳获取月份 (1-12)
 */
val Long.month: Int
    get() = this.localDateTime.monthNumber

/**
 * 从时间戳获取月份名称
 */
val Long.monthName: String
    get() = this.localDateTime.month.name.lowercase()
        .replaceFirstChar { it.uppercase() }

/**
 * 从时间戳获取日期 (1-31)
 */
val Long.day: Int
    get() = this.localDateTime.dayOfMonth

/**
 * 从时间戳获取星期几
 */
val Long.dayOfWeek: String
    get() = this.localDateTime.dayOfWeek.name.lowercase()
        .replaceFirstChar { it.uppercase() }

/**
 * 从时间戳获取小时 (0-23)
 */
val Long.hour: Int
    get() = this.localDateTime.hour

/**
 * 从时间戳获取分钟 (0-59)
 */
val Long.minute: Int
    get() = this.localDateTime.minute

/**
 * 从时间戳获取秒数 (0-59)
 */
val Long.second: Int
    get() = this.localDateTime.second

/**
 * 从时间戳获取毫秒数
 */
val Long.millisecond: Int
    get() = this.localDateTime.nanosecond / 1_000_000
// endregion

// region 格式化输出扩展
/**
 * 将时间戳格式化为默认字符串 "yyyy-MM-dd HH:mm:ss"
 */
fun Long.toFormattedString(): String = this.toFormattedString(PATTERN_DEFAULT)

/**
 * 将时间戳格式化为指定模式的字符串
 */
fun Long.toFormattedString(pattern: String): String {
    val dateTime = this.localDateTime
    return DateTimeUtils.formatLocalDateTime(dateTime, pattern)
}

/**
 * 将时间戳转换为相对时间字符串（例如："2天前", "刚刚"）
 */
fun Long.toRelativeTimeString(): String {
    val duration = (DateTimeUtils.currentTimestamp - this).toDuration(DurationUnit.MILLISECONDS)
    return when {
        duration.isNegative() -> "未来"
        duration.inWholeDays > 365 -> "${duration.inWholeDays / 365}年前"
        duration.inWholeDays > 30 -> "${duration.inWholeDays / 30}个月前"
        duration.inWholeDays > 7 -> "${duration.inWholeDays / 7}周前"
        duration.inWholeDays > 0 -> "${duration.inWholeDays}天前"
        duration.inWholeHours > 0 -> "${duration.inWholeHours}小时前"
        duration.inWholeMinutes > 0 -> "${duration.inWholeMinutes}分钟前"
        else -> "刚刚"
    }
}

/**
 * 将时间戳转换为简洁的时间格式（今天显示时间，昨天显示"昨天"，更早显示日期）
 */
fun Long.toSmartTimeString(): String {
    return when {
        this.isToday() -> this.toFormattedString(PATTERN_HH_MM_ONLY)
        this.isYesterday() -> "昨天 ${this.toFormattedString(PATTERN_HH_MM_ONLY)}"
        this.isThisYear() -> this.toFormattedString("MM-dd HH:mm")
        else -> this.toFormattedString(PATTERN_DATE_ONLY)
    }
}
// endregion

// region 相对时间判断扩展
/**
 * 判断时间戳是否代表今天
 */
fun Long.isToday(): Boolean {
    val today = Clock.System.now().toLocalDateTime(TimeZone.currentSystemDefault()).date
    val targetDate = this.instant.toLocalDateTime(TimeZone.currentSystemDefault()).date
    return today == targetDate
}

/**
 * 判断时间戳是否代表明天
 */
fun Long.isTomorrow(): Boolean {
    val today = Clock.System.now().toLocalDateTime(TimeZone.currentSystemDefault()).date
    val tomorrow = today.plus(DatePeriod(days = 1))
    val targetDate = this.instant.toLocalDateTime(TimeZone.currentSystemDefault()).date
    return tomorrow == targetDate
}

/**
 * 判断时间戳是否代表昨天
 */
fun Long.isYesterday(): Boolean {
    val today = Clock.System.now().toLocalDateTime(TimeZone.currentSystemDefault()).date
    val yesterday = today.minus(DatePeriod(days = 1))
    val targetDate = this.instant.toLocalDateTime(TimeZone.currentSystemDefault()).date
    return yesterday == targetDate
}

/**
 * 判断时间戳是否在本年
 */
fun Long.isThisYear(): Boolean {
    val currentYear = Clock.System.now().toLocalDateTime(TimeZone.currentSystemDefault()).year
    return this.year == currentYear
}

/**
 * 判断时间戳是否在指定年份
 */
fun Long.isInYear(targetYear: Int): Boolean = this.year == targetYear

/**
 * 判断时间戳是否在指定月份
 */
fun Long.isInMonth(targetMonth: Int): Boolean = this.month == targetMonth
// endregion

// region 时间运算扩展
/**
 * 为此时间戳添加指定的时间量
 */
fun Long.plusDuration(duration: Duration): Long =
    (this.duration + duration).inWholeMilliseconds

fun Long.plusDays(days: Int): Long = this.plusDuration(days.toDuration(DurationUnit.DAYS))
fun Long.plusHours(hours: Int): Long = this.plusDuration(hours.toDuration(DurationUnit.HOURS))
fun Long.plusMinutes(minutes: Int): Long =
    this.plusDuration(minutes.toDuration(DurationUnit.MINUTES))

fun Long.plusSeconds(seconds: Int): Long =
    this.plusDuration(seconds.toDuration(DurationUnit.SECONDS))

/**
 * 从此时间戳减去指定的时间量
 */
fun Long.minusDuration(duration: Duration): Long =
    (this.duration - duration).inWholeMilliseconds

fun Long.minusDays(days: Int): Long = this.minusDuration(days.toDuration(DurationUnit.DAYS))
fun Long.minusHours(hours: Int): Long = this.minusDuration(hours.toDuration(DurationUnit.HOURS))
fun Long.minusMinutes(minutes: Int): Long =
    this.minusDuration(minutes.toDuration(DurationUnit.MINUTES))

/**
 * 计算此时间戳与另一个时间戳之间的时间差
 */
fun Long.timeUntil(otherTimestamp: Long): Duration =
    (otherTimestamp - this).toDuration(DurationUnit.MILLISECONDS)

/**
 * 计算此时间戳与当前时间的时间差
 */
fun Long.timeFromNow(): Duration =
    (DateTimeUtils.currentTimestamp - this).toDuration(DurationUnit.MILLISECONDS)

/**
 * 计算两个时间戳之间相隔的天数
 */
fun Long.daysBetween(otherTimestamp: Long): Int {
    val startDate = this.instant.toLocalDateTime(TimeZone.currentSystemDefault()).date
    val endDate = otherTimestamp.instant.toLocalDateTime(TimeZone.currentSystemDefault()).date
    return startDate.daysUntil(endDate)
}

/**
 * 计算两个时间戳之间相隔的小时数
 */
fun Long.hoursBetween(otherTimestamp: Long): Long =
    this.timeUntil(otherTimestamp).inWholeHours

/**
 * 计算两个时间戳之间相隔的分钟数
 */
fun Long.minutesBetween(otherTimestamp: Long): Long =
    this.timeUntil(otherTimestamp).inWholeMinutes
// endregion

// region 实用工具扩展
/**
 * 获取当天开始的时间戳（00:00:00.000）
 */
fun Long.atStartOfDay(timeZone: TimeZone = TimeZone.currentSystemDefault()): Long {
    val localDate = this.instant.toLocalDateTime(timeZone).date
    return localDate.atStartOfDayIn(timeZone).toEpochMilliseconds()
}

/**
 * 获取当天结束的时间戳（23:59:59.999）
 */
fun Long.atEndOfDay(timeZone: TimeZone = TimeZone.currentSystemDefault()): Long {
    return this.atStartOfDay(timeZone).plusDays(1) - 1
}

/**
 * 获取本周第一天的开始时间戳
 */
fun Long.atStartOfWeek(timeZone: TimeZone = TimeZone.currentSystemDefault()): Long {
    val localDateTime = this.instant.toLocalDateTime(timeZone)
    val daysFromMonday = (localDateTime.dayOfWeek.isoDayNumber - 1) % 7
    return this.minusDays(daysFromMonday).atStartOfDay(timeZone)
}

/**
 * 获取本月第一天的开始时间戳
 */
fun Long.atStartOfMonth(timeZone: TimeZone = TimeZone.currentSystemDefault()): Long {
    val localDateTime = this.instant.toLocalDateTime(timeZone)
    val firstDayOfMonth = LocalDate(localDateTime.year, localDateTime.month, 1)
    return firstDayOfMonth.atStartOfDayIn(timeZone).toEpochMilliseconds()
}

/**
 * 判断时间戳是否在某个时间范围内
 */
fun Long.isBetween(startTimestamp: Long, endTimestamp: Long): Boolean =
    this in startTimestamp..endTimestamp

/**
 * 将时间戳转换为 Duration 对象
 */
val Long.duration: Duration
    get() = this.toDuration(DurationUnit.MILLISECONDS)

/**
 * 获取时间戳对应的季度 (1-4)
 */
val Long.quarter: Int
    get() = (this.month - 1) / 3 + 1

/**
 * 获取时间戳对应的星期在年中的周数
 */
val Long.weekOfYear: Int
    get() {
        val localDate = this.instant.toLocalDateTime(TimeZone.currentSystemDefault()).date
        val firstDayOfYear = LocalDate(localDate.year, 1, 1)
        val daysBetween = firstDayOfYear.daysUntil(localDate)
        return daysBetween / 7 + 1
    }
// endregion

// region 常用日期格式模式常量,需要什么自己扩展
const val PATTERN_DEFAULT = "yyyy-MM-dd HH:mm:ss"
const val PATTERN_YYYY_MM_DD_HH_MM = "yyyy-MM-dd HH:mm"
const val PATTERN_CHINESE_DATE = "yyyy年MM月dd日"
const val PATTERN_DATE_ONLY = "yyyy-MM-dd"
const val PATTERN_DATE_ONLY_ = "yyyy/MM/dd"
const val PATTERN_TIME_ONLY = "HH:mm:ss"
const val PATTERN_HH_MM_ONLY = "HH:mm"
const val PATTERN_YEAR_MONTH = "yyyy-MM"
const val PATTERN_MONTH_DAY = "MM-dd"
const val PATTERN_MONTH_DAY_ = "MM/dd"
// endregion

// region 处理秒级时间戳的扩展

/**
 * 将秒级时间戳转换为Instant对象
 */
fun Long.toInstantFromSeconds(): Instant = Instant.fromEpochSeconds(this)

/**
 * 将秒级时间戳转换为系统默认时区的LocalDateTime
 */
fun Long.toLocalDateTimeFromSeconds(): LocalDateTime = 
    this.toInstantFromSeconds().toLocalDateTime(TimeZone.currentSystemDefault())

/**
 * 将秒级时间戳格式化为指定模式的字符串
 */
fun Long.toFormattedStringFromSeconds(pattern: String): String {
    val dateTime = this.toLocalDateTimeFromSeconds()
    return DateTimeUtils.formatLocalDateTime(dateTime, pattern)
}

// endregion