DateTime
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
表示民用时间（有时也表示实际时间）。
此类型可以通过以下几种可能的方式之一表示民用时间：
- 当 utcOffset 已设置且 timeZone 未设置时：日历日的民用时间，相对于世界协调时间 (UTC) 有特定偏移量。
- 如果已设置 timeZone 且未设置 utcOffset：特定时区中某个日历日的民用时间。
- 如果未设置 timeZone 和 utcOffset：则为日历日的民用时间（以当地时间为准）。
日期相对于前公历。
如果年份、月份或日期为 0，则 DateTime 会被视为分别不具有特定的年份、月份或日期。
如果所有日期和时间字段均已设置，并且 time_offset oneof 的任一情况均已设置，则此类型还可用于表示实际时间。请考虑改用 Timestamp 消息来表示实际时间。如果您的用例还需要存储用户的时区，则可以在其他字段中执行此操作。
此类型的灵活性可能超出了某些应用的需求。请务必记录并验证应用的限制。
| JSON 表示法 |
{
"year": integer,
"month": integer,
"day": integer,
"hours": integer,
"minutes": integer,
"seconds": integer,
"nanos": integer,
// Union field time_offset can be only one of the following:
"utcOffset": string,
"timeZone": {
object (TimeZone)
}
// End of list of possible types for union field time_offset.
} |
| 字段 |
year |
integer
可选。某年。必须介于 1 到 9999 之间，如果指定不含年份的日期时间，则为 0。
|
month |
integer
可选。月份。必须介于 1 到 12 之间，如果指定日期时间但未指定月份，则为 0。
|
day |
integer
可选。某日。必须介于 1 到 31 之间并且对年份和月份有效，如果指定日期时间但不指定日期，则为 0。
|
hours |
integer
可选。一天中的小时（采用 24 小时制）。应介于 0 到 23 之间，默认为 0（午夜）。对于业务结束时间等场景，API 可以选择允许“24:00:00”一值。
|
minutes |
integer
可选。一天中某小时的分钟数。必须是 0 到 59 之间的数字，默认为 0。
|
seconds |
integer
可选。时间的秒数部分。通常必须是 0 到 59 之间的数字，默认为 0。如果 API 允许闰秒，则 API 可以允许 60 一值。
|
nanos |
integer
可选。秒数的小数部分（以纳秒为单位）。必须介于 0 到 999,999,999 之间，默认为 0。
|
联合字段 time_offset。可选。指定 DateTime 的 UTC 偏移量或时区。请谨慎选择这两者，因为时区数据未来可能会发生变化（例如，某个国家/地区修改了夏令时开始/结束日期，而受影响范围内的未来日期时间已存储）。如果省略，则 DateTime 会被视为当地时间。time_offset 只能是下列其中一项： |
utcOffset |
string (Duration format)
UTC 偏移量。必须是整秒数，介于 -18 小时到 +18 小时之间。例如，-4:00 的 UTC 偏移量将表示为 { seconds: -14400 }。 该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
|
timeZone |
object (TimeZone)
时区。
|
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-08-29。
[null,null,["最后更新时间 (UTC)：2025-08-29。"],[],[],null,["# DateTime\n\n- [JSON representation](#SCHEMA_REPRESENTATION)\n\nRepresents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n- When utcOffset is set and timeZone is unset: a civil time on a calendar day with a particular offset from UTC.\n- When timeZone is set and utcOffset is unset: a civil time on a calendar day in a particular time zone.\n- When neither timeZone nor utcOffset is set: a civil time on a calendar day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year, month, or day are 0, the DateTime is considered not to have a specific year, month, or day respectively.\n\nThis type may also be used to represent a physical time if all the date and time fields are set and either case of the `time_offset` oneof is set. Consider using `Timestamp` message for physical time instead. If your use case also would like to store the user's timezone, that can be done in another field.\n\nThis type is more flexible than some applications may want. Make sure to document and validate your application's limitations.\n\n| JSON representation |\n|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ``` { \"year\": integer, \"month\": integer, \"day\": integer, \"hours\": integer, \"minutes\": integer, \"seconds\": integer, \"nanos\": integer, // Union field `time_offset` can be only one of the following: \"utcOffset\": string, \"timeZone\": { object (/maps/documentation/weather/reference/rest/v1/TimeZone) } // End of list of possible types for union field `time_offset`. } ``` |\n\n| Fields ||\n|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `year` | `integer` Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a datetime without a year. |\n| `month` | `integer` Optional. Month of year. Must be from 1 to 12, or 0 if specifying a datetime without a month. |\n| `day` | `integer` Optional. Day of month. Must be from 1 to 31 and valid for the year and month, or 0 if specifying a datetime without a day. |\n| `hours` | `integer` Optional. Hours of day in 24 hour format. Should be from 0 to 23, defaults to 0 (midnight). An API may choose to allow the value \"24:00:00\" for scenarios like business closing time. |\n| `minutes` | `integer` Optional. Minutes of hour of day. Must be from 0 to 59, defaults to 0. |\n| `seconds` | `integer` Optional. Seconds of minutes of the time. Must normally be from 0 to 59, defaults to 0. An API may allow the value 60 if it allows leap-seconds. |\n| `nanos` | `integer` Optional. Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999, defaults to 0. |\n| Union field `time_offset`. Optional. Specifies either the UTC offset or the time zone of the DateTime. Choose carefully between them, considering that time zone data may change in the future (for example, a country modifies their DST start/end dates, and future DateTimes in the affected range had already been stored). If omitted, the DateTime is considered to be in local time. `time_offset` can be only one of the following: ||\n| `utc``Offset` | `string (`[Duration](https://protobuf.dev/reference/protobuf/google.protobuf/#duration)` format)` UTC offset. Must be whole seconds, between -18 hours and +18 hours. For example, a UTC offset of -4:00 would be represented as { seconds: -14400 }. A duration in seconds with up to nine fractional digits, ending with '`s`'. Example: `\"3.5s\"`. |\n| `time``Zone` | `object (`[TimeZone](/maps/documentation/weather/reference/rest/v1/TimeZone)`)` Time zone. |"]]
