javascript/ionic-framework

Fork 0

mirror of https://github.com/ionic-team/ionic-framework.git synced 2025-08-26 08:13:34 +08:00

Files

Brandy Carney 2f32ecc15a docs(breaking): update breaking changes to include item sliding markup

2018-02-09 22:41:30 -05:00

21 KiB

Raw Blame History

Breaking Changes

A list of the breaking changes introduced in Ionic Angular v4.

Dynamic Mode
Button
Chip
Cordova
Datetime
FAB
Fixed Content
Icon
Input
Item
Item Divider
Item Sliding
List Header
Menu Toggle
Nav
Option
Radio
Range
Segment
Select
Text/Typography
Toolbar

Dynamic Mode

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.

Button

Markup Changed

Button should now be written as an <ion-button> element. Ionic will determine when to render an anchor tag based on the presence of an href attribute.

Old Usage Example:

<button ion-button (click)="doSomething()">
  Default Button
</button>

<a ion-button href="#">
  Default Anchor
</a>

New Usage Example:

<ion-button (click)="doSomething()">
  Default Button
</ion-button>

<ion-button href="#">
  Default Anchor
</ion-button>

Attributes Renamed

Previously to style icons inside of a button the following attributes were used: icon-left, icon-right, (and with the added support of RTL) icon-start, icon-end.

These have been renamed to the following, and moved from the button element to the icon itself:

Old Property	New Property	Property Behavior
`icon-left`, `icon-start`	`slot="start"`	Positions to the left of the button in LTR, and to the right in RTL.
`icon-right`, `icon-end`	`slot="end"`	Positions to the right of the button in LTR, and to the left in RTL.

In addition, several sets of mutually exclusive boolean attributes have been combined into a single string attribute.

The small and large attributes are now combined under the size attribute. The clear, outline, and solid attributes have been combined under fill. And, lastly, the full and block attributes have been combined under expand.

Old Property	New Property	Property Behavior
`small`, `large`	`size`	Sets the button size.
`clear`, `outline`, `solid`	`fill`	Sets the button fill style.
`full`, `block`	`expand`	Sets the button width.

Old Usage Example:

<ion-button icon-left>
  <ion-icon name="home"></ion-icon>
  Icon Left
</ion-button>

<ion-button icon-start>
  <ion-icon name="home"></ion-icon>
  Icon Left on LTR, Right on RTL
</ion-button>

<ion-button icon-right>
  Icon Right
  <ion-icon name="home"></ion-icon>
</ion-button>

<ion-button icon-end>
  Icon Right on LTR, Left on RTL
  <ion-icon name="home"></ion-icon>
</ion-button>

<ion-button large>
  Large Button
</ion-button>

<ion-button outline>
  Outline Button
</ion-button>

<ion-button full>
  Full-width Button
</ion-button>

New Usage Example:

<ion-button>
  <ion-icon slot="start" name="home"></ion-icon>
  Icon Left on LTR, Right on RTL
</ion-button>

<ion-button>
  Icon Right on LTR, Left on RTL
  <ion-icon slot="end" name="home"></ion-icon>
</ion-button>

<ion-button size="large">
  Large Button
</ion-button>

<ion-button fill="outline">
  Outline Button
</ion-button>

<ion-button expand="full">
  Full-width Button
</ion-button>

Chip

Markup Changed

Buttons inside of an <ion-chip> container should now be written as an <ion-chip-button> element. Ionic will determine when to render an anchor tag based on the presence of an href attribute.

Old Usage Example:

<ion-chip>
  <ion-label>Default</ion-label>
  <ion-button clear color="light">
    <ion-icon name="close-circle"></ion-icon>
  </ion-button>
</ion-chip>

New Usage Example:

<ion-chip>
  <ion-label>Default</ion-label>
  <ion-chip-button fill="clear" color="light">
    <ion-icon name="close-circle"></ion-icon>
  </ion-chip-button>
</ion-chip>

Datetime

The Datetime classes and interfaces have changed capitalization from DateTime to Datetime. This is more consistent with other components and their tags.

Old Usage Example:

import { DateTime } from 'ionic-angular';

New Usage Example:

import { Datetime } from 'ionic-angular';

Cordova

Sass variables for changing the cordova statusbar have been renamed to app:

Old Usage Example:

$cordova-ios-statusbar-padding:   20px;
$cordova-md-statusbar-padding:    20px;

New Usage Example:

$app-ios-statusbar-padding:   20px;
$app-md-statusbar-padding:    20px;

FAB

Markup Changed

Buttons inside of an <ion-fab> container should now be written as an <ion-fab-button> element. Ionic will determine when to render an anchor tag based on the presence of an href attribute.

Old Usage Example:

<ion-fab top right edge>
  <button ion-fab>
    <ion-icon name="add"></ion-icon>
  </button>
  <ion-fab-list>
    <button ion-fab>
      <ion-icon name="logo-facebook"></ion-icon>
    </button>
    <button ion-fab>
      <ion-icon name="logo-twitter"></ion-icon>
    </button>
    <button ion-fab>
      <ion-icon name="logo-vimeo"></ion-icon>
    </button>
    <button ion-fab>
      <ion-icon name="logo-googleplus"></ion-icon>
    </button>
  </ion-fab-list>
</ion-fab>

New Usage Example:

<ion-fab top right edge>
  <ion-fab-button>
    <ion-icon name="add"></ion-icon>
  </ion-fab-button>
  <ion-fab-list>
    <ion-fab-button>
      <ion-icon name="logo-facebook"></ion-icon>
    </ion-fab-button>
    <ion-fab-button>
      <ion-icon name="logo-twitter"></ion-icon>
    </ion-fab-button>
    <ion-fab-button>
      <ion-icon name="logo-vimeo"></ion-icon>
    </ion-fab-button>
    <ion-fab-button>
      <ion-icon name="logo-googleplus"></ion-icon>
    </ion-fab-button>
  </ion-fab-list>
</ion-fab>

Fixed Content

The <ion-fab> container was previously placed inside of the fixed content by default. Now, any fixed content should go inside of the <ion-fixed> container.

Old Usage Example:

<ion-content>
  <ion-fab top right edge>
    <!-- fab buttons and lists -->
  </ion-fab>
  Scrollable Content
</ion-content>

New Usage Example:

<ion-fixed>
  <ion-fab top right edge>
    <!-- fab buttons and lists -->
  </ion-fab>
</ion-fixed>
<ion-content>
  Scrollable Content
</ion-content>

Icon

Fonts Removed

Icons have been refactored to use SVGs instead of fonts. Ionic will only fetch the SVG for the icon when it is needed, instead of having a large font file that is always loaded in.

If any CSS is being overridden for an icon it will need to change to override the SVG itself. Below is a usage example of the differences in changing the icon color.

Old Usage Example:

.icon {
  color: #000;
}

New Usage Example:

.icon {
  fill: #000;
}

Property Removed

The isActive property has been removed. It only worked for ios icons previously. If you would like to switch between an outline and solid icon you should set it in the name, or ios/md attribute and then change it when needed.

Input

The Sass variables were all renamed from having $text-input as the prefix to $input.

Old Usage Example:

$text-input-highlight-color-valid:       #32db64;

New Usage Example:

$input-highlight-color-valid:       #32db64;

Item

Markup Changed

Item should now be written as an <ion-item> element. Ionic will determine when to render an anchor tag based on the presence of an href attribute, and a button tag based on the presence of a click. Otherwise, it will render a div.

Old Usage Example:

<ion-item>
  Default Item
</ion-item>

<button ion-item (click)="doSomething()">
  Button Item
</button>

<a ion-item href="#">
  Anchor Item
</a>

New Usage Example:

<ion-item>
  Default Item
</ion-item>

<ion-item (click)="doSomething()">
  Button Item
</ion-item>

<ion-item href="#">
  Anchor Item
</ion-item>

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.

<ion-item>
  <ion-label>Item Label</ion-label>
</ion-item>

Attributes Renamed

Previously to position elements inside of an ion-item the following attributes were used: item-left, item-right, (and with the added support of RTL) item-start, item-end.

These have been renamed to the following:

Old Property	New Property	Property Behavior
`item-left`, `item-start`	`slot="start"`	Positions to the left of the item in LTR, and to the right in RTL.
`item-right`, `item-end`	`slot="end"`	Positions to the right of the item in LTR, and to the left in RTL.

Old Usage Example:

<ion-item>
  <div item-left>Left</div>
  <ion-label>Item Label</ion-label>
  <div item-right>Right</div>
</ion-item>

<ion-item>
  <div item-start>Left on LTR, Right on RTL</div>
  <ion-label>Item Label</ion-label>
  <div item-end>Right on LTR, Left on RTL</div>
</ion-item>

New Usage Example:

<ion-item>
  <div slot="start">Left on LTR, Right on RTL</div>
  <ion-label>Item Label</ion-label>
  <div slot="end">Right on LTR, Left on RTL</div>
</ion-item>

Item Divider

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.

<ion-item-divider>
  <ion-label>Item Divider Label</ion-label>
</ion-item-divider>

List Header

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.

<ion-list-header>
  <ion-label>List Header Label</ion-label>
</ion-list-header>

Markup Changed

The menuToggle attribute should not be added to an element anymore. Elements that should toggle a menu should be wrapped in an ion-menu-toggle element.

Old Usage Example:

<button ion-button menuToggle>
  Toggle Menu
</button>

New Usage Example:

<ion-menu-toggle>
  <ion-button>
    Toggle Menu
  </ion-button>
</ion-menu-toggle>

Item Sliding

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.

Old Usage Example:

<ion-item-sliding>
  <ion-item>
    Item 1
  </ion-item>
  <ion-item-options side="right">
    <button ion-button expandable>
      <ion-icon name="star"></ion-icon>
    </button>
  </ion-item-options>
</ion-item-sliding>

New Usage Example:

<ion-item-sliding>
  <ion-item>
    <ion-label>Item 1</ion-label>
  </ion-item>
  <ion-item-options side="right">
    <ion-item-option expandable>
      <ion-icon name="star"></ion-icon>
    </ion-item-option>
  </ion-item-options>
</ion-item-sliding>

Method Renamed

The getSlidingPercent method has been renamed to getSlidingRatio since the function is returning a ratio of the open amount of the item compared to the width of the options.

Previously if a menuToggle directive was added to an Ionic button in a toolbar, it would be positioned outside of the ion-buttons element. Since menu toggle is simply a wrapper to a button now, it should be placed inside of the ion-buttons element.

Old Usage Example:

<ion-toolbar>
  <button ion-button menuToggle>
    <ion-icon name="menu"></ion-icon>
  </button>
  <ion-title>Left side menu toggle</ion-title>
</ion-toolbar>

New Usage Example:

<ion-toolbar>
  <ion-buttons slot="start">
    <ion-menu-toggle>
      <ion-button>
        <ion-icon slot="icon-only" name="menu"></ion-icon>
      </ion-button>
    </ion-menu-toggle>
  </ion-buttons>
  <ion-title>Left side menu toggle</ion-title>
</ion-toolbar>

Nav

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.

Option

Markup Changed

Select's option element should now be written as <ion-select-option>. This makes it more obvious that the element should only be used with a Select.

Old Usage Example:

<ion-select>
  <ion-option>Option 1</ion-option>
  <ion-option>Option 2</ion-option>
  <ion-option>Option 3</ion-option>
</ion-select>

New Usage Example:

<ion-select>
  <ion-select-option>Option 1</ion-select-option>
  <ion-select-option>Option 2</ion-select-option>
  <ion-select-option>Option 3</ion-select-option>
</ion-select>

Class Changed

The class has been renamed from Option to SelectOption to keep it consistent with the element tag name.

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.

** Old Usage Example **

<ion-item>
  <ion-label>Apple</ion-label>
  <ion-radio value="apple"></ion-radio>
</ion-item>

<ion-item>
  <ion-label>Grape, checked, disabled</ion-label>
  <ion-radio item-left value="grape" checked disabled></ion-radio>
</ion-item>

<ion-item>
  <ion-label>Cherry</ion-label>
  <ion-radio item-right color="danger" value="cherry"></ion-radio>
</ion-item>

** New Usage Example **

<ion-item>
  <ion-label>Apple</ion-label>
  <ion-radio slot="start" value="apple"></ion-radio>
</ion-item>

<ion-item>
  <ion-label>Grape, checked, disabled</ion-label>
  <ion-radio slot="start" value="grape" checked disabled></ion-radio>
</ion-item>

<ion-item>
  <ion-label>Cherry</ion-label>
  <ion-radio slot="end" color="danger" value="cherry"></ion-radio>
</ion-item>

Radio Group

Radio group has been changed to an element. It should now be wrapped around any <ion-radio> elements as <ion-radio-group>.

** Old Usage Example **

<ion-list radio-group>
  <ion-item>
    <ion-label>Apple</ion-label>
    <ion-radio value="apple"></ion-radio>
  </ion-item>

  <ion-item>
    <ion-label>Grape, checked, disabled</ion-label>
    <ion-radio value="grape" checked disabled></ion-radio>
  </ion-item>

  <ion-item>
    <ion-label>Cherry</ion-label>
    <ion-radio color="danger" value="cherry"></ion-radio>
  </ion-item>
</ion-list>

** New Usage Example **

<ion-list>
  <ion-radio-group>
    <ion-item>
      <ion-label>Apple</ion-label>
      <ion-radio slot="start" value="apple"></ion-radio>
    </ion-item>

    <ion-item>
      <ion-label>Grape, checked, disabled</ion-label>
      <ion-radio slot="start" value="grape" checked disabled></ion-radio>
    </ion-item>

    <ion-item>
      <ion-label>Cherry</ion-label>
      <ion-radio slot="start" color="danger" value="cherry"></ion-radio>
    </ion-item>
  </ion-radio-group>
</ion-list>

Range

Attributes Renamed

Previously to place content inside of a range the following attributes were used: range-left, range-right, (and with the added support of RTL) range-start, range-end.

These have been renamed to the following:

Old Property	New Property	Property Behavior
`range-left`, `range-start`	`slot="start"`	Positions to the left of the range in LTR, and to the right in RTL.
`range-right`, `range-end`	`slot="end"`	Positions to the right of the range in LTR, and to the left in RTL.

Old Usage Example:

<ion-range>
  <ion-icon name="sunny" range-left></ion-icon>
  <ion-icon name="sunny" range-right></ion-icon>
</ion-range>

<ion-range>
  <ion-icon name="sunny" range-start></ion-icon>
  <ion-icon name="sunny" range-end></ion-icon>
</ion-range>

New Usage Example:

<ion-range>
  <ion-icon name="sunny" slot="start"></ion-icon>
  <ion-icon name="sunny" slot="end"></ion-icon>
</ion-range>

Segment

The markup hasn't changed for Segments, but now writing <ion-segment-button> will render a native button element inside of it.

Select

The selectOptions property was renamed to interfaceOptions since it directly correlates with the interface property.

Old Usage Example:

<ion-select [selectOptions]="customOptions">
  ...
</ion-select>

this.customOptions = {
  title: 'Pizza Toppings',
  subTitle: 'Select your toppings'
};

New Usage Example:

<ion-select [interfaceOptions]="customOptions">
  ...
</ion-select>

this.customOptions = {
  title: 'Pizza Toppings',
  subTitle: 'Select your toppings'
};

Text / Typography

Markup Changed

Typography should now be written as an <ion-text> element. Previously the ion-text attribute could be added to any HTML element to set its color. It should now be used as a wrapper around the HTML elements to style.

Old Usage Example:

<h1 ion-text color="secondary">H1: The quick brown fox jumps over the lazy dog</h1>

<h2 ion-text color="primary">H2: The quick brown fox jumps over the lazy dog</h2>

<h3 ion-text color="light">H3: The quick brown fox jumps over the lazy dog</h3>

<p>
  I saw a werewolf with a Chinese menu in his hand.
  Walking through the <sub ion-text color="danger">streets</sub> of Soho in the rain.
  He <i ion-text color="primary">was</i> looking for a place called Lee Ho Fook's.
  Gonna get a <a ion-text color="secondary">big dish of beef chow mein.</a>
</p>

New Usage Example:

<ion-text color="secondary">
  <h1>H1: The quick brown fox jumps over the lazy dog</h1>
</ion-text>

<ion-text color="primary">
  <h2>H2: The quick brown fox jumps over the lazy dog</h2>
</ion-text>

<ion-text color="light">
  <h3>H3: The quick brown fox jumps over the lazy dog</h3>
</ion-text>

<p>
  I saw a werewolf with a Chinese menu in his hand.
  Walking through the <ion-text color="danger"><sub>streets</sub></ion-text> of Soho in the rain.
  He <ion-text color="primary"><i>was</i></ion-text> looking for a place called Lee Ho Fook's.
  Gonna get a <ion-text color="secondary"><a>big dish of beef chow mein.</a></ion-text>
</p>

Attributes Renamed

The attributes to position an ion-buttons element inside of a toolbar have been renamed, as well as the behavior attached to the name. We noticed there was some confusion behind the behavior of the start and end attributes, and with the new support for RTL we wanted to make the behavior of these match RTL. In order to do this we had to rename the old start/end to something that makes more sense with their behavior.

The names and behavior of each of the properties was previously:

Old Property	Property Behavior
`start`	Positions element to the left of the content in `ios` mode, and directly to the right in `md` and `wp` mode.
`end`	Positions element to the right of the content in `ios` mode, and to the far right in `md` and `wp` mode.
`left`	Positions element to the left of all other elements.
`right`	Positions element to the right of all other elements.

The properties have been renamed to the following:

Old Property	New Property	Property Behavior
`start`	`slot="mode-start"`	Positions element to the `left` of the content in `ios` mode, and directly to the `right` in `md` and `wp` mode.
`end`	`slot="mode-end"`	Positions element to the `right` of the content in `ios` mode, and to the far right in `md` and `wp` mode.
`left`	`slot="start"`	Positions element to the `left` of all other elements in `LTR`, and to the `right` in `RTL`.
`right`	`slot="end"`	Positions element to the `right` of all other elements in `LTR`, and to the `left` in `RTL`.

21 KiB Raw Blame History

Breaking Changes

Dynamic Mode

Button

Markup Changed

Attributes Renamed

Chip

Markup Changed

Datetime

Cordova

FAB

Markup Changed

Fixed Content

Icon

Fonts Removed

Property Removed

Input

Item

Markup Changed

Label Required

Attributes Renamed

Item Divider

Label Required

List Header

Label Required

Menu Toggle

Markup Changed

Item Sliding

Markup Changed

Method Renamed

Toolbar

Nav

Method renamed

Option

Markup Changed

Class Changed

Radio

Slot Required

Radio Group

Range

Attributes Renamed

Segment

Select

Text / Typography

Markup Changed

Toolbar

Attributes Renamed

21 KiB

Raw Blame History