javascript/ionic-framework
1
0
Fork 0
mirror of https://github.com/ionic-team/ionic-framework.git synced 2026-03-13 10:22:08 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore(): docs and snapshot updates

Browse Source
This commit is contained in:
mhartington
2017-12-14 14:34:46 -05:00
parent 178ae80b3c
commit 66d67a590e
4 changed files with 119 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
packages/core/src/components/action-sheet-controller/readme.md
View File

@@ -4,7 +4,7 @@
options. It appears on top of the app's content, and must be manually
dismissed by the user before they can resume interaction with the app.
Dangerous (destructive) options are made obvious in `ios` mode. There are easy
ways to cancel out of the action sheet, such as tapping the backdrop or
ways to cancel the action sheet, such as tapping the backdrop or
hitting the escape key on desktop.
An action sheet is created from an array of `buttons`, with each button
@@ -19,7 +19,7 @@
have been added to the `buttons` array. Note: We recommend that `destructive`
buttons are always the first button in the array, making them the top button.
Additionally, if the action sheet is dismissed by tapping the backdrop, then
it will fire the handler from the button with the cancel role.
it will call the handler from the button with the cancel role.
You can pass all of the action sheet's options in the first argument of
the create method: `ActionSheet.create(opts)`.

1
packages/core/src/components/action-sheet/test/basic/index.html
View File

@@ -68,7 +68,6 @@
}
}, {
text: 'Cancel',
icon: 'close',
role: 'cancel',
handler: () => {
console.log('Cancel clicked');

4
packages/core/src/components/alert-controller/readme.md
View File

@@ -22,7 +22,7 @@ the array) is the main button.
Optionally, a `role` property can be added to a button, such as `cancel`.
If a `cancel` role is on one of the buttons, then if the alert is
dismissed by tapping the backdrop, then it will fire the handler from
dismissed by tapping the backdrop, then it will call the handler from
the button with a cancel role.
@@ -33,7 +33,7 @@ back to the app. Inputs can be used as a simple way to prompt users for
information. Radios, checkboxes and text inputs are all accepted, but they
cannot be mixed. For example, an alert could have all radio button inputs,
or all checkbox inputs, but the same alert cannot mix radio and checkbox
inputs. Do note however, different types of "text"" inputs can be mixed,
inputs. Do note however, different types of "text" inputs can be mixed,
such as `url`, `email`, `text`, etc. If you require a complex form UI
which doesn't fit within the guidelines of an alert then we recommend
building the form within a modal instead.

251
packages/core/src/components/datetime/readme.md
View File

@@ -1,54 +1,55 @@
# ion-datetime
The Datetime component is used to present an interface which makes it easy for
users to select dates and times. Tapping on `<ion-datetime>` will display a picker
interface that slides up from the bottom of the page. The picker then displays
scrollable columns that can be used to individually select years, months, days,
hours and minute values. The Datetime component is similar to the native
`<input type="datetime-local">` element, however, Ionic's Datetime component makes
it easy to display the date and time in a preferred format, and manage the datetime
values.
users to select dates and times. Tapping on `<ion-datetime>` will display a
picker interface that slides up from the bottom of the page. The picker then
displays scrollable columns that can be used to individually select years,
months, days, hours and minute values. The Datetime component is similar to the
native `<input type="datetime-local">` element, however, Ionic's Datetime
component makes it easy to display the date and time in a preferred format, and
manage the datetime values.
```html
<ion-item>
<ion-label>Date</ion-label>
<ion-datetime displayFormat="MM/DD/YYYY" [(ngModel)]="myDate"></ion-datetime>
<ion-datetime displayFormat="MM/DD/YYYY" ></ion-datetime>
</ion-item>
```
## Display and Picker Formats
The Datetime component displays the values in two places: in the `<ion-datetime>`
component, and in the interface that is presented from the bottom of the screen.
The following chart lists all of the formats that can be used.
The Datetime component displays the values in two places: in the
`<ion-datetime>` component, and in the interface that is presented from the
bottom of the screen. The following chart lists all of the formats that can be
used.
| Format | Description | Example |
|---------|--------------------------------|-------------------------|
| `YYYY` | Year, 4 digits | `2018` |
| `YY` | Year, 2 digits | `18` |
| `M` | Month | `1` ... `12` |
| `MM` | Month, leading zero | `01` ... `12` |
| `MMM` | Month, short name | `Jan` |
| `MMMM` | Month, full name | `January` |
| `D` | Day | `1` ... `31` |
| `DD` | Day, leading zero | `01` ... `31` |
| `DDD` | Day, short name | `Fri` |
| `DDDD` | Day, full name | `Friday` |
| `H` | Hour, 24-hour | `0` ... `23` |
| `HH` | Hour, 24-hour, leading zero | `00` ... `23` |
| `h` | Hour, 12-hour | `1` ... `12` |
| `hh` | Hour, 12-hour, leading zero | `01` ... `12` |
| `a` | 12-hour time period, lowercase | `am` `pm` |
| `A` | 12-hour time period, uppercase | `AM` `PM` |
| `m` | Minute | `1` ... `59` |
| `mm` | Minute, leading zero | `01` ... `59` |
| `s` | Second | `1` ... `59` |
| `ss` | Second, leading zero | `01` ... `59` |
| `Z` | UTC Timezone Offset | `Z or +HH:mm or -HH:mm` |
| Format | Description | Example |
| ------ | ------------------------------ | ----------------------- |
| `YYYY` | Year, 4 digits | `2018` |
| `YY` | Year, 2 digits | `18` |
| `M` | Month | `1` ... `12` |
| `MM` | Month, leading zero | `01` ... `12` |
| `MMM` | Month, short name | `Jan` |
| `MMMM` | Month, full name | `January` |
| `D` | Day | `1` ... `31` |
| `DD` | Day, leading zero | `01` ... `31` |
| `DDD` | Day, short name | `Fri` |
| `DDDD` | Day, full name | `Friday` |
| `H` | Hour, 24-hour | `0` ... `23` |
| `HH` | Hour, 24-hour, leading zero | `00` ... `23` |
| `h` | Hour, 12-hour | `1` ... `12` |
| `hh` | Hour, 12-hour, leading zero | `01` ... `12` |
| `a` | 12-hour time period, lowercase | `am` `pm` |
| `A` | 12-hour time period, uppercase | `AM` `PM` |
| `m` | Minute | `1` ... `59` |
| `mm` | Minute, leading zero | `01` ... `59` |
| `s` | Second | `1` ... `59` |
| `ss` | Second, leading zero | `01` ... `59` |
| `Z` | UTC Timezone Offset | `Z or +HH:mm or -HH:mm` |
**Important**: See the [Month Names and Day of the Week Names](#month-names-and-day-of-the-week-names)
section below on how to use different names for the month and day.
**Important**: See the [Month Names and Day of the Week
Names](#month-names-and-day-of-the-week-names) section below on how to use
different names for the month and day.
### Display Format
@@ -57,31 +58,32 @@ printed, as formatted text, within the `ion-datetime` component.
In the following example, the display in the `<ion-datetime>` will use the
month's short name, the numerical day with a leading zero, a comma and the
four-digit year. In addition to the date, it will display the time with the hours
in the 24-hour format and the minutes. Any character can be used as a separator.
An example display using this format is: `Jun 17, 2005 11:06`.
four-digit year. In addition to the date, it will display the time with the
hours in the 24-hour format and the minutes. Any character can be used as a
separator. An example display using this format is: `Jun 17, 2005 11:06`.
```html
<ion-item>
<ion-label>Date</ion-label>
<ion-datetime displayFormat="MMM DD, YYYY HH:mm" [(ngModel)]="myDate"></ion-datetime>
<ion-datetime displayFormat="MMM DD, YYYY HH:mm"></ion-datetime>
</ion-item>
```
### Picker Format
The `pickerFormat` input property determines which columns should be shown in the
interface, the order of the columns, and which format to use within each column.
If the `pickerFormat` input is not provided then it will default to the `displayFormat`.
The `pickerFormat` input property determines which columns should be shown in
the interface, the order of the columns, and which format to use within each
column. If the `pickerFormat` input is not provided then it will default to the
`displayFormat`.
In the following example, the display in the `<ion-datetime>` will use the
`MM/YYYY` format, such as `06/2020`. However, the picker interface
will display two columns with the month's long name, and the four-digit year.
`MM/YYYY` format, such as `06/2020`. However, the picker interface will display
two columns with the month's long name, and the four-digit year.
```html
<ion-item>
<ion-label>Date</ion-label>
<ion-datetime displayFormat="MM/YYYY" pickerFormat="MMMM YYYY" [(ngModel)]="myDate"></ion-datetime>
<ion-datetime displayFormat="MM/YYYY" pickerFormat="MMMM YYYY" ></ion-datetime>
</ion-item>
```
@@ -93,26 +95,26 @@ 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.
But no worries, all is not lost! Ionic's datetime input has been designed so
developers can avoid the common pitfalls, allowing developers to easily format
datetime values within the input, and give the user a simple datetime picker for a
great user experience.
Fortunately, Ionic's datetime input has been designed so developers can avoid
the common pitfalls, allowing developers to easily format datetime values within
the input, and give the user a simple datetime picker for a great user
experience.
##### ISO 8601 Datetime Format: YYYY-MM-DDTHH:mmZ
Ionic uses the [ISO 8601 datetime format](https://www.w3.org/TR/NOTE-datetime)
for its value. The value is simply a string, rather than using JavaScript's `Date`
object. Additionally, when using the ISO datetime format, it makes it easier
to serialize and pass within JSON objects, and sending databases a standardized
format which it can be easily parsed if need be.
for its value. The value is simply a string, rather than using JavaScript's
`Date` object. Additionally, when using the ISO datetime format, it makes it
easier to serialize and pass within JSON objects, and sending databases a
standardized format which it can be easily parsed if need be.
An ISO format can be used as a simple year, or just the hour and minute, or get more
detailed down to the millisecond and timezone. Any of the ISO formats below can be used,
and after a user selects a new value, Ionic will continue to use the same ISO format
which datetime value was originally given as.
An ISO format can be used as a simple year, or just the hour and minute, or get
more detailed down to the millisecond and timezone. Any of the ISO formats below
can be used, and after a user selects a new value, Ionic will continue to use
the same ISO format which datetime value was originally given as.
| Description | Format | Datetime Value Example |
|----------------------|------------------------|------------------------------|
| -------------------- | ---------------------- | ---------------------------- |
| Year | YYYY | 1994 |
| Year and Month | YYYY-MM | 1994-12 |
| Complete Date | YYYY-MM-DD | 1994-12-15 |
@@ -124,112 +126,89 @@ which datetime value was originally given as.
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`.
It's also important to note that neither the `displayFormat` or `pickerFormat` can
set the datetime value's output, which is the value that is set by the component's
`ngModel`. The format's are merely for displaying the value as text and the picker's
interface, but the datetime's value is always persisted as a valid ISO 8601 datetime
string.
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`.
It's also important to note that neither the `displayFormat` or `pickerFormat`
can set the datetime value's output, which is the value that is set by the
component's `ngModel`. The format's are merely for displaying the value as text
and the picker's interface, but the datetime's value is always persisted as a
valid ISO 8601 datetime string.
## Min and Max Datetimes
Dates are infinite in either direction, so for a user's selection there should be at
least some form of restricting the dates that can be selected. By default, the maximum
date is to the end of the current year, and the minimum date is from the beginning
of the year that was 100 years ago.
Dates are infinite in either direction, so for a user's selection there should
be at least some form of restricting the dates that can be selected. By default,
the maximum date is to the end of the current year, and the minimum date is from
the beginning of the year that was 100 years ago.
To customize the minimum and maximum datetime values, the `min` and `max` component
inputs can be provided which may make more sense for the app's use-case, rather
than the default of the last 100 years. Following the same IS0 8601 format listed
in the table above, each component can restrict which dates can be selected by the
user. Below is an example of restricting the date selection between the beginning
of 2016, and October 31st of 2020:
To customize the minimum and maximum datetime values, the `min` and `max`
component inputs can be provided which may make more sense for the app's
use-case, rather than the default of the last 100 years. Following the same IS0
8601 format listed in the table above, each component can restrict which dates
can be selected by the user. Below is an example of restricting the date
selection between the beginning of 2016, and October 31st of 2020:
```html
<ion-item>
<ion-label>Date</ion-label>
<ion-datetime displayFormat="MMMM YYYY" min="2016" max="2020-10-31" [(ngModel)]="myDate">
<ion-datetime displayFormat="MMMM YYYY" min="2016" max="2020-10-31" >
</ion-datetime>
</ion-item>
```
## Month Names and Day of the Week Names
At this time, there is no one-size-fits-all standard to automatically choose the correct
language/spelling for a month name, or day of the week name, depending on the language
or locale. Good news is that there is an
At this time, there is no one-size-fits-all standard to automatically choose the
correct language/spelling for a month name, or day of the week name, depending
on the language or locale. Good news is that there is an
[Intl.DatetimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DatetimeFormat)
standard whichmost* browsers have adopted. However, at this time the standard has not
been fully implemented by all popular browsers so Ionic is unavailable to take advantage
of ityet*. Additionally, Angular also provides an internationalization service, but it
is still under heavy development so Ionic does not depend on it at this time.
standard whichmost* browsers have adopted. However, at this time the standard
has not been fully implemented by all popular browsers so Ionic is unavailable
to take advantage of ityet*. Additionally, Angular also provides an
internationalization service, but it is still under heavy development so Ionic
does not depend on it at this time.
All things considered, the by far easiest solution is to just provide an array of names
if the app needs to use names other than the default English version of month and day
names. The month names and day names can be either configured at the app level, or
individual `ion-datetime` level.
### App Config Level
```ts
//app.module.ts
@NgModule({
...,
imports: [
IonicModule.forRoot(MyApp, {
monthNames: ['janeiro', 'fevereiro', 'mar\u00e7o', ... ],
monthShortNames: ['jan', 'fev', 'mar', ... ],
dayNames: ['domingo', 'segunda-feira', 'ter\u00e7a-feira', ... ],
dayShortNames: ['dom', 'seg', 'ter', ... ],
})
],
...
})
```
All things considered, the by far easiest solution is to just provide an array
of names if the app needs to use names other than the default English version of
month and day names. The month names and day names can be either configured at
the app level, or individual `ion-datetime` level.
### Component Input Level
```html
<ion-item>
<ion-label>Período</ion-label>
<ion-datetime displayFormat="DDDD MMM D, YYYY" [(ngModel)]="myDate"
<ion-datetime
displayFormat="DDDD MMM D, YYYY"
monthNames="janeiro, fevereiro, mar\u00e7o, ..."
monthShortNames="jan, fev, mar, ..."
dayNames="domingo, segunda-feira, ter\u00e7a-feira, ..."
dayShortNames="dom, seg, ter, ..."></ion-datetime>
</ion-item>
```
### Advanced Datetime Validation and Manipulation
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](https://www.w3.org/TR/NOTE-datetime).
However, it's important to note that `ion-datetime` does not attempt to solve all
situtations 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 [moment.js](http://momentjs.com/) to "Parse, validate, manipulate, and
display dates in JavaScript". [Moment.js](http://momentjs.com/) has quickly become
our goto standard when dealing with datetimes within JavaScript, but Ionic does not
prepackage this dependency since most apps will not require it, and its locale
configuration should be decided by the end-developer.
```html
<ion-item>
<ion-label>Date</ion-label>
<ion-datetime displayFormat="MM/DD/YYYY" [(ngModel)]="myDate">
dayShortNames="dom, seg, ter, ...">
</ion-datetime>
</ion-item>
```
### Advanced Datetime Validation and Manipulation
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](https://www.w3.org/TR/NOTE-datetime). However, it's important
to note that `ion-datetime` does not attempt to solve all situtations 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](https://date-fns.org) to work with
dates in JavaScript.
```html
<ion-item>
<ion-label>Date</ion-label>
<ion-datetime displayFormat="MM/DD/YYYY" >
</ion-datetime>
</ion-item>
```
<!-- Auto Generated Below -->