QTime Class

成员函数文档

[constexpr] QTime::QTime()

构建一个空时间对象。对于空时间，isNull() 返回true ，而isValid() 返回false 。如果需要零时间，请使用 QTime(0, 0)。关于一天的开始时间，请参阅QDate::startOfDay()。

另请参阅 isNull() 和isValid()。

QTime::QTime(int h, int m, int s = 0, int ms = 0)

构建一个时间，其中小时为h ，分钟为m ，秒为s ，毫秒为ms 。

h 必须在 0 到 23 之间，m 和s 必须在 0 到 59 之间，ms 必须在 0 到 999 之间。

另请参阅 isValid()。

QTime QTime::addMSecs(int ms) const

返回一个QTime 对象，其中包含比该对象当前时间晚ms 毫秒的时间（如果ms 为负数，则返回比当前时间早的时刻）。

请注意，如果时间超过午夜，时间值将发生循环。示例请参见addSecs()。

如果该时间无效，则返回空时间。

另请参阅 addSecs()、msecsTo() 和QDateTime::addMSecs()。

QTime QTime::addSecs(int s) const

返回一个QTime 对象，其中包含比该对象当前时间晚s 秒的时间（如果s 为负数，则返回更早的时间）。

请注意，如果时间超过午夜，时间值将进行循环重置。

如果该时间无效，则返回空时间。

示例：

QTime n(14, 0, 0);                // n == 14:00:00
QTime t;
t = n.addSecs(70);                // t == 14:01:10
t = n.addSecs(-70);               // t == 13:58:50
t = n.addSecs(10 * 60 * 60 + 5);  // t == 00:00:05
t = n.addSecs(-15 * 60 * 60);     // t == 23:00:00

另请参阅 addMSecs()、secsTo() 和QDateTime::addSecs()。

[static] QTime QTime::currentTime()

返回系统时钟报告的当前时间。

请注意，其精度取决于底层操作系统的精度；并非所有系统都能提供 1 毫秒的精度。

此外，currentTime() 在每一天内只会递增；每逢午夜，该值将减少 24 小时；此外，如果期间发生夏令时转换，其变化可能与实际经过的时间不一致。

另请参阅 QDateTime::currentDateTime() 和QDateTime::currentDateTimeUtc()。

[static constexpr] QTime QTime::fromMSecsSinceStartOfDay(int msecs)

返回一个新的 `QTime ` 实例，其中时间设置为自当天开始（即自 00:00:00 起）以来的 `msecs ` 个单位。

如果 `msecs ` 超出有效范围，则会返回一个无效的 `QTime `。

另请参阅 msecsSinceStartOfDay()。

[static] QTime QTime::fromString(const QString &string, const QString &format)

返回由字符串string 所表示的QTime ，使用给定的format 进行解析；如果无法解析该字符串，则返回无效时间。

以下表达式可用于该格式：

任何用单引号括起的非空字符序列也将被视为文本（去掉引号），而不会被解释为表达式。 两个连续的单引号（"''"）将被视为一个单引号，用于与输入内容匹配，而不是作为原样序列的开始或结束。所有其他输入字符都将被视为原样文本，用于与输入字符串进行匹配。例如：

QTime time = QTime::fromString("1mm12car00", "m'mm'hcarss");
// time is 12:01.00

如果格式不符，将返回一个无效的QTime 。

当数字字段紧邻排列且没有分隔符来分割数字序列时，可能会出现歧义：某些允许使用一位数的字段是否应使用两位数（因为要表示的值大于9）。 若为该字段分配两位数会导致其他字段可用位数不足，且单个位数的读数与其他字段一致，则可解决此歧义。 否则（即当多个字段允许仅使用一位数，且若每个字段仅使用一位数时仍会有剩余位数），在数据保持一致的前提下，优先采用将额外位数分配给前序字段的处理方式，而非分配给后序字段。例如：

QTime time = QTime::fromString("00:710", "hh:ms"); // 7 mins, 10 secs after midnight

任何未在该格式中表示的字段将被设为零。例如：

QTime time = QTime::fromString("1.30", "m.s");
// time is 00:01:30.000

另请参阅 toString()、QDateTime::fromString()、QDate::fromString()、QLocale::toTime() 以及QLocale::toDateTime()。

[static, since 6.0] QTime QTime::fromString(QStringView string, QStringView format)

该函数在 Qt 6.0 中引入。

[static, since 6.0] QTime QTime::fromString(QStringView string, Qt::DateFormat format = Qt::TextDate)

该函数在 Qt 6.0 中引入。

[static, since 6.0] QTime QTime::fromString(const QString &string, QStringView format)

该函数在 Qt 6.0 中引入。

[static] QTime QTime::fromString(const QString &string, Qt::DateFormat format = Qt::TextDate)

使用给定的format ，将string 中表示的时间转换为QTime ，若无法转换，则返回无效时间。

另请参阅 toString() 和QLocale::toTime()。

int QTime::hour() const

返回时间中的小时部分（0 到 23）。

如果时间无效，则返回 -1。

另请参阅 minute()、second() 和msec()。

[constexpr] bool QTime::isNull() const

如果时间值为空（即QTime 对象是通过默认构造函数创建的），则返回true ；否则返回false。空时间值也被视为无效时间。

另请参阅 isValid()。

bool QTime::isValid() const

如果时间有效，则返回true ；否则返回false 。例如，时间23:30:55.746是有效的，但24:12:30是无效的。

另请参阅 isNull()。

[static] bool QTime::isValid(int h, int m, int s, int ms = 0)

如果指定的时间有效，则返回true ；否则返回false。

若h 处于 0 到 23 之间，m 和s 处于 0 到 59 之间，且ms 处于 0 到 999 之间，则该时间有效。

示例：

QTime::isValid(21, 10, 30); // returns true
QTime::isValid(22, 5,  62); // returns false

int QTime::minute() const

返回时间的分钟部分（0 到 59）。

如果时间无效，则返回 -1。

另请参阅 hour()、second() 和msec()。

int QTime::msec() const

返回时间的毫秒部分（0 到 999）。

如果时间无效，则返回 -1。

另请参阅 hour()、minute() 和second()。

[constexpr] int QTime::msecsSinceStartOfDay() const

返回自当天开始（即自 00:00:00 起）以来的毫秒数。

另请参阅 fromMSecsSinceStartOfDay()。

int QTime::msecsTo(QTime t) const

返回从当前时间到t 的时间差（以毫秒为单位）。如果t 早于当前时间，则返回的毫秒数为负值。

由于QTime 用于测量一天内的时间，而一天有86400秒，因此结果始终在-86400000至86400000毫秒之间。

如果任一时间无效，则返回 0。

另请参阅 secsTo()、addMSecs() 和QDateTime::msecsTo()。

int QTime::second() const

返回时间的第二部分（0 到 59）。

如果时间无效，则返回 -1。

另请参阅 hour()、minute() 和msec()。

int QTime::secsTo(QTime t) const

返回从当前时间到t 的秒数。如果t 早于当前时间，则返回的秒数为负数。

由于QTime 用于测量一天内的时间，而一天有86400秒，因此结果始终在-86400到86400之间。

secsTo() 不考虑毫秒。

如果任一时间无效，则返回 0。

另请参见 addSecs() 和QDateTime::secsTo()。

bool QTime::setHMS(int h, int m, int s, int ms = 0)

将时间设置为小时h 、分钟m 、秒s 和毫秒ms 。

h 必须在 0 到 23 之间，m 和s 必须在 0 到 59 之间，ms 必须在 0 到 999 之间。如果设置的时间有效，则返回true ；否则返回false 。

另请参阅 isValid()。

返回一个表示时间的字符串。

format 参数决定结果字符串的格式。如果时间无效，将返回一个空字符串。

可使用以下表达式：

当无法确定时区或没有合适的时区表示形式时，表示时区的t 形式可能会被跳过。有关何时返回空字符串的详细信息，请参阅QTimeZone::displayName()。

任何用单引号括起的非空字符序列都将原样包含在输出字符串中（去除引号），即使其中包含格式化字符也是如此。 两个连续的单引号（"''"）在输出中会被替换为一个单引号，而不是作为原样序列的开始或结束。格式字符串中的所有其他字符都会原样包含在输出字符串中。

支持不带分隔符的格式（例如 "hhmm"），但必须谨慎使用，因为生成的字符串并不总是可靠可读的（例如，如果 "Hm" 生成 "212"，它可能表示 02:12 或 21:02）。

格式字符串示例（假设QTime 为14:13:09.042）

另请参阅 fromString()、QDate::toString()、QDateTime::toString() 和QLocale::toString()。

QString QTime::toString(Qt::DateFormat format = Qt::TextDate) const

将时间作为字符串返回。format 参数用于确定字符串的格式。

如果format 为Qt::TextDate ，则字符串格式为 HH:mm:ss；例如，午夜前 1 秒将显示为 "23:59:59"。

如果 `format ` 为 `Qt::ISODate`，则字符串格式遵循 ISO 8601 扩展规范中关于日期表示的规定，即 HH:mm:ss。若要在 ISO 8601 日期中包含毫秒，请使用 `format ` `Qt::ISODateWithMs`，其对应格式为 HH:mm:ss.zzz。

如果format 为Qt::RFC2822Date ，则字符串将按RFC 2822兼容的方式进行格式化。此格式的一个示例是“23:59:20”。

如果时间无效，则返回一个空字符串。

另请参阅 fromString()、QDate::toString()、QDateTime::toString() 和QLocale::toString()。