ion-datetime
日期時間顯示一個日曆介面和時間轉盤，讓使用者可以輕鬆選擇日期和時間。日期時間與 datetime-local 的原生 input 元素類似，但是，Ionic Framework 的日期時間元件可以輕鬆地以偏好的格式顯示日期和時間，並管理日期時間值。
概述
從歷史上看，在 JavaScript 中，甚至在 HTML 輸入中處理日期時間值一直是一項挑戰。具體來說，JavaScript 的 Date 物件在正確解析日期時間字串或格式化日期時間值方面非常困難。更糟糕的是，不同的瀏覽器和 JavaScript 版本以不同的方式解析各種日期時間字串，尤其是在每個地區設定中。
幸運的是，Ionic Framework 的日期時間輸入設計旨在讓開發人員避免常見的陷阱，讓開發人員可以輕鬆地操作日期時間值，並為使用者提供一個簡單的日期時間選擇器，以獲得絕佳的使用者體驗。
ISO 8601 日期時間格式：YYYY-MM-DDTHH:mmZ
Ionic Framework 使用 ISO 8601 日期時間格式 作為其值。該值只是一個字串，而不是使用 JavaScript 的 Date 物件。使用 ISO 日期時間格式可以輕鬆地在 JSON 物件和資料庫中序列化和解析。
以下是一些可以用於 ion-datetime 的 ISO 8601 格式範例
| 描述 | 格式 | 日期時間值範例 |
|---|---|---|
| 年份 | 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 |
請注意，年份始終為四位數，毫秒（如果添加）始終為三位數，所有其他值始終為兩位數。因此，代表 1 月的數字始終帶有前導零，例如 01。此外，小時始終採用 24 小時制格式，因此 00 在 12 小時制時鐘上為 凌晨 12 點，13 表示 下午 1 點，而 23 表示 晚上 11 點。
雖然可以使用 ISO 8601 日期時間格式指定秒、毫秒和時區，但 ion-datetime 不提供秒、毫秒和時區選擇的介面。任何提供的秒、毫秒或時區值都將被忽略。
基本用法
與日期時間按鈕一起使用
如果需要在覆蓋層（例如模態或快顯視窗）中顯示日期時間，我們建議使用 ion-datetime-button。當空間有限時，應使用 ion-datetime-button。此元件顯示按鈕，這些按鈕會顯示目前的日期和時間值。當點擊按鈕時，日期或時間選擇器會在覆蓋層中開啟。
非同步設定值
如果日期時間已經建立後，其 value 是以程式方式更新的，則日期時間會自動跳到新日期。但是，建議避免在使用者能夠與日期時間互動時以這種方式更新 value，因為這可能會讓目前嘗試選擇日期的使用者感到困惑。例如，如果日期時間的 value 是由非同步程序載入的，則建議使用 CSS 隱藏日期時間，直到值完成更新。
日期限制
最大和最小日期
若要自訂最小和最大日期時間值，可以提供 min 和 max 元件屬性，這可能更符合應用程式的使用案例。按照上面表格中列出的相同 IS0 8601 格式，每個元件都可以限制使用者可以選擇的日期。
以下範例將日期選擇限制為僅 2022 年 3 月到 2022 年 5 月。
選擇特定值
雖然 min 和 max 屬性可讓您將日期選擇限制在特定範圍內，但 monthValues、dayValues、yearValues、hourValues 和 minuteValues 屬性可讓您選擇使用者可以選擇的特定日期和時間。
以下範例允許以 15 分鐘的增量選擇分鐘。它還允許以 5 天的增量選擇日期。
進階日期限制
使用 isDateEnabled 屬性，開發人員可以使用 ISO 8601 日期字串自訂 ion-datetime，以停用特定日期、日期範圍、週末或任何自訂規則。isDateEnabled 屬性接受一個傳回布林值的函式，表示是否啟用日期。函式會針對上個月、當月和下個月的每個彩現日曆日呼叫。自訂實作應針對效能進行最佳化，以避免不流暢。
以下範例顯示如何停用所有週末日期。對於更進階的日期操作，我們建議使用日期公用程式（例如 date-fns）。
本地化
Ionic Framework 使用 Intl.DatetimeFormat Web API，這讓我們可以根據使用者裝置上設定的語言和地區，自動本地化月份和日期名稱。
自訂地區設定
在需要特定地區設定的情況下，您可以使用 locale 屬性來設定。地區設定會控制顯示的語言以及日期和時間格式。
以下範例示範如何將地區設定為西班牙文（西班牙）。
時間標籤不會自動本地化。請參閱 時間標籤 以取得更多資訊。
時鐘週期
ion-datetime 預設會使用 locale 屬性指定的時鐘週期。例如，如果 locale 設定為 en-US，則 ion-datetime 將使用 12 小時制。
主要有 4 種時鐘週期類型
| 時鐘週期類型 | 描述 |
|---|---|
'h12' | 使用 1–12 的小時系統；對應於模式中的 'h'。12 小時制時鐘，午夜從 12:00 am 開始。 |
'h23' | 使用 0–23 的小時系統；對應於模式中的 'H'。24 小時制時鐘，午夜從 0:00 開始。 |
'h11' | 使用 0–11 的小時系統；對應於模式中的 'K'。12 小時制時鐘，午夜從 0:00 am 開始。 |
'h24' | 使用 1–24 的小時系統；對應於模式中的 'k'。24 小時制時鐘，午夜從 24:00 開始。 |
在某些情況下，您可能需要更精確地控制使用的時鐘週期。這時 hourCycle 屬性就能派上用場。
在以下範例中，即使地區設定為 en-GB（預設使用 24 小時制），我們也可以使用 hourCycle 屬性強制 ion-datetime 使用 12 小時制。
一週的第一天
對於 ion-datetime 來說，預設的一週第一天是星期日。截至 2022 年，沒有瀏覽器 API 可以讓 Ionic 根據裝置的地區設定自動判斷一週的第一天，不過這方面的工作正在進行中（請參閱：TC39 GitHub）。
時間標籤
時間標籤不會自動本地化。幸好，Ionic 透過 time-label 插槽可以輕鬆提供自訂的本地化。
地區設定延伸標籤
ion-datetime 也支援 地區設定延伸標籤 作為 Intl.Locale API 的一部分。這些標籤可讓您在地區設定字串本身中編碼有關地區設定的資訊。如果開發人員在其應用程式中使用 Intl.Locale API，他們可能會偏好使用延伸標籤方法。
例如，如果您想在 en-GB 地區設定中使用 12 小時制，您可以提供延伸標籤，而不是同時使用 locale 和 hourCycle 屬性。
在應用程式中使用 Intl.Locale 之前，請務必查看 瀏覽器相容性圖表。
呈現方式
預設情況下，ion-datetime 允許使用者同時選取日期和時間。此外，使用者可以選取特定的月份、年份、小時和分鐘。
某些使用情況可能只需要選取日期或只需要選取時間。presentation 屬性可讓您指定要顯示哪些選擇器以及顯示順序。例如，設定 date-time 會讓日曆選擇器顯示在時間選擇器之前。設定 time-date 會讓日曆選擇器顯示在時間選擇器之後。
月份和年份選取
透過將 month-year、year-month、month 或 year 傳遞給 presentation 屬性即可使用月份和年份選取。
此範例顯示具有 month-year 設定的日期時間。
時間選取
透過將 date-time、time-date 或 time 傳遞給 presentation 屬性即可使用時間選取。
此範例顯示具有 time 設定的日期時間。
日期選取
透過將 date-time、time-date 或 date 傳遞給 presentation 屬性即可使用日期選取。
此範例顯示具有 date 設定的日期時間。
滾輪樣式選擇器
預設情況下，Ionic 在使用 presentation 時會偏好顯示格線樣式版面配置。不過，可以使用 preferWheel 屬性來顯示滾輪樣式。當 preferWheel 為 true 時，Ionic 會盡可能偏好顯示滾輪樣式版面配置。
某些 presentation 選項同時具有格線和滾輪樣式，開發人員可以使用 preferWheel 屬性來選擇。其他 presentation 值只有滾輪樣式，永遠不會顯示格線樣式。下表顯示哪些 presentation 值具有格線或滾輪樣式。
呈現方式 | 是否有格線樣式？ | 是否有滾輪樣式？ |
|---|---|---|
date | 是 | 是 |
date-time | 是 | 是 |
month | 否 | 是 |
month-year | 否 | 是 |
time | 否 | 是 |
time-date | 是 | 是 |
year | 否 | 是 |
以下範例顯示 presentation="date-time" 的滾輪選擇器。
多重日期選取
如果將 multiple 屬性設定為 true，則可以從日曆選擇器中選取多個日期。按一下選取的日期將會取消選取。
只有在使用 presentation="date" 和 preferWheel="false" 時，才支援此屬性。
標題
預設情況下，ion-datetime 不會顯示任何與元件相關聯的標頭或標題。開發人員可以使用 showDefaultTitle 屬性來顯示預設的標題/標頭設定。他們也可以使用 title 插槽來自訂標頭中呈現的內容。
顯示預設標題
自訂標題
格式選項
您可以透過提供 formatOptions 來客製化日期時間元件標頭文字中的日期格式和時間按鈕中的時間格式。formatOptions 屬性中的 date 和 time 應該都是 Intl.DateTimeFormatOptions 物件。如果未提供 formatOptions，則會使用預設的日期和時間格式。
日期時間不會操作或設定時區。如果提供 timeZone 或 timeZoneName，它們將會被忽略，時區將會設定為 UTC。這可確保顯示的值與選取的值相符，而不是轉換為使用者目前的時區。
請小心您提供的選項，因為它們可能與選取的呈現方式不符。例如，為 month 的呈現方式提供 minute: 'numeric' 可能會導致非預期的行為，顯示一個可能只預期顯示時間的月份。
按鈕
預設情況下，每次選取新日期時都會發出新的日期時間值的 ionChange。若要在發出 ionChange 之前要求使用者確認，您可以將 showDefaultButtons 屬性設定為 true，或使用 buttons 插槽傳遞自訂的確認按鈕。當傳遞自訂按鈕時，確認按鈕必須在 ion-datetime 上呼叫 confirm 方法才能發出 ionChange。
顯示確認按鈕
預設的「完成」和「取消」按鈕已預先設定為分別呼叫 confirm 和 cancel 方法。
自訂按鈕文字
對於簡單的使用情況，開發人員可以透過 doneText 和 cancelText 屬性，為確認和取消值提供自訂的按鈕文字。當您只需要變更按鈕文字，而不需要任何自訂行為時，我們建議您這樣做。
自訂按鈕元素
開發人員可以提供自己的按鈕以取得進階的自訂行為。
ion-datetime 具有 confirm、cancel 和 reset 方法，開發人員可以在按一下自訂按鈕時呼叫這些方法。reset 方法也允許開發人員提供日期，以將日期時間重設為該日期。
醒目提示特定日期
開發人員可以使用 highlightedDates 屬性，以自訂文字或背景色彩為特定日期設定樣式。此屬性可以定義為日期及其色彩的陣列，或是一個接收 ISO 字串並傳回要使用之色彩的回呼函式。
指定色彩時，可以使用任何有效的 CSS 色彩格式。這包括十六進位碼、rgba、色彩變數 等。
為了保持一致的使用者體驗，選取日期的樣式將永遠覆蓋自訂醒目提示。
此屬性僅在 preferWheel="false" 時支援，且 presentation 必須設定為 "date"、"date-time" 或 "time-date"。
使用陣列
當高亮顯示適用於固定日期（例如截止日期）時，使用陣列會是較佳的選擇。
使用回呼函式
當高亮顯示的日期是重複發生的（例如生日或週期性會議）時，使用回呼函式會是較佳的選擇。
樣式設定
全域主題設定
Ionic 強大的主題系統可以輕鬆地變更整個應用程式以符合特定的主題。在此範例中，我們使用顏色建立器和階梯式顏色產生器來建立一個玫瑰色調色盤，我們可以將其用於 ion-datetime。
此方法的優點是，每個元件（而不僅僅是 ion-datetime）都可以自動利用此主題。
日曆天數
可以使用 CSS Shadow Parts 來設定網格樣式 ion-datetime 中的日曆天數樣式。
下面的範例選擇前 2 天的日期，除非該天在前一個月，則選擇未來 2 天的日期。這樣做是為了示範如何將自訂樣式套用於所有天數、當前日期和選定的日期。
滾輪選擇器
ion-datetime 中使用的滾輪可以透過結合 Shadow Parts 和 CSS 變數來設定樣式。這適用於滾輪樣式日期時間中的欄位，以及網格樣式日期時間中的月份/年份選擇器。
時區
Ionic 的 ion-datetime 遵循 datetime-local 的行為，不操縱或設定日期時間控制項內的時區。換句話說，時間值「07:00」不會根據不同的時區進行調整。
我們建議使用像 date-fns-tz 這樣的函式庫，將日期時間值轉換為所需的時區。
以下是如何格式化 ISO-8601 字串以在使用者裝置上設定的時區中顯示的範例
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 });
剖析日期值
ionChange 事件會在事件 payload 中以 ISO-8601 字串的形式發出日期值。開發人員有責任根據其應用程式的需求格式化它。我們建議使用 date-fns 來格式化日期值。
以下是如何格式化 ISO-8601 字串以顯示月份、日期和年份的範例
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 以取得所有有效格式符號的清單。
進階日期時間驗證和操作
日期時間選擇器提供選擇確切格式的便利性，並使用標準化的 ISO 8601 日期時間格式將日期時間值儲存為字串。但是，請務必注意，ion-datetime 並未嘗試解決驗證和操作日期時間值時的所有情況。如果需要從特定格式剖析日期時間值，或進行操作（例如在日期上加上 5 天、減去 30 分鐘等），甚至將資料格式化為特定地區設定，那麼我們強烈建議使用 date-fns 來處理 JavaScript 中的日期。
輔助功能
鍵盤互動
ion-datetime 對於在元件內可聚焦元素之間進行導覽，提供完整的鍵盤支援。下表詳細說明每個按鍵的作用
| 按鍵 | 描述 |
|---|---|
| Tab | 將焦點移至下一個可聚焦的元素。 |
| Shift + Tab | 將焦點移至上一個可聚焦的元素。 |
| Space 或 Enter | 點擊可聚焦的元素。 |
日期網格
| 按鍵 | 描述 |
|---|---|
| ArrowUp | 將焦點移至前一週的同一天。 |
| ArrowDown | 將焦點移至下一週的同一天。 |
| ArrowRight | 將焦點移至下一天。 |
| ArrowLeft | 將焦點移至前一天。 |
| Home | 將焦點移至當週的第一天。 |
| End | 將焦點移至當週的最後一天。 |
| PageUp | 將日期網格變更為前一個月。 |
| PageDown | 將日期網格變更為下一個月。 |
| Shift + PageUp | 將日期網格變更為前一年。 |
| Shift + PageDown | 將日期網格變更為下一年。 |
時間、月份和年份滾輪
日期時間中的滾輪選擇器在內部使用 Picker。請參閱 Picker 輔助功能以取得有關滾輪選擇器的輔助功能的更多資訊。
介面
DatetimeChangeEventDetail
interface DatetimeChangeEventDetail {
value?: string | null;
}
DatetimeCustomEvent
雖然不是必需的，但此介面可用於取代 CustomEvent 介面，以針對此元件發出的 Ionic 事件進行更強的類型檢查。
interface DatetimeCustomEvent extends CustomEvent {
detail: DatetimeChangeEventDetail;
target: HTMLIonDatetimeElement;
}
屬性
cancelText
| 描述 | 要在選擇器的取消按鈕上顯示的文字。 |
| 屬性 | cancel-text |
| 類型 | string |
| 預設值 | '取消' |
clearText
| 描述 | 要在選擇器的「清除」按鈕上顯示的文字。 |
| 屬性 | clear-text |
| 類型 | string |
| 預設值 | '清除' |
color
| 描述 | 要使用應用程式調色盤中的顏色。預設選項為："primary"、"secondary"、"tertiary"、"success"、"warning"、"danger"、"light"、"medium" 和 "dark"。有關顏色的更多資訊，請參閱主題設定。 |
| 屬性 | color |
| 類型 | "danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined |
| 預設值 | 'primary' |
dayValues
| 描述 | 用於建立可選取日期清單的值。預設情況下，會顯示給定月份的每一天。但是，若要精確控制要顯示的月份中的哪些日期，dayValues 輸入可以採用數字、數字陣列或以逗號分隔的數字字串。請注意，即使陣列中的日期對於所選月份而言具有無效的數字，例如二月的 31，它也會正確地不顯示所選月份中無效的日期。 |
| 屬性 | day-values |
| 類型 | number ｜ number[] ｜ string ｜ undefined |
| 預設值 | undefined |
disabled
| 描述 | 如果為 true，則使用者無法與日期時間互動。 |
| 屬性 | disabled |
| 類型 | boolean |
| 預設值 | false |
doneText
| 描述 | 要在選擇器的「完成」按鈕上顯示的文字。 |
| 屬性 | done-text |
| 類型 | string |
| 預設值 | '完成' |
firstDayOfWeek
| 描述 | 要用於 ion-datetime 的一週的第一天。預設值為 0，表示星期日。 |
| 屬性 | first-day-of-week |
| 類型 | number |
| 預設值 | 0 |
formatOptions
| 描述 | 日期和時間的格式化選項。應包含一個 'date' 和/或 'time' 物件，每個物件的類型都是 Intl.DateTimeFormatOptions。 |
| 屬性 | undefined |
| 類型 | undefined ｜ { date: DateTimeFormatOptions; time?: DateTimeFormatOptions ｜ undefined; } ｜ { date?: DateTimeFormatOptions ｜ undefined; time: DateTimeFormatOptions; } |
| 預設值 | undefined |
highlightedDates
| 描述 | 用於將自訂文字和背景顏色套用於特定日期。 可以是包含 ISO 字串和顏色的物件陣列，也可以是接收 ISO 字串並傳回顏色的回呼函式。 僅適用於 date、date-time 和 time-date 呈現方式，且 preferWheel="false"。 |
| 屬性 | undefined |
| 類型 | ((dateIsoString: string) => DatetimeHighlightStyle ｜ undefined) ｜ DatetimeHighlight[] ｜ undefined |
| 預設值 | undefined |
hourCycle
| 描述 | ion-datetime 的小時週期。如果未設定值，則由目前的地區設定指定。 |
| 屬性 | hour-cycle |
| 類型 | "h11" ｜ "h12" ｜ "h23" ｜ "h24" ｜ undefined |
| 預設值 | undefined |
hourValues
| 描述 | 用於建立可選取小時清單的值。預設情況下，小時值在 24 小時制下為從 0 到 23，或在 12 小時制下為從 1 到 12。但是，若要精確控制要顯示的小時，hourValues 輸入可以採用數字、數字陣列或以逗號分隔的數字字串。 |
| 屬性 | hour-values |
| 類型 | number ｜ number[] ｜ string ｜ undefined |
| 預設值 | undefined |
isDateEnabled
| 描述 | 傳回是否啟用或停用個別日期（日曆天）。 如果為 true，則將啟用/互動該天。如果為 false，則將停用/非互動該天。該函式接受給定日期的 ISO 8601 日期字串。預設情況下，所有日期都已啟用。開發人員可以使用此函式來撰寫自訂邏輯以停用某些日期。 會針對上個月、當月和下個月的每個呈現的日曆天呼叫該函式。自訂實作應針對效能進行最佳化，以避免產生卡頓。 |
| 屬性 | undefined |
| 類型 | ((dateIsoString: string) => boolean) ｜ undefined |
| 預設值 | undefined |
locale
| 描述 | 用於 ion-datetime 的地區設定。這會影響月份和日期的名稱格式。"default" 值指的是您裝置設定的預設地區設定。 |
| 屬性 | locale |
| 類型 | string |
| 預設值 | 'default' |
max
| 描述 | 允許的最大日期時間。值必須是遵循 ISO 8601 日期時間格式標準的日期字串，例如 1996-12-19。格式不一定要精確到一個確切的日期時間。例如，最大值可以只是年份，例如 1994。預設為今年年底。 |
| 屬性 | max |
| 類型 | string ｜ undefined |
| 預設值 | undefined |
min
| 描述 | 允許的最小日期時間。值必須是遵循 ISO 8601 日期時間格式標準的日期字串，例如 1996-12-19。格式不一定要精確到一個確切的日期時間。例如，最小值可以只是年份，例如 1994。預設為今年開始的 100 年前。 |
| 屬性 | min |
| 類型 | string ｜ undefined |
| 預設值 | undefined |
minuteValues
| 描述 | 用於建立可選分鐘列表的值。預設情況下，分鐘範圍從 0 到 59。但是，為了精確控制要顯示哪些分鐘，minuteValues 輸入可以接受數字、數字陣列或以逗號分隔的數字字串。例如，如果分鐘選擇應該僅為每 15 分鐘一次，則此輸入值應為 minuteValues="0,15,30,45"。 |
| 屬性 | minute-values |
| 類型 | number ｜ number[] ｜ string ｜ undefined |
| 預設值 | undefined |
mode
| 描述 | 模式決定要使用哪個平台樣式。 |
| 屬性 | mode |
| 類型 | "ios" ｜ "md" |
| 預設值 | undefined |
monthValues
| 描述 | 用於建立可選月份列表的值。預設情況下，月份值範圍從 1 到 12。但是，為了精確控制要顯示哪些月份，monthValues 輸入可以接受數字、數字陣列或以逗號分隔的數字字串。例如，如果只應顯示夏季月份，則此輸入值應為 monthValues="6,7,8"。請注意，月份數字的索引不是從零開始的，這表示一月的數值為 1，而十二月的數值為 12。 |
| 屬性 | month-values |
| 類型 | number ｜ number[] ｜ string ｜ undefined |
| 預設值 | undefined |
multiple
| 描述 | 如果為 true，則可以一次選擇多個日期。僅適用於 presentation="date" 和 preferWheel="false"。 |
| 屬性 | multiple |
| 類型 | boolean |
| 預設值 | false |
name
| 描述 | 控制項的名稱，會與表單資料一起提交。 |
| 屬性 | name |
| 類型 | string |
| 預設值 | this.inputId |
preferWheel
| 描述 | 如果為 true，則在可能的情況下會呈現滾輪選取器，而不是日曆網格。如果為 false，則在可能的情況下會呈現日曆網格，而不是滾輪選取器。當 presentation 是下列值之一時，可以呈現滾輪選取器而不是網格："date"、"date-time" 或 "time-date"。當 presentation 是下列值之一時，無論 preferWheel 值為何，都會始終呈現滾輪選取器："time"、"month"、"month-year" 或 "year"。 |
| 屬性 | prefer-wheel |
| 類型 | boolean |
| 預設值 | false |
presentation
| 描述 | 您要選取的值。"date" 會顯示日曆選取器以選取月份、日期和年份。"time" 會顯示時間選取器以選取小時、分鐘和（可選）上午/下午。"date-time" 會先顯示日期選取器，然後再顯示時間選取器。"time-date" 會先顯示時間選取器，然後再顯示日期選取器。 |
| 屬性 | 呈現方式 |
| 類型 | "date" ｜ "date-time" ｜ "month" ｜ "month-year" ｜ "time" ｜ "time-date" ｜ "year" |
| 預設值 | 'date-time' |
readonly
| 描述 | 如果為 true，則日期時間會正常顯示，但無法變更選取的日期。 |
| 屬性 | readonly |
| 類型 | boolean |
| 預設值 | false |
showClearButton
| 描述 | 如果為 true，則會在 ion-datetime 元件底部與預設的「取消」和「確定」按鈕一起呈現「清除」按鈕。如果開發人員想要自訂這些按鈕，也可以使用 button 插槽。如果在 button 插槽中設定了自訂按鈕，則不會呈現預設按鈕。 |
| 屬性 | show-clear-button |
| 類型 | boolean |
| 預設值 | false |
showDefaultButtons
| 描述 | 如果為 true，則會在 ion-datetime 元件底部呈現預設的「取消」和「確定」按鈕。如果開發人員想要自訂這些按鈕，也可以使用 button 插槽。如果在 button 插槽中設定了自訂按鈕，則不會呈現預設按鈕。 |
| 屬性 | show-default-buttons |
| 類型 | boolean |
| 預設值 | false |
showDefaultTimeLabel
| 描述 | 如果為 true，則會為 ion-datetime 元件的時間選取器呈現預設的「時間」標籤。如果開發人員想要自訂此標籤，也可以使用 time-label 插槽。如果在 time-label 插槽中設定了自訂標籤，則不會呈現預設標籤。 |
| 屬性 | show-default-time-label |
| 類型 | boolean |
| 預設值 | true |
showDefaultTitle
| 描述 | 如果為 true，則會在日曆選取器上方顯示標頭。這將包含插槽標題和選取的日期。 |
| 屬性 | show-default-title |
| 類型 | boolean |
| 預設值 | false |
size
| 描述 | 如果為 cover，則 ion-datetime 會展開以覆蓋其容器的整個寬度。如果為 fixed，則 ion-datetime 會具有固定寬度。 |
| 屬性 | size |
| 類型 | "cover" ｜ "fixed" |
| 預設值 | 'fixed' |
titleSelectedDatesFormatter
| 描述 | 用於格式化標頭文字的回呼，該標頭文字顯示選取了多少個日期。僅在選取了 0 個或多於 1 個時使用（即對於正好 1 個未使用的情況）。預設情況下，標頭文字設定為「numberOfDates 天」。 如果您需要從回呼內存取 this，請參閱 https://ionic.dev.org.tw/docs/troubleshooting/runtime#accessing-this。 |
| 屬性 | undefined |
| 類型 | ((selectedDates: string[]) => string) ｜ undefined |
| 預設值 | undefined |
value
| 描述 | 日期時間的值，為有效的 ISO 8601 日期時間字串。只有在 multiple="true" 時，才應該是字串陣列。 |
| 屬性 | value |
| 類型 | null ｜ string ｜ string[] ｜ undefined |
| 預設值 | undefined |
yearValues
| 描述 | 用於建立可選年份列表的值。預設情況下，年份值範圍在 min 和 max 日期時間輸入之間。但是，為了精確控制要顯示哪些年份，yearValues 輸入可以接受數字、數字陣列或以逗號分隔的數字字串。例如，若要顯示即將到來和最近的閏年，則此輸入的值應為 yearValues="2008,2012,2016,2020,2024"。 |
| 屬性 | year-values |
| 類型 | number ｜ number[] ｜ string ｜ undefined |
| 預設值 | undefined |
事件
| 名稱 | 描述 | 冒泡 |
|---|---|---|
ionBlur | 當日期時間失去焦點時發出。 | true |
ionCancel | 當日期時間選取被取消時發出。 | true |
ionChange | 當值（選取的日期）已變更時發出。 以程式方式設定 value 屬性時，不會發出此事件。 | true |
ionFocus | 當日期時間具有焦點時發出。 | true |
方法
cancel
| 描述 | 發出 ionCancel 事件，並可選擇性地關閉呈現日期時間的快顯視窗或模式視窗。 |
| 簽章 | cancel(closeOverlay?: boolean) => Promise<void> |
confirm
| 描述 | 確認選取的日期時間值，更新 value 屬性，並可選擇性地關閉呈現日期時間的快顯視窗或模式視窗。 |
| 簽章 | confirm(closeOverlay?: boolean) => Promise<void> |
reset
| 描述 | 重設日期時間的內部狀態，但不更新值。傳遞有效的 ISO-8601 字串會將元件的狀態重設為提供的日期。如果未提供任何值，則內部狀態會重設為最小、最大和今天的鉗制值。 |
| 簽章 | reset(startDate?: string) => Promise<void> |
CSS 陰影部分
| 名稱 | 描述 |
|---|---|
calendar-day | 在日期時間日曆內顯示一天的個別按鈕。 |
calendar-day active | 目前選取的日曆日期。 |
calendar-day disabled | 已停用的日曆日期。 |
calendar-day today | 包含當天的日曆日期。 |
month-year-button | 使用網格樣式版面配置時，開啟月份/年份選取器的按鈕。 |
time-button | 使用網格樣式版面配置且 presentation="date-time" 或 "time-date" 時，開啟時間選取器的按鈕。 |
time-button active | 選取器開啟時的時間選取器按鈕。 |
wheel-item | 使用滾輪樣式版面配置時，或使用網格樣式版面配置時在月份/年份選取器中的個別項目。 |
wheel-item active | 目前選取的 wheel-item。 |
CSS 自訂屬性
- iOS
- MD
| 名稱 | 描述 |
|---|---|
--background | 日期時間元件的主要背景。 |
--background-rgb | RGB 格式的日期時間元件的主要背景。 |
--title-color | 標題的文字顏色。 |
--wheel-fade-background-rgb | 使用滾輪樣式版面配置時，或用於網格樣式版面配置的月份/年份選取器時，覆蓋未選取項目的漸層顏色。必須使用 RGB 格式，例如 255, 255, 255。 |
--wheel-highlight-background | 使用滾輪樣式版面配置時，或用於網格樣式版面配置的月份/年份選取器時，選取項目下方醒目提示的背景。 |
--wheel-highlight-border-radius | 使用滾輪樣式版面配置時，或用於網格樣式版面配置的月份/年份選取器時，選取項目下方醒目提示的邊框半徑。 |
| 名稱 | 描述 |
|---|---|
--background | 日期時間元件的主要背景。 |
--background-rgb | RGB 格式的日期時間元件的主要背景。 |
--title-color | 標題的文字顏色。 |
--wheel-fade-background-rgb | 使用滾輪樣式版面配置時，或用於網格樣式版面配置的月份/年份選取器時，覆蓋未選取項目的漸層顏色。必須使用 RGB 格式，例如 255, 255, 255。 |
--wheel-highlight-background | 使用滾輪樣式版面配置時，或用於網格樣式版面配置的月份/年份選取器時，選取項目下方醒目提示的背景。 |
--wheel-highlight-border-radius | 使用滾輪樣式版面配置時，或用於網格樣式版面配置的月份/年份選取器時，選取項目下方醒目提示的邊框半徑。 |
插槽
| 名稱 | 描述 |
|---|---|
buttons | 日期時間中的按鈕。 |
time-label | 日期時間中時間選取器的標籤。 |
title | 日期時間的標題。 |