Flutter时间计算插件time_since的使用

time_since 是一个用于将时间戳转换为人类可读的时间字符串（如“2小时前”，“3个月前”）的 Flutter 包。

特性

• 将时间戳或 DateTime 对象转换为人类可读的时间字符串。
• 可自定义输出格式。
• 支持多种时间单位（年、月、日、小时、分钟、秒）。
• 针对非常近的时间设置“刚刚”阈值。
• 可配置的时间描述精度。
• 自动复数化时间单位。

安装

在你的项目 pubspec.yaml 文件中添加以下依赖：

dependencies:
  time_since: ^1.0.0

然后运行：

flutter pub get

使用

基本用法

import 'package:time_since/time_since.dart';

// 使用 DateTime
final dateTime = DateTime(2024, 1, 1);
print(timeSince(dateTime)); // "3个月前"

// 使用 Unix 时间戳（秒）
final timestamp = 1704067200; // 2024年1月1日
print(timeSince(timestamp)); // "3个月前"

自定义输出

你可以通过 TimeFormatOptions 自定义输出格式：

final options = TimeFormatOptions(
  addAgo: false,         // 不追加 "ago"
  maxPrecision: 2,       // 显示最多两个单位（例如 "1年，2个月"）
  justNowThreshold: 60,  // 在60秒内显示 "刚刚"
);

final time = DateTime.now().subtract(Duration(hours: 25));
print(timeSince(time, options)); // "1天，1小时"

API 参考

timeSince

String timeSince(dynamic time, [TimeFormatOptions? options])

将时间格式化为人类可读的时间字符串。

参数：

• time: Unix 时间戳（int）或 DateTime 对象
• options: 可选的 TimeFormatOptions 以自定义输出

返回值类似于 “2小时前” 或 “3个月前” 的字符串。

TimeFormatOptions

class TimeFormatOptions {
  final bool addAgo;            // 是否追加 "ago" 到结果
  final int maxPrecision;       // 显示的最大单位数量
  final int justNowThreshold;   // "刚刚" 的秒阈值
  
  const TimeFormatOptions({
    this.addAgo = true,
    this.maxPrecision = 1,
    this.justNowThreshold = 30,
  });
}

时间单位

该包支持以下时间单位：

• 年
• 月
• 日
• 小时
• 分钟
• 秒

时间单位会根据数值自动复数化（例如，“1个月”与“2个月”）。

错误处理

如果提供的时间输入无效，包将抛出 ArgumentError。有效的输入包括：

• Unix 时间戳（int）
• DateTime 对象

示例代码

以下是完整的示例代码：

import 'package:time_since/time_since.dart';

void main() {
  // 示例1：基本用法（使用 DateTime）
  void basicDateTimeExample() {
    final now = DateTime.now();
    final pastTime = now.subtract(const Duration(hours: 5));
    print(timeSince(pastTime)); // "5小时前"
  }

  // 示例2：使用 Unix 时间戳
  void unixTimestampExample() {
    final timestampInSeconds = 1698422400; // 2023年10月27日
    print(timeSince(timestampInSeconds)); // 结果取决于当前日期
  }

  // 示例3：自定义格式化选项
  void customFormattingExample() {
    final now = DateTime.now();
    final pastTime = now.subtract(const Duration(days: 45));

    final options = TimeFormatOptions(
      addAgo: false, // 不追加 "ago"
      maxPrecision: 2, // 显示两个单位
    );

    print(timeSince(pastTime, options)); // "1个月，15天"
  }

  // 示例4：处理非常近的时间
  void recentTimesExample() {
    final now = DateTime.now();
    final justNow = now.subtract(const Duration(seconds: 10));
    final almostNow = now.subtract(const Duration(seconds: 45));

    // 默认阈值为30秒
    print(timeSince(justNow)); // "刚刚"
    print(timeSince(almostNow)); // "45秒前"

    // 自定义阈值
    final options = TimeFormatOptions(justNowThreshold: 60);
    print(timeSince(almostNow, options)); // "刚刚"
  }

  // 示例5：高精度格式化
  void highPrecisionExample() {
    final now = DateTime.now();
    final pastTime = now.subtract(const Duration(
      days: 400,
      hours: 5,
      minutes: 30,
    ));

    final options = TimeFormatOptions(
      maxPrecision: 3,
      addAgo: true,
    );

    print(timeSince(pastTime, options)); // "1年，1个月，5天前"
  }

  // 示例6：错误处理
  void errorHandlingExample() {
    try {
      // 无效的输入类型
      print(timeSince("not a valid time"));
    } catch (e) {
      print('错误: $e');
      // 打印: 错误: 无效的时间输入。期望 Unix 时间戳（int）或 DateTime 对象
    }
  }

  // 运行示例
  basicDateTimeExample();
  unixTimestampExample();
  customFormattingExample();
  recentTimesExample();
  highPrecisionExample();
  errorHandlingExample();
}