XScript 手册 · Chapter 33

DATE 对象 — 日期 / 时间处理

脚本中通过关键字 DATE 访问的日期 / 时间工具。内部表示是 .NET 的 Ticks(long) — 比 DateTime 更轻,比较与运算简单。

形式	含义
`long`(Ticks)	1 tick = 100 ns。从 `DateTime(0001-01-01)` 起的累计值
`"yyyy-MM-dd HH:mm:ss"`	人类可读标准格式

当前时间一行 — long now = DATE.GetNow();

当前时间

long nowLocal = DATE.GetNow();      // 本地时区 Ticks
long nowUtc   = DATE.GetUtcNow();   // UTC Ticks
 
Log($"now local : {DATE.ConvertDateTimeString(nowLocal)}");
Log($"now utc   : {DATE.ConvertDateTimeString(nowUtc)}");

字符串 ↔ Ticks 转换

// Ticks → 字符串
string d  = DATE.ConvertDateString(DATE.GetNow());                   // "2026-05-06"
string dt = DATE.ConvertDateTimeString(DATE.GetNow());                // "2026-05-06 09:31:02"
string dt2 = DATE.ConvertDateTimeString(DATE.GetNow(), "HH:mm:ss");  // 自定义格式
 
// 字符串 → Ticks
long t1 = DATE.ConvertDateTimeLong("2026-05-06 09:30:00");
long t2 = DATE.ConvertUtcDateTimeLong("2026-05-06T00:30:00Z");
 
// 安全解析 — 失败返回 false
long t3;
if( DATE.TryParseDateTime("2026-13-99", t3) == false )
{
    LogError("invalid date input");
}

格式字符:yyyy MM dd HH mm ss fff(区分大小写 — MM 月 / mm 分)。

本地 ↔ UTC 转换

long local = DATE.GetNow();
long utc   = DATE.ConvertLocalToUtc(local);
 
long backToLocal = DATE.ConvertUtcToLocal(utc);

数据库存 UTC、画面显示本地 — 记住这两个转换即可。

Encode / Decode

// 由年-月-日-时-分-秒-毫秒构成
long t = DATE.EncodeDate(2026, 5, 6);
long u = DATE.EncodeDateTime(2026, 5, 6, 9, 30, 0, 0);
 
// 分解
int year, month, day;
DATE.DecodeDate(t, year, month, day);
 
int yy, mm, dd, hh, mi, ss, ms;
DATE.DecodeDateTime(u, yy, mm, dd, hh, mi, ss, ms);

DecodeDate / DecodeDateTime 通过 out 参数直接填入变量。

两个时间的差(Between)

long start = DATE.EncodeDateTime(2026, 5, 1, 9, 0, 0, 0);
long end   = DATE.GetNow();
 
int years   = DATE.YearsBetween(end, start);
int months  = DATE.MonthsBetween(end, start);
int weeks   = DATE.WeeksBetween(end, start);
int days    = DATE.DaysBetween(end, start);
long hours  = DATE.HoursBetween(end, start);
long mins   = DATE.MinutesBetween(end, start);
long secs   = DATE.SecondsBetween(end, start);
long mss    = DATE.MilliSecondsBetween(end, start);
 
Log($"elapsed : {days}d {hours % 24}h {mins % 60}m");

参数顺序无关 — 内部按绝对值计算。

时间加减(Increment*)

long now = DATE.GetNow();
 
long oneYearLater  = DATE.IncrementYears(now, 1);
long threeMonths   = DATE.IncrementMonths(now, 3);
long tomorrow      = DATE.IncrementDays(now, 1);
long inOneHour     = DATE.IncrementHours(now, 1);
long inFiveMinutes = DATE.IncrementMinutes(now, 5);
long inThirtySec   = DATE.IncrementSeconds(now, 30);
long inOneSecond   = DATE.IncrementMilliseconds(now, 1000);
 
// 负值 → 过去
long yesterday     = DATE.IncrementDays(now, -1);

常用模式

显示作业经过时间

long workStart;
 
FUNCTION OnStart()
{
    workStart = DATE.GetNow();
}
 
FUNCTION OnTick()
{
    long now = DATE.GetNow();
    int sec = (int)DATE.SecondsBetween(now, workStart);
    Data::ElapsedText = $"{sec / 60}:{sec % 60:00}";
}

等待到截止时间

long deadline = DATE.IncrementSeconds(DATE.GetNow(), 30);
 
while( DATE.GetNow() < deadline )
{
    if( SYS.IsHomeDone() ) return true;
    Sleep(50);
}
return false;     // timeout

按日期建文件夹

string today = DATE.ConvertDateString(DATE.GetNow());        // "2026-05-06"
string folder = $"D:/Logs/{today}";
SYS.CreateFolder(folder);

函数一览

函数	返回	含义
`GetNow()` / `GetUtcNow()`	long	当前时间(本地 / UTC)
`ConvertDateString(t)`	string	`"yyyy-MM-dd"`
`ConvertDateTimeString(t)` / `(t, fmt)`	string	标准 / 自定义格式
`ConvertDateTimeLong(s)`	long	字符串 → Ticks
`ConvertUtcDateTimeLong(s)`	long	视为 UTC 解析
`TryParseDateTime(s, ref t)`	bool	安全解析
`ConvertLocalToUtc(t)` / `ConvertUtcToLocal(t)`	long	时区转换
`EncodeDate / EncodeDateTime`	long	数字 → Ticks
`DecodeDate / DecodeDateTime`	void	Ticks → out 变量
`YearsBetween / Months / Weeks / Days / Hours / Minutes / Seconds / MilliSeconds`	int / long	两时间差
`IncrementYears / Months / Days / Hours / Minutes / Seconds / Milliseconds`	long	加减(负值减)