From 4ff6f6c61914724e78f2216339a16987e719ede5 Mon Sep 17 00:00:00 2001 From: "ester.zhou" Date: Sat, 26 Mar 2022 08:40:40 +0800 Subject: [PATCH] add and update docs Signed-off-by: ester.zhou --- .../reference/arkui-ts/Readme-EN.md | 2 + .../ts-basic-components-datepicker.md | 93 ++++---------- .../ts-basic-components-timepicker.md | 77 ++++++++++++ .../arkui-ts/ts-methods-datepicker-dialog.md | 116 ++---------------- .../arkui-ts/ts-methods-timepicker-dialog.md | 86 +++++++++++++ 5 files changed, 199 insertions(+), 175 deletions(-) create mode 100644 en/application-dev/reference/arkui-ts/ts-basic-components-timepicker.md create mode 100644 en/application-dev/reference/arkui-ts/ts-methods-timepicker-dialog.md diff --git a/en/application-dev/reference/arkui-ts/Readme-EN.md b/en/application-dev/reference/arkui-ts/Readme-EN.md index 2c6cea4956..5877e10c6c 100644 --- a/en/application-dev/reference/arkui-ts/Readme-EN.md +++ b/en/application-dev/reference/arkui-ts/Readme-EN.md @@ -73,6 +73,7 @@ - [TextInput](ts-basic-components-textinput.md) - [TextPicker](ts-basic-components-textpicker.md) - [TextTimer](ts-basic-components-texttimer.md) + - [TimePicker](ts-basic-components-timepicker.md) - [Toggle](ts-basic-components-toggle.md) - [TextClock](ts-basic-components-textclock.md) - [Web](ts-basic-components-web.md) @@ -143,6 +144,7 @@ - [Action Sheet](ts-methods-action-sheet.md) - [Custom Dialog Box](ts-methods-custom-dialog-box.md) - [Date Picker Dialog Box](ts-methods-datepicker-dialog.md) + - [Time Picker Dialog Box](ts-methods-timepicker-dialog.md) - [Text Picker Dialog Box](ts-methods-textpicker-dialog.md) - [Menu](ts-methods-menu.md) - Appendix diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-datepicker.md b/en/application-dev/reference/arkui-ts/ts-basic-components-datepicker.md index 07518d184b..f14fcd3c6d 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-datepicker.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-datepicker.md @@ -1,73 +1,61 @@ # DatePicker - > ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** > This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. -The **<DatePicker>** component allows users to select date and time. +The **\** component allows users to select a date from the given range. ## Required Permissions -None +No ## Child Components -None +No ## APIs -DatePicker(value:{start?: Date, end?: Date, selected?: Date, type?: DatePickerType}) +DatePicker(options?: DatePickerOptions) -Creates a date picker that allows users to select a date or time within the specified range. +Creates a date picker in the given date range. -- Parameters - | Name | Type | Mandatory | Default Value | Description | +- options parameters + | Name| Type| Mandatory| Default Value| Description| | -------- | -------- | -------- | -------- | -------- | - | start | Date | No | Date('1970-1-1') | Start date of the date picker. | - | end | Date | No | Date('2100-12-31') | End date of the date picker. | - | selected | Date | No | Current system date or time | Selected date when **type** is set to **DatePickerType.Date** and selected time when **type** is set to **DatePickerType.Time**. | - | type | DatePickerType | No | DatePickerType.Date | Picker type, which can be date picker and time picker. The date picker is used by default. | - -- DatePickerType enums - | Name | Description | - | -------- | -------- | - | Date | Date picker. | - | Time | Time picker. | + | start | Date | No| Date('1970-1-1') | Start date of the picker.| + | end | Date | No| Date('2100-12-31') | End date of the picker.| + | selected | Date | No| Current system date| Date of the selected item.| ## Attributes -| Name | Type | Default Value | Description | -| -------- | -------- | -------- |-------- | -| lunar | boolean | false | Whether to display the lunar calendar.
- **true**: The lunar calendar is displayed.
- **false**: The lunar calendar is not displayed. | -| useMilitaryTime | boolean | false | Whether the display time is in 24-hour format. The value cannot be dynamically modified. | +| Name| Type| Default Value| Description| +| -------- | -------- | -------- | -------- | +| lunar | boolean | false | Whether to display the lunar calendar.
- **true**: Display the lunar calendar.
- **false**: Do not display the lunar calendar.| ## Events -| Name | Description | +| Name| Description| | -------- | -------- | -| onChange(callback: (value: DatePickerResult) => void) | This event is triggered when a date or time is selected. | +| onChange(callback: (value: DatePickerResult) => void) | Triggered when a date is selected.| -- DatePickerResult - | Name | Type | Description | - | -------- | -------- | -------- | - | year | number | Year of the selected date (when **type** is **DatePickerType.Date**). | - | month | number | Month of the selected date (when **type** is **DatePickerType.Date**). | - | day | number | Date of the selected date (when **type** is **DatePickerType.Date**). | - | hour | number | Hour portion of the selected time (when **type** is **DatePickerType.Time**). | - | minute | number | Minute portion of the selected time (when **type** is **DatePickerType.Time**). | +### DatePickerResult +| Name| Type| Description| +| -------- | -------- | -------- | +| year | number | Year of the selected date.| +| month | number | Month of the selected date.| +| day | number | Day of the selected date.| ## Example -### Date Picker (with Lunar Calendar) - +### Date Picker Sample Code (With Lunar Calendar) ``` @Entry @@ -79,9 +67,8 @@ struct DatePickerExample01 { Column() { DatePicker({ start: new Date('1970-1-1'), - end: new Date('2200-1-1'), + end: new Date('2100-1-1'), selected: this.selectedDate, - type: DatePickerType.Date }) .lunar(true) .onChange((date: DatePickerResult) => { @@ -93,8 +80,7 @@ struct DatePickerExample01 { ``` -### Date Picker (Without Lunar Calendar) - +### Date Picker Sample Code (No Lunar Calendar) ``` @Entry @@ -106,9 +92,8 @@ struct DatePickerExample02 { Column() { DatePicker({ start: new Date('1970-1-1'), - end: new Date('2200-1-1'), + end: new Date('2100-1-1'), selected: this.selectedDate, - type: DatePickerType.Date }) .lunar(false) .onChange((date: DatePickerResult) => { @@ -120,31 +105,3 @@ struct DatePickerExample02 { ``` - -### Time Picker - - -``` -@Entry -@Component -struct DatePickerExample03 { - private selectedTime: Date = new Date('2021-9-29 08:00:00') - - build() { - Column() { - DatePicker({ - start: new Date('00:00:00'), - end: new Date('23:59:59'), - selected: this.selectedTime, - type: DatePickerType.Time - }) - .useMilitaryTime(true) - .onChange((date: DatePickerResult) => { - console.info('select current date is: ' + JSON.stringify(date)) - }) - }.width('100%') - } -} -``` - -![en-us_image_0000001256858401](figures/en-us_image_0000001256858401.gif) diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-timepicker.md b/en/application-dev/reference/arkui-ts/ts-basic-components-timepicker.md new file mode 100644 index 0000000000..24b1ac6d59 --- /dev/null +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-timepicker.md @@ -0,0 +1,77 @@ +# TimePicker + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** +> This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. + + +The **\** component allows users to select a time from the given range. + + +## Required Permissions + +No + + +## Child Components + +No + + +## APIs + +TimePicker(options?: TimePickerOptions) + +Creates a time picker whose default time range is from 00:00 to 23:59. + +- options parameters + | Name| Type| Mandatory| Default Value| Description| + | -------- | -------- | -------- | -------- | -------- | + | selected | Date | No| Current system time| Time of the selected item.| + + +## Attributes + +| Name| Type| Default Value| Description| +| -------- | -------- | -------- | -------- | +| useMilitaryTime | boolean | false | Whether to display time in 24-hour format. The value cannot be modified dynamically.| + + +## Events + +| Name| Description| +| -------- | -------- | +| onChange(callback: (value: TimePickerResult ) => void) | Triggered when a time is selected.| + +### TimePickerResult +| Name| Type| Description| +| -------- | -------- | -------- | +| hour | number | Hour portion of the selected time.| +| minute | number | Minute portion of the selected time.| + + +## Example + + +### Time Picker + +``` +@Entry +@Component +struct TimePickerExample { + private selectedTime: Date = new Date('08-00') + + build() { + Column() { + TimePicker({ + selected: this.selectedTime, + }) + .useMilitaryTime(true) + .onChange((date: TimePickerResult) => { + console.info('select current date is: ' + JSON.stringify(date)) + }) + }.width('100%') + } +} +``` + +![en-us_image_0000001251292933](figures/en-us_image_0000001251292933.gif) diff --git a/en/application-dev/reference/arkui-ts/ts-methods-datepicker-dialog.md b/en/application-dev/reference/arkui-ts/ts-methods-datepicker-dialog.md index ba0a5716ae..33f5b2b99a 100644 --- a/en/application-dev/reference/arkui-ts/ts-methods-datepicker-dialog.md +++ b/en/application-dev/reference/arkui-ts/ts-methods-datepicker-dialog.md @@ -3,7 +3,7 @@ > ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** > This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. -You can display a date or time picker in a dialog box to allow users to select a date or time from the given range. +You can display a date picker in a dialog box to allow users to select a date from the given range. ## Required Permissions @@ -11,22 +11,20 @@ None ## DatePickerDialog.show -show(options?: DatePickerDialogOption) +show(options?: DatePickerDialogOptions) -Shows a date or time picker in the given settings. +Defines and displays a date picker dialog box. -- DatePickerDialogOption parameters +- options parameters | Name| Type| Mandatory| Default Value| Description| | -------- | -------- | -------- | -------- | -------- | | start | Date | No| Date('1970-1-1') | Start date of the picker.| | end | Date | No| Date('2100-12-31') | End date of the picker.| - | selected | Date | No| Current system date or time| Date or time of the selected item in the picker. When **type** is set to **DatePickerType.Date**, this parameter indicates the date of the selected item. When **type** is set to **DatePickerType.Time**, this parameter indicates the time of the selected item.| - | type | [DatePickerType](ts-basic-components-datepicker.md) | No| DatePickerType.Date | Picker type, which can be the date picker and time picker.| + | selected | Date | No| Current system date| Date of the selected item.| | lunar | boolean | No| false | Whether to display the lunar calendar.| - | useMilitaryTime | boolean | No| false | Whether to display time in 24-hour format.| - | onAccept | (value: [DatePickerResult](ts-basic-components-datepicker.md)) => void | No| - | Triggered when the OK button in the dialog box is clicked.| + | onAccept | (value: [DatePickerResult](ts-basic-components-datepicker.md#DatePickerResult)) => void | No| - | Triggered when the OK button in the dialog box is clicked.| | onCancel | () => void | No| - | Triggered when the Cancel button in the dialog box is clicked.| - | onChange | (value: [DatePickerResult](ts-basic-components-datepicker.md)) => void | No| - | Triggered when the selected item in the picker changes.| + | onChange | (value: [DatePickerResult](ts-basic-components-datepicker.md#DatePickerResult)) => void | No| - | Triggered when the selected item in the picker changes.| ## Example @@ -36,8 +34,6 @@ Shows a date or time picker in the given settings. @Component struct DatePickerDialogExample01 { @State isLunar: boolean = true - @State isUseMilitaryTime: boolean = false - @State datePickerType: DatePickerType = DatePickerType.Date selectedDate: Date = new Date("2000-1-1") build() { @@ -48,15 +44,10 @@ struct DatePickerDialogExample01 { start: new Date("2000-1-1"), end: new Date("2005-1-1"), selected: this.selectedDate, - type: this.datePickerType, lunar: this.isLunar, - useMilitaryTime: this.isUseMilitaryTime, onAccept: (value: DatePickerResult) => { + this.selectedDate.setFullYear(value.year, value.month, value.day) console.info("DatePickerDialog:onAccept()" + JSON.stringify(value)) - if (this.datePickerType == DatePickerType.Date) { - this.selectedDate.setFullYear(value.year, value.month, value.day) - } else if (this.datePickerType == DatePickerType.Time) { - this.selectedDate.setHours(value.hour, value.minute, value.second) } }, onCancel: () => { @@ -77,8 +68,6 @@ struct DatePickerDialogExample01 { @Component struct DatePickerDialogExample02 { @State isLunar: boolean = false - @State isUseMilitaryTime: boolean = false - @State datePickerType: DatePickerType = DatePickerType.Date selectedDate: Date = new Date("2000-1-1") build() { @@ -89,97 +78,10 @@ struct DatePickerDialogExample02 { start: new Date("2000-1-1"), end: new Date("2005-1-1"), selected: this.selectedDate, - type: this.datePickerType, lunar: this.isLunar, - useMilitaryTime: this.isUseMilitaryTime, onAccept: (value: DatePickerResult) => { + this.selectedDate.setFullYear(value.year, value.month, value.day) console.info("DatePickerDialog:onAccept()" + JSON.stringify(value)) - if (this.datePickerType == DatePickerType.Date) { - this.selectedDate.setFullYear(value.year, value.month, value.day) - } else if (this.datePickerType == DatePickerType.Time) { - this.selectedDate.setHours(value.hour, value.minute, value.second) - } - }, - onCancel: () => { - console.info("DatePickerDialog:onCancel()") - }, - onChange: (value: DatePickerResult) => { - console.info("DatePickerDialog:onChange()" + JSON.stringify(value)) - } - }) - }) - } - } -} -``` -### Time Picker Sample Code (24-Hour Clock) -``` -@Entry -@Component -struct DatePickerDialogExample03 { - @State isLunar: boolean = false - @State isUseMilitaryTime: boolean = true - @State datePickerType: DatePickerType = DatePickerType.Time - selectedDate: Date = new Date("2000-1-1") - - build() { - Flex({direction: FlexDirection.Column, alignItems: ItemAlign.Center, - justifyContent: FlexAlign.Center }) { - Button("DatePickerDialog").onClick(() => { - DatePickerDialog.show({ - start: new Date("2000-1-1"), - end: new Date("2005-1-1"), - selected: this.selectedDate, - type: this.datePickerType, - lunar: this.isLunar, - useMilitaryTime: this.isUseMilitaryTime, - onAccept: (value: DatePickerResult) => { - console.info("DatePickerDialog:onAccept()" + JSON.stringify(value)) - if (this.datePickerType == DatePickerType.Date) { - this.selectedDate.setFullYear(value.year, value.month, value.day) - } else if (this.datePickerType == DatePickerType.Time) { - this.selectedDate.setHours(value.hour, value.minute, value.second) - } - }, - onCancel: () => { - console.info("DatePickerDialog:onCancel()") - }, - onChange: (value: DatePickerResult) => { - console.info("DatePickerDialog:onChange()" + JSON.stringify(value)) - } - }) - }) - } - } -} -``` -### Time Picker Sample Code (12-Hour Clock) -``` -@Entry -@Component -struct DatePickerDialogExample04 { - @State isLunar: boolean = false - @State isUseMilitaryTime: boolean = false - @State datePickerType: DatePickerType = DatePickerType.Time - selectedDate: Date = new Date("2000-1-1") - - build() { - Flex({direction: FlexDirection.Column, alignItems: ItemAlign.Center, - justifyContent: FlexAlign.Center }) { - Button("DatePickerDialog").onClick(() => { - DatePickerDialog.show({ - start: new Date("2000-1-1"), - end: new Date("2005-1-1"), - selected: this.selectedDate, - type: this.datePickerType, - lunar: this.isLunar, - useMilitaryTime: this.isUseMilitaryTime, - onAccept: (value: DatePickerResult) => { - console.info("DatePickerDialog:onAccept()" + JSON.stringify(value)) - if (this.datePickerType == DatePickerType.Date) { - this.selectedDate.setFullYear(value.year, value.month, value.day) - } else if (this.datePickerType == DatePickerType.Time) { - this.selectedDate.setHours(value.hour, value.minute, value.second) } }, onCancel: () => { diff --git a/en/application-dev/reference/arkui-ts/ts-methods-timepicker-dialog.md b/en/application-dev/reference/arkui-ts/ts-methods-timepicker-dialog.md new file mode 100644 index 0000000000..5c0bc59793 --- /dev/null +++ b/en/application-dev/reference/arkui-ts/ts-methods-timepicker-dialog.md @@ -0,0 +1,86 @@ +# Time Picker Dialog Box + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** +> This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. + +You can display a time picker in a dialog box to allow users to select a time from the given range, which is from 00:00 to 23:59 by default. + +## Required Permissions + +None + +## TimePickerDialog.show + +show(options?: TimePickerDialogOptions) + +Defines and displays a time picker dialog box. + +- options parameters + | Name| Type| Mandatory| Default Value| Description| + | -------- | -------- | -------- | -------- | -------- | + | selected | Date | No| Current system time| Time of the selected item.| + | useMilitaryTime | boolean | No| false | Whether to display time in 24-hour format.| + | onAccept | (value: [TimePickerResult](ts-basic-components-timepicker.md#TimePickerResult)) => void | No| - | Triggered when the OK button in the dialog box is clicked.| + | onCancel | () => void | No| - | Triggered when the Cancel button in the dialog box is clicked.| + | onChange | (value: [TimePickerResult](ts-basic-components-timepicker.md#TimePickerResult)) => void | No| - | Triggered when the selected item in the picker changes.| + +## Example + +### Time Picker Sample Code (24-Hour Clock) +``` +@Entry +@Component +struct TimePickerDialogExample01 { + @State isUseMilitaryTime: boolean = true + + build() { + Flex({direction: FlexDirection.Column, alignItems: ItemAlign.Center, + justifyContent: FlexAlign.Center }) { + Button("TimePickerDialog").onClick(() => { + TimePickerDialog.show({ + useMilitaryTime: this.isUseMilitaryTime, + onAccept: (value: TimePickerResult) => { + this.selectedDate.setHours(value.hour, value.minute, value.second) + console.info("TimePickerDialog:onAccept()" + JSON.stringify(value)) + }, + onCancel: () => { + console.info("TimePickerDialog:onCancel()") + }, + onChange: (value: TimePickerResult) => { + console.info("TimePickerDialog:onChange()" + JSON.stringify(value)) + } + }) + }) + } + } +} +``` +### Time Picker Sample Code (12-Hour Clock) +``` +@Entry +@Component +struct TimePickerDialogExample02 { + @State isUseMilitaryTime: boolean = false + + build() { + Flex({direction: FlexDirection.Column, alignItems: ItemAlign.Center, + justifyContent: FlexAlign.Center }) { + Button("TimePickerDialog").onClick(() => { + TimePickerDialog.show({ + useMilitaryTime: this.isUseMilitaryTime, + onAccept: (value: TimePickerResult) => { + this.selectedDate.setHours(value.hour, value.minute, value.second) + console.info("TimePickerDialog:onAccept()" + JSON.stringify(value)) + }, + onCancel: () => { + console.info("TimePickerDialog:onCancel()") + }, + onChange: (value: TimePickerResult) => { + console.info("TimePickerDialog:onChange()" + JSON.stringify(value)) + } + }) + }) + } + } +} +``` -- GitLab