插件详情v2.0.1

date_time_format

用于使用标准日期/时间格式或相对时间偏移来格式化 Dart 的 DateTime 对象的工具。

AndroidiOSWebmacOSWindowsLinux

pub.dev API 文档源代码

近 30 天下载: 4.1万
喜欢数: 118
Pub 分数: 150

安装插件

flutter pub add date_time_format

插件介绍

基于插件公开信息、社区数据与项目使用情况整理的选型参考。

一个 Flutter/Dart 包，提供用于格式化 Dart DateTime 对象的工具。它支持标准日期/时间表示法以及相对时间偏移（例如“2分钟前”）。旨在简化跨多个平台的应用程序中的日期显示，提供清晰、易读的输出，而无需复杂的手动格式化。该包轻量且可无缝集成到现有项目中。

适合场景

显示用户活动时间戳
在聊天或社交媒体应用中格式化日期
显示事件发生以来的相对时间
多语言应用程序中的本地化日期显示
简化UI组件中的日期字符串生成

主要特点

支持相对时间格式化
处理标准的日期/时间格式
轻量且易于集成
跨平台兼容性
用于常见格式化需求的简单 API

适合对象

需要可读时间戳的应用程序
寻求最小化日期格式化解决方案的开发者
面向多个平台的项目
频繁显示日期的UI密集型应用
注重代码简洁性和可维护性的团队

使用建议

仅限基本格式选项
无内置本地化支持
依赖默认系统区域设置
可能需要为自定义格式进行额外设置
不适用于复杂的国际日期处理

原始 README

以下为关联源码仓库的 README 原文快照，最新内容请访问源码仓库。

date_time_format

A utility class, and extension methods, for formatting Dart's [DateTime] object using standard date/time notation or as a relative time offset.

Usage

import 'package:date_time_format/date_time_format.dart';

date_time_format exposes 2 utility methods, [format] and [relative], that are added to the [DateTime] class as extension methods or can be accessed via the [DateTimeFormat] utility class.

[format] and [relative] format [DateTime] objects as defined by standard date/time notation or as relative to the current or a provided [DateTime], respectively.

See the Date/Time Notations section below for a complete list of supported formatting notations.

In addition to the formatting utilities, a variety of date/time notation formatting constants are pre-defined in the following classes: DateTimeFormats contains standard date/time formatting notations. DateFormats and TimeFormats contain common date-only and time-only formatting constants, respectively. Additional American and European date/time formatting constants can be found in the AmericanDateFormats, AmericanDateTimeFormats, EuropeanDateFormats, and EuropeanDateTimeFormats classes.

Standard Formatting

Note: Each example below shows the extension method being utilized, and the utility method being used on the next line. Both methods will return the same output.

final dateTime = DateTime.now();

// 2019-10-15T19:42:05-08:00
print(dateTime.format());
print(DateTimeFormat.format(dateTime));

// October 15, 2019 7:42 pm
print(dateTime.format(DateTimeFormats.american));
print(DateTimeFormat.format(dateTime, format: DateTimeFormats.american));

// 15/Oct/2019:19:42:05 -0700
print(dateTime.format(DateTimeFormats.commonLogFormat));
print(DateTimeFormat.format(dateTime, format: DateTimeFormats.commonLogFormat));

// Tuesday, October 15, 2019
print(dateTime.format(AmericanDateFormats.dayOfWeek));
print(DateTimeFormat.format(dateTime, format: AmericanDateFormats.dayOfWeek));

// Tue, Oct 15, 19:42
print(dateTime.format('D, M j, H:i'));
print(DateTimeFormat.format(dateTime, format: 'D, M j, H:i'));

Relative Formatting

By default, [DateTimeFormat.relative] returns the time offset rounded to the nearest whole unit of time.

// 5 minutes
print(DateTimeFormat.relative(dateTime.subtract(Duration(minutes: 5))));

// 3 hours
print(DateTimeFormat.relative(dateTime.subtract(Duration(hours: 2, minutes: 30))));

// 5 days
print(DateTimeFormat.relative(dateTime.subtract(Duration(days: 5, hours: 10))));

// 1 week
print(DateTimeFormat.relative(dateTime.subtract(Duration(days: 9))));

// 9 days
print(DateTimeFormat.relative(dateTime.subtract(Duration(days: 9)),
    excludeWeeks: true));

[relative] can also be called as an extension method on [DateTime].

final dateTime = DateTime.now().subtract(Duration(minutes: 5));

// 5 minutes
print(dateTime.relative());

// 5 minutes ago
print(dateTime.relative(appendIfAfter: 'ago'));

// 5 minutes
print(dateTime.relative(to: DateTime.now().subtract(Duration(minutes: 10))));

// In 5 minutes
print(dateTime.relative(
    to: DateTime.now().subtract(Duration(minutes: 10)),
    prependIfBefore: 'In'));

All of the parameters detailed on the [DateTimeFormat.relative] are also provided on the [DateTime.relative] extension method.

Abbreviating:

The returned intervals of time can be abbreviated by setting the [abbr] parameter to true.

final timeOffset = dateTime.subtract(Duration(minutes: 5));

// 5 minutes
print(DateTimeFormat.relative(timeOffset));

// 5m
print(DateTimeFormat.relative(timeOffset, abbr: true));

To compare the provided [DateTime] to another [DateTime] object, the [relativeTo] parameter can be set.

final timeOffset1 = dateTime.subtract(Duration(minutes: 5));
final timeOffset2 = dateTime.add(Duration(minutes: 5));

// 5 minutes
print(DateTimeFormat.relative(timeOffset1));

// 10 minutes
print(DateTimeFormat.relative(timeOffset1, relativeTo: timeOffset2));

Level of Precision:

The [levelOfPrecision] parameter sets the degrees of removal from the largest interval counted that will be included in the count. I.e. minutes are 1 degree removed from hours, and seconds are 2 degrees removed from hours but only 1 degree removed from minutes.

Note: Weeks can be excluded as an interval of time by setting the [excludeWeeks] parameter to true, and will not be counted as a degree of time in regards to [levelOfPrecision].

final timeOffset = dateTime.add(Duration(days: 3, hours: 6, minutes: 30, seconds: 15));

// 3 days
print(DateTimeFormat.relative(timeOffset));

// 3 days 7 hours
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 1));

// 3 days 6 hours 30 minutes
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 2));

// 3 days 6 hours 30 minutes 15 seconds
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 3));

Minimum & Maximum Units of Time:

The minimum and maximum intervals to include in the count can be specified by the [minUnitOfTime] and [maxUnitOfTime] respectively. The largest possible interval of time being a year, and the smallest being a microsecond.

By default, the smallest unit of time returned is a second, to include milliseconds or microseconds the [minUnitOfTime] parameter must be set to [UnitOfTime.milliseconds]/ [UnitOfTime.microseconds]. Note: Milliseconds and microseconds may be returned slightly off from the expected values if the function takes longer to process than those intervals of time.

final timeOffset = dateTime.add(Duration(
    days: 762, hours: 6, minutes: 30, seconds: 15, milliseconds: 300, microseconds: 740));

// 2 years 1 month 2 days
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 3));

// 25 months 5 days 7 hours
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 3,
    maxUnitOfTime: UnitOfTime.month));

// 762 days 6 hours 30 minutes 15 seconds
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 3,
    maxUnitOfTime: UnitOfTime.day));

// 2 years 1 month 2 days 6 hours 30 minutes 15 seconds
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 8));

// 2 years 1 month 2 days 6 hours 30 minutes 15 seconds 301 milliseconds
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 8,
    minUnitOfTime: UnitOfTime.millisecond));

// 2 years 1 month 2 days 6 hours 30 minutes 15 seconds 300 milliseconds 740 microseconds
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 8,
    minUnitOfTime: UnitOfTime.microsecond));

// 2y 1m 2d 6h 30m 15s 300ms 740mu
print(DateTimeFormat.relative(timeOffset, levelOfPrecision: 8,
    minUnitOfTime: UnitOfTime.microsecond, abbr: true));

Rounding:

Rounding, which is enabled by default, can be disabled by setting the [round] parameter to false, in which case any measure of time that isn't included in the smallest returned interval will be truncated.

final timeOffset = dateTime.subtract(Duration(hours: 6, minutes: 45));

// 7 hours
print(DateTimeFormat.relative(timeOffset));

// 6 hours
print(DateTimeFormat.relative(timeOffset, round: false));

Formatting After X Amount of Time:

[formatAfter] can be set to a [Duration] of time to return a standard formatted date/time stamp, via the [DateTimeFormat.format] method, if the difference in time is greater than the duration specified.

By default, date/time stamps will be formatted to the [AmericanDateTimeStamp.abbrWithComma] constant. A different formatting notation can be provided via the [format] parameter.

final timeOffset = dateTime.subtract(Duration(days: 762, hours: 6, minutes: 30));

// 2 years
print(DateTimeFormat.relative(timeOffset));

// Apr 29, 2018 6:27 am
print(DateTimeFormat.relative(timeOffset, formatAfter: Duration(days: 365)));

// 6:27 am · Apr 29, 2018
print(DateTimeFormat.relative(timeOffset, formatAfter: Duration(days: 365),
    format: r'g:i a · M j, Y'));

Prepending & Appending Text:

[prependIfBefore] and [appendIfAfter] can be used to conveniently prepend and/or append a [String] before or after the returned relative time offset if the formatted [DateTime] occurs before or after [relativeTo] (which defaults to DateTime.now()), respectively.

// 5 days ago
print(DateTimeFormat.relative(dateTime.subtract(Duration(days: 5)),
    prependIfBefore: 'In', appendIfAfter: 'ago'));

// In 5 days
print(DateTimeFormat.relative(dateTime.add(Duration(days: 5)),
    prependIfBefore: 'In', appendIfAfter: 'ago'));

Return X Below Minimum Unit of Time:

The [ifNow] parameter can be set to return a value if the difference in time is less than [minUnitOfTime], otherwise, an empty string will be returned.

// Now
print(DateTimeFormat.relative(DateTime.now(), ifNow: 'Now'));

// 5 minutes
print(DateTimeFormat.relative(dateTime.subtract(Duration(minutes: 5)), ifNow: 'Now'));

// Now
print(DateTimeFormat.relative(dateTime.subtract(Duration(minutes: 5)), ifNow: 'Now',
    minUnitOfTime: UnitOfTime.hour));