javascript/ionic-framework

Fork 0

mirror of https://github.com/ionic-team/ionic-framework.git synced 2026-03-13 10:22:08 +08:00

Files

Brandy Carney 6fc1612f42 docs(breaking): add breaking changes for v5 (#20156 )

2020-01-13 11:29:29 -05:00

21 KiB

Raw Blame History

Breaking Changes

This is a comprehensive list of the breaking changes introduced in the major version releases of Ionic Framework.

Version 5.x

CSS
Components
- Anchor
- Back Button
- Card
- Controllers
- Header / Footer
- List Header
- Menu
- Nav Link
- Searchbar
- Segment
- Skeleton Text
- Split Pane
- Toast
Colors
Events
Mode
Ionicons

CSS

CSS Utilities

We originally added CSS utility attributes for styling components because it was a quick and easy way to wrap text or add padding to an element. Once we added support for multiple frameworks as part of our "Ionic for everyone" approach, we quickly determined there were problems with using CSS attributes with frameworks that use JSX and Typescript. In order to solve this we added CSS classes. Rather than support CSS attributes in certain frameworks and classes in others, we decided to remove the CSS attributes and support what works in all of them, classes, for consistency. In addition to this, changing to classes prefixed with ion avoids conflict with native attributes & user's CSS. In the latest version of Ionic 4, there are deprecation warnings printed in the console to show what the new classes are, and the documentation has been updated since support for classes was added to remove all references to attributes: https://ionicframework.com/docs/layout/css-utilities.

Some examples of what's changed are below. This is not all-inclusive, see the documentation linked above for all of the available CSS utility classes.

<ion-header text-center></ion-header>
<ion-content padding></ion-content>
<ion-label text-wrap></ion-label>
<ion-item wrap></ion-item>

becomes

<ion-header class="ion-text-center"></ion-header>
<ion-content class="ion-padding"></ion-content>
<ion-label class="ion-text-wrap"></ion-label>
<ion-item class="ion-wrap"></ion-item>

Display Classes

The responsive display classes found in the display.css file have had their media queries updated to better reflect how they should work. Instead of using the maximum value of the breakpoint for .ion-hide-{breakpoint}-down classes it will use the minimum of that breakpoint.

The Ionic breakpoints are the following:

Breakpoint Name	Width
xs	0
sm	576px
md	768px
lg	992px
xl	1200px

Previously, if you added the class ion-hide-md-down to an element, it would hide the element when the screen size was 991px (the maximum of the md breakpoint) or smaller. Now, using this same class will hide the element when the maximum screen size is 768px.

Below is a table of how the media queries have changed for each class:

Class Name	Ionic 4	Ionic 5
`.ion-hide-down`	`@media (max-width: 575px)`	all screen sizes
`.ion-hide-sm-down`	`@media (max-width: 767px)`	`@media (max-width: 576px)`
`.ion-hide-md-down`	`@media (max-width: 991px)`	`@media (max-width: 768px)`
`.ion-hide-lg-down`	`@media (max-width: 1199px)`	`@media (max-width: 992px)`
`.ion-hide-xl-down`	all screen sizes	`@media (max-width: 1200px)`

Note that no changes were made to the .ion-hide-{breakpoint}-up classes.

See the CSS Utilities responsive display documentation for more information.

Activated, Focused, Hover States

The .activated class that gets added has been renamed to .ion-activated for consistency with how we add focused to elements and to avoid conflicts in users' CSS.

Distributed Sass

The scss files have been removed from dist/. CSS variables should be used to theme instead.

Components

Anchor

The ion-anchor component has been renamed to ion-router-link as this is a better description of which component it should be used with. This component should still only be used in vanilla and Stencil JavaScript projects. Angular projects should use an <a> and routerLink with the Angular router. See the documentation for router-link for more information.

Back Button

Converted ion-back-button to use shadow DOM.

Card

Converted ion-card to use shadow DOM.

Controllers

The controller components (ion-action-sheet-controller, ion-alert-controller, ion-loading-controller, ion-menu-controller, ion-modal-controller, ion-picker-controller, ion-popover-controller, ion-toast-controller) have been removed from Ionic core as elements. They should be imported from @ionic/core instead. This will not affect projects that use Angular or React. Below is an example of the loading controller change in a JavaScript project, but this change applies to all controller elements.

<ion-loading-controller></ion-loading-controller>

<script>
  async function presentLoading() {
    const loadingController = document.querySelector('ion-loading-controller');

    const loading = await loadingController.create({
      message: 'Hello',
      duration: 2000
    });
    await loading.present();
  }
</script>

becomes

<script type="module">
  import { loadingController } from '@ionic/core';
  window.loadingController = loadingController;
</script>

<script>
  async function presentLoading() {
    const loading = await loadingController.create({
      message: 'Hello',
      duration: 2000
    });
    await loading.present();
  }
</script>

Header / Footer

The no-border attribute has been removed, use ion-no-border class instead. See CSS Utilities above for more information on why this change was made.

List Header

The list header has been redesigned to match the latest iOS spec. This may break the design of your application as the previous design had a small font size with uppercase text. The latest design includes a larger, bolder text. If the old look is desired, use custom CSS to achieve it.

The swipeEnable() function has been removed in Angular, use swipeGesture() instead.
The side values left and right have been removed, use start and end instead.

Removed the main attribute, use content-id (for vanilla JS / Vue) and contentId (for Angular / React) instead.

<ion-menu>...</ion-menu>
<ion-content main>...</ion-content>

becomes

<ion-menu content-id="main"></ion-menu>
<ion-content id="main">...</ion-content>

The presentation type in ios now defaults to "overlay".

Nav Link

The ion-nav-push, ion-nav-back, and ion-nav-set-root components have been removed in favor of using ion-nav-link with a router-direction property which accepts ”root”, “forward”, and “back”. This reduces the need for maintaining multiple components when they all do the same thing with different transition directions. See the documentation for nav-link for more information.

Searchbar

Show Cancel Button

The show-cancel-button property of the searchbar no longer accepts boolean values. Accepted values are strings: "focus", "always", "never".

<ion-searchbar show-cancel-button>
<ion-searchbar show-cancel-button="true">
<ion-searchbar show-cancel-button="false">

becomes

<ion-searchbar show-cancel-button="focus">
<ion-searchbar show-cancel-button="focus">
<ion-searchbar show-cancel-button="never">

See the Searchbar documentation for more information.

Inputmode

The inputmode property for ion-searchbar now defaults to undefined. To get the old behavior, set the inputmode property to "search".

Segment

Skeleton Text

The width property has been removed in favor of using CSS styling.

Split Pane

Converted to use shadow DOM.

Removed the main attribute, use content-id (for vanilla JS / Vue) and contentId (for Angular / React) instead.

<ion-split-pane>
  ...
  <div main>...</div>
</ion-split-pane>

becomes

<ion-split-pane content-id="main">
  ...
  <div id="main">...</div>
</ion-split-pane>

Toast

The close button properties (showCloseButton and closeButtonText) have been removed. Use the buttons array instead with role: 'cancel'. See the usage documentation for more information.

async presentToast() {
  const toast = await this.toastController.create({
    message: 'Your settings have been saved.',
    showCloseButton: true,
    closeButtonText: 'Close'
  });
  toast.present();
}

becomes

async presentToast() {
  const toast = await this.toastController.create({
    message: 'Your settings have been saved.',
    buttons: [
      {
        text: 'Close',
        role: 'cancel',
        handler: () => {
          console.log('Close clicked');
        }
      }
    ]
  });
  toast.present();
}

Colors

The default Ionic colors have been updated to the following:

primary:         #3880ff
secondary:       #3dc2ff
tertiary:        #5260ff
success:         #2dd36f
warning:         #ffc409
danger:          #eb445a
light:           #f4f5f8
medium:          #92949c
dark:            #222428

primary, light and dark have not changed. The contrast color for warning has been updated to #000.

This will only be a breaking change in your app if you are not using one of our starters & not overriding the defaults. If you are overriding the defaults already these will need to be manually updated if desired.

Events

The @ionic/angular Events service has been removed.

Use "Observables" for a similar pub/sub architecture: https://angular.io/guide/observables
Use "Redux" for advanced state management: https://ngrx.io

Mode

Mode is now cascaded from the parent to the child component. Previously, if you wanted to update a component and its children to use the same mode, you'd have to set it on all components. For example, if you wanted to use a md segment no matter the mode, you'd have to write the following:

<ion-segment mode="md">
  <ion-segment-button mode="md">Button</ion-segment-button>
  <ion-segment-button mode="md">Button</ion-segment-button>
</ion-segment>

Now, the mode only needs to be set on the ion-segment and it will be inherited. If this behavior is not desired set a different mode on the child component.

Ionicons

The table below outlines icons that were removed or renamed.

Icon Name		Status	Notes
add-circle	❌	deleted	re-added as "circled" icon
add-circle-outline	❌	deleted	re-added as "circled" icon
appstore	❌	deleted	added as google play & apple app store logos
arrow-dropdown-circle	✏️	renamed	renamed to "arrow-down-circle"
arrow-dropdown	✏️	renamed	renamed to "arrow-down"
arrow-dropleft-circle	✏️	renamed	renamed to "arrow-back-circle"
arrow-dropleft	✏️	renamed	renamed to "arrow-back"
arrow-dropright-circle	✏️	renamed	renamed to "arrow-forward-circle"
arrow-dropright	✏️	renamed	renamed to "arrow-forward"
arrow-dropup-circle	✏️	renamed	renamed to "arrow-up-circle"
arrow-dropup	✏️	renamed	renamed to "arrow-up"
arrow-round-back	❌	deleted	becomes "arrow-back"
arrow-round-down	❌	deleted	becomes "arrow-down"
arrow-round-forward	❌	deleted	becomes "arrow-forward"
arrow-round-up	❌	deleted	becomes "arrow-up"
bowtie	❌	deleted
chatboxes	✏️	renamed	renamed to "chatbox"
checkbox-outline	❌	deleted
checkmark-circle-outline	❌	deleted
clock	❌	deleted
close-circle-outline	❌	deleted
cloud-outline	✏️	renamed	renamed to "cloud"
contact	✏️	renamed	renamed to "person-circle"
contacts	✏️	renamed	renamed to "person-circle"
done-all	✏️	renamed	renamed to "checkmark-done"
fastforward	✏️	renamed	renamed to "play-forward"
filing	✏️	renamed	renamed to "file-tray"
freebsd-devil	❌	deleted
game-controller-a	❌	deleted
game-controller-b	❌	deleted	added as "game-controller"
googleplus	❌	deleted
hand	❌	deleted	split into "hand-left" and "hand-right"
heart-empty	✏️	renamed	renamed to "heart"
help-circle-outline	❌	deleted	exists as circled version
information-circle-outline	❌	deleted	exists as circled version
jet	❌	deleted	use "airplane"
list-box	❌	deleted
lock	✏️	renamed	renamed to "lock-closed"
microphone	❌	deleted
model-s	❌	deleted	added as "car-sport"
more	❌	deleted	use "ellipsis-horizontal" for `ios` and "ellipsis-vertical" for `md`
notifications-outline	❌	deleted	exists as circled version
outlet	❌	deleted
paper	✏️	renamed	renamed to "newspaper"
pie	✏️	renamed	renamed to "pie chart"
pint	❌	deleted
photos	❌	deleted	use "image" or "images"
qr-scanner	✏️	renamed	renamed to "scanner"
quote	❌	deleted
redo	✏️	renamed	renamed to "arrow-redo"
remove-circle-outline	❌	deleted	exists as circled version
reorder	❌	deleted	added as reorder-two, reorder-three, reorder-four
return-left	✏️	renamed	renamed to "return-right-up/down-arrow"
return-right	✏️	renamed	renamed to "return-right-up/down-arrow"
rewind	✏️	renamed	renamed to "play-back"
reverse-camera	✏️	renamed	renamed to "camera-reverse"
share-alt	❌	deleted
skip-backward	✏️	renamed	renamed to "play-skip-back"
skip-forward	✏️	renamed	renamed to "play-skip-forward"
star-outline	✏️	renamed	renamed to "star"
stats	✏️	renamed	renamed to "stats-chart"
swap	❌	deleted	use "swap-horizontal" or "swap-vertical"
text	✏️	renamed	renamed to "chatbox-ellipsis"
undo	✏️	renamed	renamed to "arrow-undo"
unlock	✏️	renamed	renamed to "lock-open"

Version 4.x

The list of the breaking changes introduced in Ionic Angular v4 can be found in angular/BREAKING.md.

Legacy

For the breaking changes of the older legacy versions (versions 2.x & 3.x) of Ionic Framework, see the v3 changelog.

21 KiB Raw Blame History

Breaking Changes

Versions

Version 5.x

CSS

CSS Utilities

Display Classes

Activated, Focused, Hover States

Distributed Sass

Components

Anchor

Back Button

Card

Controllers

Header / Footer

List Header

Menu

Nav Link

Searchbar

Show Cancel Button

Inputmode

Segment

Skeleton Text

Split Pane

Toast

Colors

Events

Mode

Ionicons

Version 4.x

Legacy

21 KiB

Raw Blame History