ion-datetime
Datetimes 提供日历界面和时间轮，使用户可以轻松选择日期和时间。日期时间与 datetime-local 的原生 input 元素类似，但是，Ionic Framework 的日期时间组件可以轻松以首选格式显示日期和时间，并管理日期时间值。
¥Datetimes present a calendar interface and time wheel, making it easy for users to select dates and times. Datetimes are similar to the native input elements of datetime-local, however, Ionic Framework's Datetime component makes it easy to display the date and time in the preferred format, and manage the datetime values.
概述
¥Overview
从历史上看，在 JavaScript 中处理日期时间值，甚至在 HTML 输入中，一直是一个挑战。具体来说，JavaScript 的 Date 对象很难正确解析日期时间字符串或格式化日期时间值。更糟糕的是不同的浏览器和 JavaScript 版本以不同的方式解析各种日期时间字符串，尤其是针对每个区域设置。
¥Historically, handling datetime values within JavaScript, or even within HTML
inputs, has always been a challenge. Specifically, JavaScript's Date object is
notoriously difficult to correctly parse apart datetime strings or to format
datetime values. Even worse is how different browsers and JavaScript versions
parse various datetime strings differently, especially per locale.
幸运的是，Ionic Framework 的日期时间输入经过精心设计，使开发者可以避免常见的陷阱，从而使开发者能够轻松操作日期时间值，并为用户提供简单的日期时间选择器，以获得出色的用户体验。
¥Fortunately, Ionic Framework's datetime input has been designed so developers can avoid the common pitfalls, allowing developers to easily manipulate datetime values and give the user a simple datetime picker for a great user experience.
ISO 8601 日期时间格式：YYYY-MM-DDTHH:mmZ
¥ISO 8601 Datetime Format: YYYY-MM-DDTHH:mmZ
Ionic Framework 使用 ISO 8601 日期时间格式 作为其值。该值只是一个字符串，而不是使用 JavaScript 的 Date 对象。使用 ISO 日期时间格式可以轻松在 JSON 对象和数据库中进行序列化和解析。
¥Ionic Framework uses the ISO 8601 datetime format
for its value. The value is simply a string, rather than using JavaScript's
Date object. Using the ISO datetime format makes it easy to serialize
and parse within JSON objects and databases.
以下是可与 ion-datetime 一起使用的 ISO 8601 格式的一些示例：
¥Below are some examples of ISO 8601 formats that can be used with ion-datetime:
| 描述 | 格式 | 日期时间值示例 |
|---|---|---|
| 年 | YYYY | 1994 |
| 年月 | YYYY-MM | 1994-12 |
| 完成日期 | YYYY-MM-DD | 1994-12-15 |
| 日期和时间 | YYYY-MM-DDTHH:mm | 1994-12-15T13:47 |
| UTC 时区 | YYYY-MM-DDTHH:mm:ssZ | 1994-12-15T13:47:20Z |
| 时区偏移 | YYYY-MM-DDTHH:mm:ssTZD | 1994-12-15T13:47:20+05:00 |
| 小时和分钟 | HH:mm | 13:47 |
请注意，年份始终为四位数，毫秒（如果添加的话）始终为三位数，所有其他始终为两位数。因此，代表一月的数字总是有一个前导零，例如 01。此外，小时始终采用 24 小时格式，因此 00 在 12 小时制中是 12am，13 表示 1pm，23 表示 11pm。
¥Note that the year is always four-digits, milliseconds (if it's added) is always
three-digits, and all others are always two-digits. So the number representing
January always has a leading zero, such as 01. Additionally, the hour is
always in the 24-hour format, so 00 is 12am on a 12-hour clock, 13 means
1pm, and 23 means 11pm.
虽然可以使用 ISO 8601 日期时间格式指定秒、毫秒和时区，但 ion-datetime 不提供用于选择秒、毫秒和时区的接口。提供的任何秒、毫秒或时区值都将被忽略。
¥While seconds, milliseconds, and time zone can be specified using the ISO 8601 datetime format, ion-datetime does not provide an interface for second, millisecond, and time zone selection. Any second, millisecond, or time zone values provided will be ignored.
基本用法
¥Basic Usage
与日期时间按钮一起使用
¥Usage with Datetime Button
如果你需要在叠加层（例如模态框或弹出框）中显示日期时间，我们建议使用 ion-datetime-button。当空间有限时应使用 ion-datetime-button。该组件显示显示当前日期和时间值的按钮。点击按钮后，日期或时间选择器将在叠加层中打开。
¥If you need to present a datetime in an overlay such as a modal or a popover, we recommend using ion-datetime-button. ion-datetime-button should be used when space is constrained. This component displays buttons which show the current date and time values. When the buttons are tapped, the date or time pickers open in the overlay.
异步设置值
¥Setting Values Asynchronously
如果在创建日期时间后以编程方式更新其 value，则日期时间将自动跳转到新日期。但是，当用户能够与日期时间交互时，建议避免以这种方式更新 value，因为这可能会让当前尝试选择日期的用户感到迷惑。例如，如果异步进程加载日期时间的 value，建议使用 CSS 隐藏日期时间，直到该值完成更新。
¥If its value is updated programmatically after a datetime has already been created, the datetime will automatically jump to the new date. However, it is recommended to avoid updating the value in this way when users are able to interact with the datetime, as this could be disorienting for those currently trying to select a date. For example, if a datetime's value is loaded by an asynchronous process, it is recommended to hide the datetime with CSS until the value has finished updating.
日期限制
¥Date Constraints
最大和最小日期
¥Max and Min Dates
要自定义最小和最大日期时间值，可以提供 min 和 max 组件属性，这对于应用的用例可能更有意义。遵循上表中列出的相同 IS0 8601 格式，每个组件都可以限制用户可以选择的日期。
¥To customize the minimum and maximum datetime values, the min and max component properties can be provided which may make more sense for the app's use-case. Following the same IS0 8601 format listed in the table above, each component can restrict which dates can be selected by the user.
以下示例将日期选择限制为仅 2022 年 3 月到 2022 年 5 月。
¥The following example restricts date selection to March 2022 through May 2022 only.
选择特定值
¥Selecting Specific Values
虽然 min 和 max 属性允许你将日期选择限制在特定范围内，但 monthValues、dayValues、yearValues、hourValues 和 minuteValues 属性允许你选择用户可以选择的特定日期和时间。
¥While the min and max properties allow you to restrict date selection to a certain range, the monthValues, dayValues, yearValues, hourValues, and minuteValues properties allow you choose specific days and times that users can select.
以下示例允许以 15 为增量选择分钟。它还允许以 5 为增量选择天数。
¥The following example allows minutes to be selected in increments of 15. It also allows for days to be selected in increments of 5.
高级日期约束
¥Advanced Date Constraints
通过 isDateEnabled 属性，开发者可以自定义 ion-datetime 以禁用特定日期、日期范围、周末或使用 ISO 8601 日期字符串的任何自定义规则。isDateEnabled 属性接受返回布尔值的函数，指示是否启用日期。该函数会在每个渲染的日历日（上个月、当前月和下个月）调用。自定义实现应该针对性能进行优化，以避免卡顿。
¥With the isDateEnabled property, developers can customize the ion-datetime to disable a specific day, range of dates, weekends or any custom rule using an ISO 8601 date string.
The isDateEnabled property accepts a function returning a boolean, indicating if a date is enabled. The function is called for each rendered calendar day, for the previous, current and next month. Custom implementations should be optimized for performance to avoid jank.
以下示例显示如何禁用所有周末日期。对于更高级的日期操作，我们建议使用日期实用程序，例如 date-fns。
¥The following example shows how to disable all weekend dates. For more advanced date manipulation, we recommend using a date utility such as date-fns.
本土化
¥Localization
Ionic Framework 利用 Intl.DatetimeFormat Web API，它允许我们根据用户设备上设置的语言和区域自动本地化月份和日期名称。
¥Ionic Framework makes use of the Intl.DatetimeFormat Web API which allows us to automatically localize the month and day names according to the language and region set on the user's device.
自定义区域设置
¥Custom Locale
对于需要特定区域设置的情况，可以使用 locale 属性来设置它。区域设置控制显示的语言以及日期和时间格式。
¥For instances where you need a specific locale, you can use the locale property to set it. The locale controls both the language and the date and time formats that are displayed.
以下示例显示如何将区域设置设置为西班牙语（西班牙）。
¥The following example shows how to set the locale to Spanish (Spain).
时间标签不会自动本地化。请参阅 时间标签 了解更多信息。
¥The time label is not automatically localized. See Time Label for more information.
小时周期
¥Hour Cycle
默认情况下，ion-datetime 将使用 locale 属性指定的小时周期。例如，如果 locale 设置为 en-US，则 ion-datetime 将使用 12 小时周期。
¥ion-datetime will use the hour cycle that is specified by the locale property by default. For example, if locale is set to en-US, then ion-datetime will use a 12 hour cycle.
有 4 种主要的小时周期类型：
¥There are 4 primary hour cycle types:
| 小时循环型 | 描述 |
|---|---|
'h12' | 使用 1-12 的小时制；对应于模式中的 'h'。12 小时制，午夜从中午 12:00 开始。 |
'h23' | 使用 0–23 的小时制；对应于模式中的 'H'。24 小时制，午夜从 0:00 开始。 |
'h11' | 使用 0–11 的小时制；对应于模式中的 'K'。12 小时制，午夜从凌晨 0:00 开始。 |
'h24' | 使用 1–24 的小时制；对应于模式中的 'k'。24 小时制，午夜从 24:00 开始。 |
在某些情况下，你可能需要更好地控制使用哪个小时周期。这就是 hourCycle 属性可以提供帮助的地方。
¥There may be scenarios where you need to have more control over which hour cycle is used. This is where the hourCycle property can help.
在以下示例中，我们可以使用 hourCycle 属性强制 ion-datetime 使用 12 小时周期，即使区域设置为 en-GB（默认情况下使用 24 小时周期）：
¥In the following example, we can use the hourCycle property to force ion-datetime to use the 12 hour cycle even though the locale is en-GB, which uses a 24 hour cycle by default:
一周的第一天
¥First Day of the Week
对于 ion-datetime，一周的默认第一天是星期日。截至 2022 年，还没有浏览器 API 可以让 Ionic 根据设备的区域设置自动确定一周的第一天，尽管相关工作正在进行中（请参阅：TC39 GitHub）。
¥For ion-datetime, the default first day of the week is Sunday. As of 2022, there is no browser API that lets Ionic automatically determine the first day of the week based on a device's locale, though there is on-going work regarding this (see: TC39 GitHub).
时间标签
¥Time Label
时间标签不会自动本地化。幸运的是，Ionic 可以轻松地使用 time-label 插槽提供自定义本地化。
¥The time label is not automatically localized. Fortunately, Ionic makes it easy to provide custom localizations with the time-label slot.
区域设置扩展标签
¥Locale Extension Tags
ion-datetime 还支持 语言环境扩展标签 作为 Intl.Locale API 的一部分。这些标签允许你在区域设置字符串本身中编码有关区域设置的信息。如果开发者在应用中使用 Intl.Locale API，他们可能更喜欢使用扩展标签方法。
¥ion-datetime also supports locale extension tags as part of the Intl.Locale API. These tags let you encode information about the locale in the locale string itself. Developers may prefer to use the extension tag approach if they are using the Intl.Locale API in their apps.
例如，如果你想在 en-GB 区域设置中使用 12 小时周期，则可以提供扩展标记，而不是同时使用 locale 和 hourCycle 属性：
¥For example, if you wanted to use a 12 hour cycle with the en-GB locale, you could provide extension tags instead of using both the locale and hourCycle properties:
在你的应用中使用之前，请务必检查 浏览器兼容性图表 是否有 Intl.Locale。
¥Be sure to check the Browser Compatibility Chart for Intl.Locale before using it in your app.
渲染
¥Presentation
默认情况下，ion-datetime 允许用户选择日期和时间。此外，用户还可以选择特定的月、年、小时和分钟。
¥By default, ion-datetime allows users to select both date and time. In addition, users have access to selecting the specific month, year, hour, and minute.
某些用例可能仅需要日期选择或仅时间选择。presentation 属性允许你指定要显示的选取器以及它们的显示顺序。例如，设置 date-time 将使日历选择器出现在时间选择器之前。设置 time-date 将使日历选择器出现在时间选择器之后。
¥Some use cases may call for only date selection or only time selection. The presentation property allows you to specify which pickers to show and the order to show them in. For example, setting date-time will have the calendar picker appear before the time picker. Setting time-date will have the calendar picker appear after the time picker.
月份和年份选择
¥Month and Year Selection
通过将 month-year、month 或 year 传递给 presentation 属性，可以选择月份和年份。
¥Month and year selection is available by passing month-year, month, or year to the presentation property.
此示例显示具有 month-year 配置的日期时间。
¥This example shows a datetime with the month-year configuration.
时间选择
¥Time Selection
通过将 date-time、time-date 或 time 传递给 presentation 属性可以选择时间。
¥Time selection is available by passing date-time, time-date, or time to the presentation property.
此示例显示具有 time 配置的日期时间。
¥This example shows a datetime with the time configuration.
日期选择
¥Date Selection
通过将 date-time、time-date 或 date 传递给 presentation 属性可以选择日期。
¥Date selection is available by passing date-time, time-date, or date to the presentation property.
此示例显示具有 date 配置的日期时间。
¥This example shows a datetime with the date configuration.
轮式拾取器
¥Wheel Style Pickers
默认情况下，Ionic 在使用 presentation 时更喜欢显示网格样式布局。但是，可以使用 preferWheel 属性显示车轮样式。当 preferWheel 为 true 时，Ionic 会尽可能显示轮式布局。
¥By default, Ionic will prefer to show a grid style layout when using presentation. However, it is possible to show a wheel style using the preferWheel property. When preferWheel is true, Ionic will prefer to show the wheel style layout when possible.
某些 presentation 选项同时具有网格和滚轮样式，开发者可以通过 preferWheel 属性进行选择。其他 presentation 值只有轮子样式，永远不会显示网格样式。下表显示了哪些 presentation 值具有网格或滚轮样式。
¥Certain presentation options have both grid and wheel styles that developers can choose from with the preferWheel property. Other presentation values only have a wheel style and will never show a grid style. The table below shows which presentation values have grid or wheel styles.
presentation | 有网格样式吗？ | 有轮毂样式吗？ |
|---|---|---|
date | 是的 | 是的 |
date-time | 是的 | 是的 |
month | 不 | 是的 |
month-year | 不 | 是的 |
time | 不 | 是的 |
time-date | 是的 | 是的 |
year | 不 | 是的 |
下面的示例显示了带有 presentation="date-time" 的轮式拾取器。
¥The example below shows the wheel picker with presentation="date-time".
多个日期选择
¥Multiple Date Selection
如果 multiple 属性设置为 true，则可以从日历选择器中选择多个日期。单击选定的日期将取消选择它。
¥If the multiple property is set to true, multiple dates can be selected from the calendar picker. Clicking a selected date will deselect it.
仅当使用 presentation="date" 和 preferWheel="false" 时才支持此属性。
¥This property is only supported when using presentation="date" and preferWheel="false".
标题
¥Titles
默认情况下，ion-datetime 不显示与该组件关联的任何标题或标题。开发者可以使用 showDefaultTitle 属性来显示默认的标题/页眉配置。他们还可以使用 title 插槽来自定义标头中渲染的内容。
¥By default, ion-datetime does not show any header or title associated with the component. Developers can use the showDefaultTitle property to show the default title/header configuration. They can also use the title slot to customize what is rendered in the header.
显示默认标题
¥Showing the Default Title
自定义标题
¥Customizing the Title
格式选项
¥Format Options
你可以通过提供 formatOptions.DateTime 来自定义日期时间组件的标题文本中的日期格式和时间按钮中的时间格式。formatOptions 属性中的 date 和 time 都应该是 Intl.DateTimeFormatOptions 对象。如果未提供 formatOptions，则日期和时间将使用默认格式。
¥You can customize the format of the date in the header text and the time in the time button of a Datetime component by providing formatOptions. The date and time in the formatOptions property should each be an Intl.DateTimeFormatOptions object. If formatOptions is not provided, default formats will be used for dates and times.
日期时间 不操纵或设置 时区。如果提供了 timeZone 或 timeZoneName，它们将被忽略，时区将设置为 UTC。这可确保显示的值与所选值匹配，而不是转换为用户当前的时区。
¥Datetime does not manipulate or set the time zone. If timeZone or timeZoneName are provided, they will be ignored, and the time zone will be set to UTC. This ensures that the displayed value matches the selected value, rather than being converted to the user's current time zone.
请小心你提供的选项，因为它们可能与所选的演示文稿不匹配。例如，为 month 的演示文稿提供 minute: 'numeric' 可能会导致意外行为，即仅显示可能预期的时间的月份。
¥Be careful with the options you provide, as they may not match the selected presentation. For example, providing minute: 'numeric' for a presentation of month may lead to unexpected behavior, displaying a month where only a time might be expected.
按钮
¥Buttons
默认情况下，每当选择新日期时，都会使用新的日期时间值发出 ionChange。要在发出 ionChange 之前要求用户确认，你可以将 showDefaultButtons 属性设置为 true 或使用 buttons 插槽传入自定义确认按钮。传入自定义按钮时，确认按钮必须调用 ion-datetime 上的 confirm 方法才能发出 ionChange。
¥By default, ionChange is emitted with the new datetime value whenever a new date is selected. To require user confirmation before emitting ionChange, you can either set the showDefaultButtons property to true or use the buttons slot to pass in a custom confirmation button. When passing in custom buttons, the confirm button must call the confirm method on ion-datetime for ionChange to be emitted.
显示确认按钮
¥Showing Confirmation Buttons
默认的“完成”和“取消”按钮已预先配置为分别调用 confirm 和 cancel 方法。
¥The default Done and Cancel buttons are already preconfigured to call the confirm and cancel methods, respectively.
自定义按钮文本
¥Customizing Button Texts
对于简单的用例，开发者可以通过 doneText 和 cancelText 属性为确认和取消值提供自定义按钮文本。当你只需要更改按钮文本而不需要任何自定义行为时，我们建议你这样做。
¥For simple use cases, developers can provide custom button text to the confirmation and cancel values through the doneText and cancelText properties. We recommend doing this when you only need to change the button text and do not need any custom behavior.
自定义按钮元素
¥Customizing Button Elements
开发者可以提供自己的按钮来实现高级自定义行为。
¥Developers can provide their own buttons for advanced custom behavior.
ion-datetime 有 confirm、cancel 和 reset 方法，开发者可以在单击自定义按钮时调用这些方法。reset 方法还允许开发者提供将日期时间重置为的日期。
¥ion-datetime has confirm, cancel, and reset methods that developers can call when clicking on custom buttons. The reset method also allows developers to provide a date to reset the datetime to.
高亮特定日期
¥Highlighting Specific Dates
使用 highlightedDates 属性，开发者可以使用自定义文本或背景颜色设置特定日期的样式。此属性可以定义为日期及其颜色的数组，也可以定义为接收 ISO 字符串并返回要使用的颜色的回调。
¥Using the highlightedDates property, developers can style particular dates with custom text or background colors. This property can be defined as either an array of dates and their colors, or a callback that receives an ISO string and returns the colors to use.
指定颜色时，可以使用任何有效的 CSS 颜色格式。这包括十六进制代码、rgba、颜色变量 等。
¥When specifying colors, any valid CSS color format can be used. This includes hex codes, rgba, color variables, etc.
为了保持一致的用户体验，所选日期的样式将始终覆盖自定义高亮。
¥To maintain a consistent user experience, the style of selected date(s) will always override custom highlights.
仅当 preferWheel="false" 且使用 "date"、"date-time" 或 "time-date" 的 presentation 时才支持此属性。
¥This property is only supported when preferWheel="false", and using a presentation of either "date", "date-time", or "time-date".
使用数组
¥Using Array
当高亮应用于固定日期（例如截止日期）时，数组会更好。
¥An array is better when the highlights apply to fixed dates, such as due dates.
使用回调
¥Using Callback
当高亮的日期重复出现时（例如生日或重复会议），回调效果更好。
¥A callback is better when the highlighted dates are recurring, such as birthdays or recurring meetings.
样式
¥Styling
全局主题
¥Global Theming
Ionic 强大的主题系统可用于轻松更改整个应用以匹配特定主题。在此示例中，我们使用 色彩创造者 和 阶梯式颜色生成器 创建可用于 ion-datetime 的玫瑰色调色板。
¥Ionic's powerful theming system can be used to easily change your entire app to match a certain theme. In this example, we used the Color Creator and the Stepped Color Generator to create a rose color palette that we can use for ion-datetime.
这种方法的好处是每个组件，而不仅仅是 ion-datetime，都可以自动利用这个主题。
¥The benefit of this approach is that every component, not just ion-datetime, can automatically take advantage of this theme.
日历日
¥Calendar Days
网格样式 ion-datetime 中的日历日可以使用 CSS 阴影部分进行样式设置。
¥The calendar days in a grid-style ion-datetime can be styled using CSS shadow parts.
下面的示例选择 2 天前的一天，除非该天是上个月，否则选择 2 天后的一天。这样做是为了演示目的，以展示如何将自定义样式应用于所有日期、当前日期和选定日期。
¥The example below selects the day 2 days ago, unless that day is in the previous month, then it selects a day 2 days in the future. This is done for demo purposes in order to show how to apply custom styling to all days, the current day, and the selected day.
轮式拾取器
¥Wheel Pickers
ion-datetime 中使用的轮子可以通过阴影部分和 CSS 变量的组合来设计样式。这适用于轮式日期时间中的列以及网格式日期时间中的月/年选择器。
¥The wheels used in ion-datetime can be styled through a combination of shadow parts and CSS variables. This applies to both the columns in wheel-style datetimes, and the month/year picker in grid-style datetimes.
时区
¥Time Zones
Ionic 的 ion-datetime 遵循 datetime-local 的行为，即不在日期时间控件内操作或设置时区。也就是说，"07:00" 的时间值不会根据不同的时区进行调整。
¥Ionic's ion-datetime follows the datetime-local behavior of not manipulating or setting the time zone inside of a datetime control. In other words, a time value of "07:00" will not be adjusted according to different time zones.
我们建议使用 date-fns-tz 等库将日期时间值转换为所需的时区。
¥We recommend using a library such as date-fns-tz to convert a datetime value to the desired time zone.
以下是格式化 ISO-8601 字符串以在用户设备上设置的时区中显示的示例：
¥Below is an example of formatting an ISO-8601 string to display in the time zone set on a user's device:
import { format, utcToZonedTime } from 'date-fns-tz';
// Get the time zone set on the user's device
const userTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
// Create a date object from a UTC date string
const date = new Date('2014-10-25T10:46:20Z');
// Use date-fns-tz to convert from UTC to a zoned time
const zonedTime = utcToZonedTime(date, userTimeZone);
// Create a formatted string from the zoned time
format(zonedTime, 'yyyy-MM-dd HH:mm:ssXXX', { timeZone: userTimeZone });
解析日期值
¥Parsing Date Values
ionChange 事件将在事件负载中以 ISO-8601 字符串形式发出日期值。开发者有责任根据其应用需求对其进行格式化。我们建议使用 date-fns 来格式化日期值。
¥The ionChange event will emit the date value as an ISO-8601 string in the event payload. It is the developer's responsibility to format it based on their application needs. We recommend using date-fns to format the date value.
下面是格式化 ISO-8601 字符串以显示月份、日期和年份的示例：
¥Below is an example of formatting an ISO-8601 string to display the month, date and year:
import { format, parseISO } from 'date-fns';
/**
* This is provided in the event
* payload from the `ionChange` event.
* * The value is an ISO-8601 date string.
*/
const dateFromIonDatetime = '2021-06-04T14:23:00-04:00';
const formattedString = format(parseISO(dateFromIonDatetime), 'MMM d, yyyy');
console.log(formattedString); // Jun 4, 2021
有关所有有效格式标记的列表，请参阅 https://date-fns.org/docs/format。
¥See https://date-fns.org/docs/format for a list of all the valid format tokens.
高级日期时间验证和操作
¥Advanced Datetime Validation and Manipulation
日期时间选择器提供了选择精确格式的简单性，并使用标准化的 ISO 8601 日期时间格式 将日期时间值保留为字符串。但是，请务必注意，ion-datetime 并不尝试在验证和操作日期时间值时解决所有情况。如果需要从某种格式解析日期时间值，或对其进行操作（例如向日期添加 5 天、减去 30 分钟等），甚至将数据格式化为特定区域设置，那么我们强烈建议使用 date-fns 来处理 JavaScript 中的日期。
¥The datetime picker provides the simplicity of selecting an exact format, and
persists the datetime values as a string using the standardized ISO 8601
datetime format. However, it's important
to note that ion-datetime does not attempt to solve all situations when
validating and manipulating datetime values. If datetime values need to be
parsed from a certain format, or manipulated (such as adding 5 days to a date,
subtracting 30 minutes, etc.), or even formatting data to a specific locale,
then we highly recommend using date-fns to work with
dates in JavaScript.
无障碍
¥Accessibility
键盘交互
¥Keyboard Interactions
ion-datetime 具有完整的键盘支持，可在组件内部的可聚焦元素之间进行导航。下表详细说明了每个键的作用：
¥ion-datetime has full keyboard support for navigating between focusable elements inside of the component. The following table details what each key does:
| 密钥 | 描述 |
|---|---|
| Tab | 将焦点移至下一个可聚焦元素。 |
| Shift + Tab | 将焦点移至上一个可聚焦元素。 |
| Space 或 Enter | 单击可聚焦元素。 |
日期网格
¥Date Grid
| 密钥 | 描述 |
|---|---|
| ArrowUp | 将焦点移至上周的同一天。 |
| ArrowDown | 将焦点移至下周的同一天。 |
| ArrowRight | 将焦点移至第二天。 |
| ArrowLeft | 将焦点移至前一天。 |
| Home | 将焦点移至本周的第一天。 |
| End | 将焦点移至本周的最后一天。 |
| PageUp | 将日期网格更改为上个月。 |
| PageDown | 将日期网格更改为下个月。 |
| Shift + PageUp | 将日期网格更改为上一年。 |
| Shift + PageDown | 将日期网格更改为下一年。 |
时间、月份和年份轮
¥Time, Month, and Year Wheels
Datetime 中的轮式选择器内部使用 拾取器。有关轮式拾取器辅助功能的更多信息，请参阅 选择器辅助功能。
¥The wheel picker in Datetime uses Picker internally. See Picker Accessibility for more information on accessibility features with the wheel picker.
接口
¥Interfaces
DatetimeChangeEventDetail
interface DatetimeChangeEventDetail {
value?: string | null;
}
DatetimeCustomEvent
虽然不是必需的，但可以使用此接口代替 CustomEvent 接口，以便使用从此组件发出的 Ionic 事件进行更强的键入。
¥While not required, this interface can be used in place of the CustomEvent interface for stronger typing with Ionic events emitted from this component.
interface DatetimeCustomEvent extends CustomEvent {
detail: DatetimeChangeEventDetail;
target: HTMLIonDatetimeElement;
}
属性
¥Properties
cancelText
| Description | The text to display on the picker's cancel button. |
| Attribute | cancel-text |
| Type | string |
| Default | 'Cancel' |
clearText
| Description | The text to display on the picker's "Clear" button. |
| Attribute | clear-text |
| Type | string |
| Default | 'Clear' |
color
| Description | The color to use from your application's color palette. Default options are: "primary", "secondary", "tertiary", "success", "warning", "danger", "light", "medium", and "dark". For more information on colors, see theming. |
| Attribute | color |
| Type | "danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined |
| Default | 'primary' |
dayValues
| Description | Values used to create the list of selectable days. By default every day is shown for the given month. However, to control exactly which days of the month to display, the dayValues input can take a number, an array of numbers, or a string of comma separated numbers. Note that even if the array days have an invalid number for the selected month, like 31 in February, it will correctly not show days which are not valid for the selected month. |
| Attribute | day-values |
| Type | number ｜ number[] ｜ string ｜ undefined |
| Default | undefined |
disabled
| Description | If true, the user cannot interact with the datetime. |
| Attribute | disabled |
| Type | boolean |
| Default | false |
doneText
| Description | The text to display on the picker's "Done" button. |
| Attribute | done-text |
| Type | string |
| Default | 'Done' |
firstDayOfWeek
| Description | The first day of the week to use for ion-datetime. The default value is 0 and represents Sunday. |
| Attribute | first-day-of-week |
| Type | number |
| Default | 0 |
formatOptions
| Description | Formatting options for dates and times. Should include a 'date' and/or 'time' object, each of which is of type Intl.DateTimeFormatOptions. |
| Attribute | undefined |
| Type | undefined ｜ { date: DateTimeFormatOptions; time?: DateTimeFormatOptions ｜ undefined; } ｜ { date?: DateTimeFormatOptions ｜ undefined; time: DateTimeFormatOptions; } |
| Default | undefined |
highlightedDates
| Description | Used to apply custom text and background colors to specific dates. Can be either an array of objects containing ISO strings and colors, or a callback that receives an ISO string and returns the colors. Only applies to the date, date-time, and time-date presentations, with preferWheel="false". |
| Attribute | undefined |
| Type | ((dateIsoString: string) => DatetimeHighlightStyle ｜ undefined) ｜ DatetimeHighlight[] ｜ undefined |
| Default | undefined |
hourCycle
| Description | The hour cycle of the ion-datetime. If no value is set, this is specified by the current locale. |
| Attribute | hour-cycle |
| Type | "h11" ｜ "h12" ｜ "h23" ｜ "h24" ｜ undefined |
| Default | undefined |
hourValues
| Description | Values used to create the list of selectable hours. By default the hour values range from 0 to 23 for 24-hour, or 1 to 12 for 12-hour. However, to control exactly which hours to display, the hourValues input can take a number, an array of numbers, or a string of comma separated numbers. |
| Attribute | hour-values |
| Type | number ｜ number[] ｜ string ｜ undefined |
| Default | undefined |
isDateEnabled
| Description | Returns if an individual date (calendar day) is enabled or disabled. If true, the day will be enabled/interactive. If false, the day will be disabled/non-interactive.The function accepts an ISO 8601 date string of a given day. By default, all days are enabled. Developers can use this function to write custom logic to disable certain days. The function is called for each rendered calendar day, for the previous, current and next month. Custom implementations should be optimized for performance to avoid jank. |
| Attribute | undefined |
| Type | ((dateIsoString: string) => boolean) ｜ undefined |
| Default | undefined |
locale
| Description | The locale to use for ion-datetime. This impacts month and day name formatting. The "default" value refers to the default locale set by your device. |
| Attribute | locale |
| Type | string |
| Default | 'default' |
max
| Description | The maximum datetime allowed. Value must be a date string following the ISO 8601 datetime format standard, 1996-12-19. The format does not have to be specific to an exact datetime. For example, the maximum could just be the year, such as 1994. Defaults to the end of this year. |
| Attribute | max |
| Type | string ｜ undefined |
| Default | undefined |
min
| Description | The minimum datetime allowed. Value must be a date string following the ISO 8601 datetime format standard, such as 1996-12-19. The format does not have to be specific to an exact datetime. For example, the minimum could just be the year, such as 1994. Defaults to the beginning of the year, 100 years ago from today. |
| Attribute | min |
| Type | string ｜ undefined |
| Default | undefined |
minuteValues
| Description | Values used to create the list of selectable minutes. By default the minutes range from 0 to 59. However, to control exactly which minutes to display, the minuteValues input can take a number, an array of numbers, or a string of comma separated numbers. For example, if the minute selections should only be every 15 minutes, then this input value would be minuteValues="0,15,30,45". |
| Attribute | minute-values |
| Type | number ｜ number[] ｜ string ｜ undefined |
| Default | undefined |
mode
| Description | The mode determines which platform styles to use. |
| Attribute | mode |
| Type | "ios" ｜ "md" |
| Default | undefined |
monthValues
| Description | Values used to create the list of selectable months. By default the month values range from 1 to 12. However, to control exactly which months to display, the monthValues input can take a number, an array of numbers, or a string of comma separated numbers. For example, if only summer months should be shown, then this input value would be monthValues="6,7,8". Note that month numbers do not have a zero-based index, meaning January's value is 1, and December's is 12. |
| Attribute | month-values |
| Type | number ｜ number[] ｜ string ｜ undefined |
| Default | undefined |
multiple
| Description | If true, multiple dates can be selected at once. Only applies to presentation="date" and preferWheel="false". |
| Attribute | multiple |
| Type | boolean |
| Default | false |
name
| Description | The name of the control, which is submitted with the form data. |
| Attribute | name |
| Type | string |
| Default | this.inputId |
preferWheel
| Description | If true, a wheel picker will be rendered instead of a calendar grid where possible. If false, a calendar grid will be rendered instead of a wheel picker where possible.A wheel picker can be rendered instead of a grid when presentation is one of the following values: "date", "date-time", or "time-date".A wheel picker will always be rendered regardless of the preferWheel value when presentation is one of the following values: "time", "month", "month-year", or "year". |
| Attribute | prefer-wheel |
| Type | boolean |
| Default | false |
presentation
| Description | Which values you want to select. "date" will show a calendar picker to select the month, day, and year. "time" will show a time picker to select the hour, minute, and (optionally) AM/PM. "date-time" will show the date picker first and time picker second. "time-date" will show the time picker first and date picker second. |
| Attribute | presentation |
| Type | "date" ｜ "date-time" ｜ "month" ｜ "month-year" ｜ "time" ｜ "time-date" ｜ "year" |
| Default | 'date-time' |
readonly
| Description | If true, the datetime appears normal but the selected date cannot be changed. |
| Attribute | readonly |
| Type | boolean |
| Default | false |
showClearButton
| Description | If true, a "Clear" button will be rendered alongside the default "Cancel" and "OK" buttons at the bottom of the ion-datetime component. Developers can also use the button slot if they want to customize these buttons. If custom buttons are set in the button slot then the default buttons will not be rendered. |
| Attribute | show-clear-button |
| Type | boolean |
| Default | false |
showDefaultButtons
| Description | If true, the default "Cancel" and "OK" buttons will be rendered at the bottom of the ion-datetime component. Developers can also use the button slot if they want to customize these buttons. If custom buttons are set in the button slot then the default buttons will not be rendered. |
| Attribute | show-default-buttons |
| Type | boolean |
| Default | false |
showDefaultTimeLabel
| Description | If true, the default "Time" label will be rendered for the time selector of the ion-datetime component. Developers can also use the time-label slot if they want to customize this label. If a custom label is set in the time-label slot then the default label will not be rendered. |
| Attribute | show-default-time-label |
| Type | boolean |
| Default | true |
showDefaultTitle
| Description | If true, a header will be shown above the calendar picker. This will include both the slotted title, and the selected date. |
| Attribute | show-default-title |
| Type | boolean |
| Default | false |
size
| Description | If cover, the ion-datetime will expand to cover the full width of its container. If fixed, the ion-datetime will have a fixed width. |
| Attribute | size |
| Type | "cover" ｜ "fixed" |
| Default | 'fixed' |
titleSelectedDatesFormatter
| Description | A callback used to format the header text that shows how many dates are selected. Only used if there are 0 or more than 1 selected (i.e. unused for exactly 1). By default, the header text is set to "numberOfDates days". See https://ionicframework.com/docs/troubleshooting/runtime#accessing-this if you need to access this from within the callback. |
| Attribute | undefined |
| Type | ((selectedDates: string[]) => string) ｜ undefined |
| Default | undefined |
value
| Description | The value of the datetime as a valid ISO 8601 datetime string. This should be an array of strings only when multiple="true". |
| Attribute | value |
| Type | null ｜ string ｜ string[] ｜ undefined |
| Default | undefined |
yearValues
| Description | Values used to create the list of selectable years. By default the year values range between the min and max datetime inputs. However, to control exactly which years to display, the yearValues input can take a number, an array of numbers, or string of comma separated numbers. For example, to show upcoming and recent leap years, then this input's value would be yearValues="2008,2012,2016,2020,2024". |
| Attribute | year-values |
| Type | number ｜ number[] ｜ string ｜ undefined |
| Default | undefined |
事件
¥Events
| Name | Description | Bubbles |
|---|---|---|
ionBlur | Emitted when the datetime loses focus. | true |
ionCancel | Emitted when the datetime selection was cancelled. | true |
ionChange | Emitted when the value (selected date) has changed. This event will not emit when programmatically setting the value property. | true |
ionFocus | Emitted when the datetime has focus. | true |
方法
¥Methods
cancel
| Description | Emits the ionCancel event and optionally closes the popover or modal that the datetime was presented in. |
| Signature | cancel(closeOverlay?: boolean) => Promise<void> |
confirm
| Description | Confirms the selected datetime value, updates the value property, and optionally closes the popover or modal that the datetime was presented in. |
| Signature | confirm(closeOverlay?: boolean) => Promise<void> |
reset
| Description | Resets the internal state of the datetime but does not update the value. Passing a valid ISO-8601 string will reset the state of the component to the provided date. If no value is provided, the internal state will be reset to the clamped value of the min, max and today. |
| Signature | reset(startDate?: string) => Promise<void> |
CSS 阴影部分
¥CSS Shadow Parts
| Name | Description |
|---|---|
calendar-day | The individual buttons that display a day inside of the datetime calendar. |
calendar-day active | The currently selected calendar day. |
calendar-day disabled | The calendar day that is disabled. |
calendar-day today | The calendar day that contains the current day. |
month-year-button | The button that opens the month/year picker when using a grid style layout. |
time-button | The button that opens the time picker when using a grid style layout with presentation="date-time" or "time-date". |
time-button active | The time picker button when the picker is open. |
wheel-item | The individual items when using a wheel style layout, or in the month/year picker when using a grid style layout. |
wheel-item active | The currently selected wheel-item. |
CSS 自定义属性
¥CSS Custom Properties
- iOS
- MD
| Name | Description |
|---|---|
--background | The primary background of the datetime component. |
--background-rgb | The primary background of the datetime component in RGB format. |
--title-color | The text color of the title. |
--wheel-fade-background-rgb | The color of the gradient covering non-selected items when using a wheel style layout, or in the month/year picker for grid style layouts. Must be in RGB format, e.g. 255, 255, 255. |
--wheel-highlight-background | The background of the highlight under the selected item when using a wheel style layout, or in the month/year picker for grid style layouts. |
--wheel-highlight-border-radius | The border radius of the highlight under the selected item when using a wheel style layout, or in the month/year picker for grid style layouts. |
| Name | Description |
|---|---|
--background | The primary background of the datetime component. |
--background-rgb | The primary background of the datetime component in RGB format. |
--title-color | The text color of the title. |
--wheel-fade-background-rgb | The color of the gradient covering non-selected items when using a wheel style layout, or in the month/year picker for grid style layouts. Must be in RGB format, e.g. 255, 255, 255. |
--wheel-highlight-background | The background of the highlight under the selected item when using a wheel style layout, or in the month/year picker for grid style layouts. |
--wheel-highlight-border-radius | The border radius of the highlight under the selected item when using a wheel style layout, or in the month/year picker for grid style layouts. |
插槽
¥Slots
| Name | Description |
|---|---|
buttons | The buttons in the datetime. |
time-label | The label for the time selector in the datetime. |
title | The title of the datetime. |