javascript/ionic-framework
1
0
Fork 0
mirror of https://github.com/ionic-team/ionic-framework.git synced 2025-08-15 17:42:15 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(breaking): add breaking changes and copy editing (#17214)

Browse Source 
- adds col auto to grid
- updates overlays to point to the same usage
- copy editing
- adds more info on the tabs changes
- documents event changes closes ionic-team/ionic-docs#258
- update nav event documentation

references #16819
This commit is contained in:
Brandy Carney
2019-01-23 15:25:11 -05:00
committed by GitHub
parent ad0c8a4e5c
commit b31b9f45de
4 changed files with 215 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

266
angular/BREAKING.md
View File

@ -21,6 +21,7 @@ A list of the breaking changes introduced to each component in Ionic Angular v4.
- [Back Button](#back-button)
- [Button](#button)
- [Colors](#colors)
- [Component Imports](#component-imports)
- [Content](#content)
- [Datetime](#datetime)
- [Dynamic Mode](#dynamic-mode)
@ -43,6 +44,7 @@ A list of the breaking changes introduced to each component in Ionic Angular v4.
- [Navbar](#navbar)
- [Option](#option)
- [Overlays](#overlays)
- [Popover](#popover)
- [Radio](#radio)
- [Range](#range)
- [Refresher](#refresher)
@ -54,6 +56,7 @@ A list of the breaking changes introduced to each component in Ionic Angular v4.
- [Tabs](#tabs)
- [Text / Typography](#text--typography)
- [Theming](#theming)
- [Toast](#toast)
- [Toolbar](#toolbar)
@ -86,7 +89,7 @@ await actionSheet.present();
## Alert
The `title`, `subTitle` and `enableBackdropDismiss` properties has been renamed to `header`, `subHeader` and `backdropDismiss` respectivelly.
The `title`, `subTitle` and `enableBackdropDismiss` properties has been renamed to `header`, `subHeader` and `backdropDismiss` respectively.
**Old Usage Example:**
@ -263,7 +266,7 @@ light: #f4f4f4
dark: #222
```
Some of their values have changed and we now include more colors by default:
Some of their values have changed, and we now include more colors by default:
```
primary: #3880ff
@ -280,13 +283,24 @@ dark: #222428
The `secondary` color saw the largest change. If you were previously using our `secondary` color we recommend switching to `success` instead.
## Component Imports
For consistency with other frameworks and the rest of APIs and tooling, the exported
Ionic components are now prefixed with `Ion`:
```diff
- import { Input, List, Slides } from 'ionic-angular';
+ import { IonInput, IonList, IonSlides } from '@ionic/angular';
```
## Content
Content is now a drop-in replacement for `ion-scroll`, that means `ion-content` is much more flexible today, they can be used anywhere, even in a nested fashion.
Content is now a drop-in replacement for `ion-scroll`. This makes `ion-content` much more flexible. It can be used anywhere, even nested.
### resize() was removed
### Method Removed
In Ionic 4, `ion-content` layout is based in flex, that means their size will automatically adjust without requiring to call resize() programmatically.
The `resize` method has been removed from Content. In Ionic 4, the `ion-content` is based on a flex layout. This means the content size will automatically adjust without requiring a call to `resize()`.
### Attributes Renamed
@ -319,6 +333,35 @@ import { Datetime } from '@ionic/angular';
Components are no longer able to have their mode changed dynamically. You can change the mode before the first render, but after that it will not style properly because only the initial mode's styles are included.
## Events
Events now emit as a [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) interface that extends the [Event](https://developer.mozilla.org/en-US/docs/Web/API/Event) interface. This interface includes a `detail` property that holds any data passed when the event is triggered.
This allows you to still get the details of the event. For example, to get the target where the event was dispatched, such as a button that was clicked, you can read in the value of `event.target`.
**Old Usage Example:**
```html
<ion-select (ionChange)="onSelectChange($event)">
```
```typescript
onSelectChange(event) {
const value = event.value;
console.log('Select value is', value);
}
```
**New Usage Example:**
```typescript
onSelectChange(event: CustomEvent) {
const value = event.detail.value;
console.log('Select value is', value);
}
```
## FAB
### Markup Changed
@ -381,8 +424,8 @@ The attributes to align the fab horizontally are now combined under the `horizon
| Old Property | New Property | Property Behavior |
|--------------|----------------------|-------------------------------------------------------------------------|
| left | Removed | |
| right | Removed | |
| left | Removed, see `start` | |
| right | Removed, see `end` | |
| center | `horizontal="center"`| Positions to the center of the viewport. |
| start | `horizontal="start"` | Positions to the left of the viewport in LTR, and to the right in RTL. |
| end | `horizontal="end"` | Positions to the right of the viewport in LTR, and to the left in RTL. |
@ -448,7 +491,7 @@ The `<ion-fab>` container was previously placed inside of the fixed content by d
The Grid has been refactored in order to support css variables and a dynamic number of columns. The following column attributes have been changed.
_In the following examples, `{breakpoint}` refers to the optional screen breakpoint (xs, sm, md, lg, xl) and `{value}` refers to the number of columns._
_In the following examples, `{breakpoint}` refers to the optional screen breakpoint (xs, sm, md, lg, xl) and `{value}` refers to the number of columns (`auto` or a number between `1` and `12`)._
- `col-{breakpoint}-{value}` attributes have been renamed to `size-{breakpoint}=“{value}”`
- `offset-{breakpoint}-{value}` attributes have been renamed to `offset-{breakpoint}=“{value}”`
@ -585,7 +628,7 @@ Item should now be written as an `<ion-item>` element. Ionic will determine when
### Label Required
Previously an `ion-label` would automatically get added to an `ion-item` if one wasn't provided. Now an `ion-label` should always be added if the component is used to display text.
Previously an `ion-label` would automatically get added to an `ion-item` if one wasn't provided. Now an `ion-label` should always be added in the item component.
```html
<ion-item>
@ -667,7 +710,7 @@ By default, items that render buttons or anchor tags will show the arrow in `ios
### Label Required
Previously an `ion-label` would automatically get added to an `ion-item-divider` if one wasn't provided. Now an `ion-label` should always be added if the component is used to display text.
Previously an `ion-label` would automatically get added to an `ion-item-divider` if one wasn't provided. Now an `ion-label` should always be added around the text.
```html
<ion-item-divider>
@ -695,7 +738,7 @@ These values have been renamed to `"start"` and `"end"` to better align with our
### Markup Changed
The option component should not be written as a `button` with an `ion-button` directive anymore. It should be written as an `ion-item-option`. This will render a native button element inside of it.
The option component should now be written as an `ion-item-option`. Previously it was written as a `button` with an `ion-button` directive. The `ion-item-option` element will render a native button element inside of it.
**Old Usage Example:**
@ -736,7 +779,7 @@ The `getSlidingPercent` method has been renamed to `getSlidingRatio` since the f
### Attributes Renamed
The attributes to set label position for input are now combined under the `position` attribute:
The attributes to set label position in an item are now combined under the `position` attribute:
| Old Property | New Property | Property Behavior |
|--------------|----------------------|------------------------------------------------------------------------------|
@ -777,7 +820,7 @@ The attributes to set label position for input are now combined under the `posit
### Label Required
Previously an `ion-label` would automatically get added to an `ion-list-header` if one wasn't provided. Now an `ion-label` should always be added if the component is used to display text.
Previously an `ion-label` would automatically get added to an `ion-list-header` if one wasn't provided. Now an `ion-label` should always be added around the text.
```html
<ion-list-header>
@ -787,38 +830,39 @@ Previously an `ion-label` would automatically get added to an `ion-list-header`
## Loading
`dismissOnPageChange` was removed. Fortunately all the navigation API is promise based and there are global events (`ionNavWillChange`) you can listen in order to detect when navigation occurs.
You should take advantage of these APIs in order to dismiss your loading overlay explicitally.
See [Overlays](#overlays).
## Menu
### Prop renamed
### Properties Renamed
The `swipeEnabled` prop has been renamed to `swipeGesture`.
The `content` prop has been renamed to `contentId` and it points to the DOM id of the content:
- The `swipeEnabled` property has been renamed to `swipeGesture`.
- The `content` prop has been renamed to `contentId` and it points to the DOM id of the content.
**Old Usage Example:**
```html
<ion-menu swipeEnabled="false" content="nav"> </ion-menu>
<ion-nav #nav></ion-nav>
```
### Events renamed
- `ionClose` was renamed to `ionDidClose`
- `ionOpen` was renamed to `ionDidOpen`
**New Usage Example:**
```html
<ion-menu swipeGesture="false" contentId="nav"> </ion-menu>
<ion-nav id="nav"></ion-nav>
```
### Events Renamed
- `ionClose` was renamed to `ionDidClose`
- `ionOpen` was renamed to `ionDidOpen`
## Menu Toggle
### Markup Changed
@ -897,19 +941,19 @@ export class MyPage {
## Nav
### Method renamed
### Method Renamed
The `remove` method has been renamed to `removeIndex` to avoid conflicts with HTML and be more descriptive as to what it does.
The `getActiveChildNavs` method has been renamed to `getChildNavs`.
- The `remove` method has been renamed to `removeIndex` to avoid conflicts with HTML and be more descriptive as to what it does.
- The `getActiveChildNavs` method has been renamed to `getChildNavs`.
### Prop renamed
### Prop Renamed
The `swipeBackEnabled` prop has been renamed to `swipeGesture`.
- The `swipeBackEnabled` prop has been renamed to `swipeGesture`.
## Navbar
The `<ion-navbar>` component has been removed in favor of always using an `<ion-toolbar>` with an added back button:
The `<ion-navbar>` component has been removed in favor of always using an `<ion-toolbar>` with an explicit back button:
**Old Usage Example:**
@ -932,6 +976,7 @@ The `<ion-navbar>` component has been removed in favor of always using an `<ion-
See the [back button](#back-button) changes for more information.
## Option
### Markup Changed
@ -958,19 +1003,16 @@ Select's option element should now be written as `<ion-select-option>`. This mak
</ion-select>
```
### Class Changed
### Class Renamed
The class has been renamed from `Option` to `SelectOption` to keep it consistent with the element tag name.
## Overlays
### Markup Changed
Action Sheet, Alert, Loading, Modal, Popover, and Toast:
- Should now use `async`/`await`
- `enableBackdropDismiss` has been renamed to `backdropDismiss`.
All overlays should now use `async`/`await`. This includes Action Sheet, Alert, Loading, Modal, Popover, and Toast. In addition, the `enableBackdropDismiss` property has been renamed to `backdropDismiss`.
**Old Usage Example:**
@ -1001,12 +1043,42 @@ async presentPopover(ev: any) {
```
### Property Removed
The `dismissOnPageChange` property of the create was removed from Loading & Toast. All of the navigation API is promise based and there are global events (`ionNavWillChange`, `ionNavDidChange`) that you can listen to in order to detect when navigation occurs.
**Old Usage Example:**
```javascript
openLoading() {
let loading = this.loadingCtrl.create({
content: 'Loading...',
dismissOnPageChange: true
});
}
```
**New Usage Example:**
```javascript
openLoading() {
let loading = this.loadingCtrl.create({
content: 'Loading...'
});
}
```
## Popover
See [Overlays](#overlays).
## Radio
### Slot Required
Previously radio was positioned inside of an item automatically or by using `item-left`/`item-right`. It is now required to have a `slot` to be positioned properly.
Previously radio was positioned inside of an item automatically or by using `item-left`/`item-right`. It is now required to have a `slot` to be positioned properly in an item.
**Old Usage Example:**
@ -1155,7 +1227,7 @@ The `enabled` property (with a default value of `true`) has been renamed to `dis
## Scroll
`ion-scroll` has been removed, fortunately `ion-content` can work as a drop-in replacement:
`ion-scroll` has been removed in favor of using `ion-content`:
```diff
- <ion-scroll scrollX="true">
@ -1440,11 +1512,18 @@ The `ios` and `ios-small` spinner's have been renamed to `lines` and `lines-smal
## Tabs
### Breaking changes
Tabs has been completely refactored for Ionic 4. In Ionic 3 there was a lot of magic going on behind the scenes to style and generate the tab bar and buttons. While this made it easy to get up and running using tabs in Ionic, it made it more difficult to customize the tabs.
#### `ion-tabs`
We decided to rethink the tabs implementation to make it more flexible and easier to theme for your application. In order to accomplish this, there had to be some changes to the markup.
The attributes to position the tabs, change the tab layout, enable the tab highlight and hide the tabs have been removed. Instead use [ion-tab-button](#ion-tab-button)
### `ion-tabs`
The general usage of the `ion-tabs` element hasn't changed too drastically. Its purpose is still mostly the same - it wraps the entire layout.
#### Properties Removed
The attributes to position the tabs, change the tab layout, enable the tab highlight and hide the tabs have been removed. Instead customize this content in the [ion-tab-button](#ion-tab-button).
**Old Usage Example:**
@ -1463,21 +1542,99 @@ The attributes to position the tabs, change the tab layout, enable the tab highl
```
#### `ion-tab`
### `ion-tab`
`ion-tab` was removed. Instead you have to use [ion-tab-button](#ion-tab-button).
The `ion-tab` has been removed in the Angular version of Ionic 4. You should use the Angular router with an [ion-tab-button](#ion-tab-button) that has a `tab` property.
#### `ion-tab-button`
```typescript
import { RouterModule, Routes } from '@angular/router';
You can add `<ion-label>` and `<ion-icon>` inside `ion-tab-button`. `ion-tab-button` has to be wrapped by `<ion-tab-bar>`.
import { TabsPage } from './tabs.page';
The tab attribute defines the route (which should be shown on switching to this tab).
const routes: Routes = [
{
path: 'tabs',
component: TabsPage,
children: [
{
path: 'tab1',
children: [
{
path: '',
loadChildren: '../tab1/tab1.module#Tab1PageModule'
}
]
},
{
path: 'tab2',
children: [
{
path: '',
loadChildren: '../tab2/tab2.module#Tab2PageModule'
}
]
},
{
path: 'tab3',
children: [
{
path: '',
loadChildren: '../tab3/tab3.module#Tab3PageModule'
}
]
},
{
path: '',
redirectTo: '/tabs/tab1',
pathMatch: 'full'
}
]
},
{
path: '',
redirectTo: '/tabs/tab1',
pathMatch: 'full'
}
];
```
```html
<ion-tabs>
<ion-tab-bar slot="bottom">
<ion-tab-button tab="tab1">
<ion-icon name="flash"></ion-icon>
<ion-label>Tab One</ion-label>
</ion-tab-button>
<ion-tab-button tab="tab2">
<ion-icon name="apps"></ion-icon>
<ion-label>Tab Two</ion-label>
</ion-tab-button>
<ion-tab-button tab="tab3">
<ion-icon name="send"></ion-icon>
<ion-label>Tab Three</ion-label>
</ion-tab-button>
</ion-tab-bar>
</ion-tabs>
```
### `ion-tab-bar`
A new element, `ion-tab-bar`, creates the tab bar that will contain the tab buttons and allow for full customization. It requires `slot` to be placed properly above or below the content.
### `ion-tab-button`
A new element, `ion-tab-button`, is used to create each button in the tab bar. These could be static links to different routes, buttons with click handlers on them, or link to whole tab views.
You can add `<ion-label>` and `<ion-icon>` inside of an `<ion-tab-button>`. An `<ion-tab-button>` should be wrapped by an `<ion-tab-bar>`.
The tab attribute defines the route to be shown upon clicking on this tab.
**Old Usage Example:**
```html
<ion-tabs>
<ion-tab tabTitle="Schedule" tabIcon="add"></ion-tab>
<ion-tab tabTitle="Map" tabIcon="map" tabBadge="2" tabBadgeStyle="danger" enabled="false"></ion-tab>
</ion-tabs>
```
@ -1493,16 +1650,12 @@ The tab attribute defines the route (which should be shown on switching to this
<ion-label>Map</ion-label>
<ion-badge color="danger">2</ion-badge>
</ion-tab-button>
<!-- No ion-tab, just a button that looks like a tab -->
<ion-tab-button (click)="schedule()">
<ion-icon name="add"></ion-icon>
<ion-label>Schedule</ion-label>
</ion-tab-button>
</ion-tab-bar>
</ion-tabs>
```
See more usage examples in the [Tabs](https://github.com/ionic-team/ionic/blob/master/core/src/components/tabs) documentation.
## Text / Typography
@ -1675,6 +1828,11 @@ Sass variables should no longer be used to change Ionic components. We have buil
For more information on theming, check out the [theming documentation](https://beta.ionicframework.com/docs/theming/basics).
## Toast
See [Overlays](#overlays).
## Toolbar
### Menu Toggle

2
core/src/components.d.ts vendored
View File

@ -2776,7 +2776,7 @@ export namespace Components {
*/
'onIonNavDidChange'?: (event: CustomEvent<void>) => void;
/**
* Event fired when the nav will components
* Event fired when the nav will change components
*/
'onIonNavWillChange'?: (event: CustomEvent<void>) => void;
/**

2
core/src/components/nav/nav.tsx
View File

@ -85,7 +85,7 @@ export class Nav implements NavOutlet {
*/
@Event() ionNavWillLoad!: EventEmitter<void>;
/**
* Event fired when the nav will components
* Event fired when the nav will change components
*/
@Event({ bubbles: false }) ionNavWillChange!: EventEmitter<void>;
/**

2
core/src/components/nav/readme.md
View File

@ -23,7 +23,7 @@ Unlike RouterOutlet, Nav is not tied to a particular router. Meaning that if we
| Event | Description | Type |
| ------------------ | ----------------------------------------------- | ------------------- |
| `ionNavDidChange` | Event fired when the nav has changed components | `CustomEvent<void>` |
| `ionNavWillChange` | Event fired when the nav will components | `CustomEvent<void>` |
| `ionNavWillChange` | Event fired when the nav will change components | `CustomEvent<void>` |
## Methods