La migración entre estos 2 Frameworks requiere de algunas actualizaciones de las propiedades de la API, las utilidades CSS y las dependencias del paquete instalado.

Actualizaciones de la API y CSS

Para consultar los cambios entre la versión 4 y la 5 podemos consultar la documentación que nos facilita Ionic pulsando aquí.

Utilidades CSS

Originalmente el Equipo de Ionic añadió atributos de utilidad CSS para los componentes de estilo porque era una forma rápida y fácil de ajustar texto o agregar relleno a un elemento. Pero pronto vieron que había problemas con el uso de atributos CSS con marcos que usan JSX y Typecript. Para resolver esto, añadieron clases CSS en lugar de admitir los atributos CSS en unos marcos y clases en otros marcos. Finalmente eliminaron los atributos CSS y dejaron solo las clases, para mantener la coherencia.

Algunos ejemplos de lo que ha cambiado están a continuación. Esto no incluye todo, consulte la documentación vinculada aquí para ver todas las clases de utilidades CSS disponibles.

Antes

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

Ahora

<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>

Clases de visualización Responsive

Las clases responsive que se encuentran en el archivo display.css han actualizado sus consultas de medios para reflejar mejor cómo deberían funcionar. En lugar de usar el valor máximo del punto de interrupción para las clases .ion-hide- {breakpoint} -down, usará el mínimo de ese punto de interrupción.

Anteriormente, si agregaba la clase ion-hide-md-down a un elemento, ocultaría el elemento cuando el tamaño de la pantalla fuera 991px (el máximo del punto de ruptura md) o menor. Ahora, usar esta misma clase ocultará el elemento cuando el tamaño máximo de pantalla sea de 768 px

A continuación se muestra una tabla de cómo han cambiado las consultas de medios para cada clase:

Estados Activated, Focused y Hover

La clase .activated que se agrega automáticamente a los componentes en los que se puede hacer clic ha cambiado su nombre a .ion-enabled.

La forma en que se usan las variables CSS para apuntar a los fondos activated, focused y hover se ha actualizado en los siguientes componentes:

• Action Sheet
• Back Button
• Button
• FAB Button
• Item
• Menu Button
• Segment Button
• Tab Button

Anteriormente, para actualizar cualquiera de los colores de fondo para los estados en los que tendrías que saber para qué se configuró la opacidad. Usando las especificaciones de Material Design como ejemplo, requeriría que sepa que el estado de desplazamiento utiliza una superposición blanca con una opacidad de .08. Esto significa que si tuviéramos el siguiente conjunto por defecto:

–background-hover: rgba(255, 255, 255, 0.08);

Si desea cambiar la superposición de desplazamiento para usar negro pero aún coincide con la especificación, tendría que configurarlo en:

– fondo-hover : rgba ( 0 , 0 , 0 , 0.08 );

La nueva forma agrega las siguientes variables:

--background-activated-opacity 
--background-focused-opacity 
--background-hover-opacity 

También actualiza el componente Action Sheet para que las variables tengan como prefijo el button.

Esto le permite seguir teniendo control sobre la opacidad si lo desea, pero al actualizar el estado, solo tiene que establecer las variables principales:
–background-activated, –background-focused, –background-hover y el botón seguirá coincidiendo con la especificación. Esto es más importante cuando se cambia el tema global, ya que la actualización del color de la barra de herramientas actualizará automáticamente los estados de desplazamiento de todos los botones en una barra de herramientas, independientemente de su relleno y sin tener que saber cuál es cada opacidad.

Ejemplos

/* Setting the button background on hover to solid red */
ion-button {
  --background-hover: red;
  --background-hover-opacity: 1;
}

/* Setting the action sheet button background on focus to an opaque green */
ion-action-sheet {
  --button-background-focus: green;
  --button-background-focus-opacity: 0.5;
}

/*
 * Setting the fab button background on hover to match the text color with
 * the default --background-hover-opacity on md
 */
.md ion-fab-button {
  --color: #222;
  --background-hover: #222;
}

Propiedades CSS Globales

Algunas variables fueron renombradas, eliminadas o agregadas. Consulte la tabla a continuación para ver los cambios.

Sass

Los archivos scss han sido eliminados de dist/. Las variables CSS deberían usarse en su lugar.

Componentes

Action Sheet

Las siguietes variables han sido renombradas o añadidas

Anchor

El componente ion-anchor ha sido renombrado como ion-router-link, ya que esta es una mejor descripción de con qué componente debe usarse. Este componente solo debe usarse en proyectos vanilla y Stencil JavaScript. Los proyectos de angular deben usar un <a> y routerLink con el enrutador de Angular.

Back Button

El botón de retroceso se ha modificado para usar Shadow DOM que en la actualidad está soportado por Firefox (63 en adelante), Chrome, Opera, Safari y Edge que está trabajando en una implementación.

Button

Los estados Activated, Focused y Hover han sido actualizados.

Card

Se ha modificado ion-card para usar Shadow DOM

Controllers

Los componentes del controlador (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) se han eliminado del núcleo dew Ionic como elementos. Deben importarse de @ionic/core en su lugar. Esto no afectará a los proyectos que usan Angular o React. A continuación se muestra un ejemplo del cambio del controlador de carga en un proyecto de JavaScript, pero este cambio se aplica a todos los elementos del controlador.

Antes

<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>

Después

<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>

FAB Button

Los estados Activated, Focused y Hover han sido actualizados.

Item

Los estados Activated, Focused y Hover han sido actualizados.

Header / Footer

El atributo no-border se ha eliminado, debemos usar ion-no-border en su lugar.

List Header

El list header se ha rediseñado para que coincida con la última especificación de iOS. Esto puede romper el diseño de la aplicación ya que el diseño anterior tenía un tamaño de fuente pequeño con texto en mayúscula. El último diseño incluye un texto más grande. Además, cualquier contenido de texto dentro de un <ion-list-header> debe estar envuelto en un <ion-label> para obtener el estilo adecuado del nuevo diseño. Si falta la etiqueta, la alineación del botón en el encabezado de la lista puede desviarse.

Antes

<ion-list-header>
  New This Week
  <ion-button>See All</ion-button>
</ion-list-header>

Después

<ion-list-header>
  <ion-label>New This Week</ion-label>
  <ion-button>See All</ion-button>
</ion-list-header>

El botón también se actualizó por defecto a fill = «clear» y size = «small» cuando está dentro del list header. Si queremos el aspecto anterior del encabezado o botones del list header, hay que usar CSS personalizado o propiedades de botones para lograrlo.

Menu

La función swipeEnable() se ha eliminado en Angular, hay que usar swipeGesture() en su lugar.
Se han eliminado los valores de side (left y right); en su lugar, hay que usar start y end.
Se ha eliminado el atributo main, hay que utilizar content-id (para vanilla JS / Vue) y contentId (para Angular / React) en su lugar.

Antes

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

Después

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

Menu Button

Los estados Focused y Hover han sido actualizados

Nav Link

Los componentes ion-nav-push, ion-nav-back y ion-nav-set-root se han eliminado a favor del uso de ion-nav-link con una propiedad router-direction que acepta «root», «forward», y «atrás». Esto reduce la necesidad de mantener múltiples componentes cuando todos hacen lo mismo con diferentes direcciones de transición.

Radio

El ion-radio debe usarse dentro de un grupo ion-radio-group incluso si solo hay un ion-radio. Además, la propiedad checked ha sido eliminada. Debemos establecer la propiedad de value en el ion-radio-group principal para que coincida con el value del radio button seleccionado. ion-radio ya no emite un evento ionSelect. Debemos escuchar si se emite un evento ionChange en ion-radio-group.

Antes

<ion-radio checked>One</ion-radio>

<ion-radio-group>
  <ion-radio>One</ion-radio>
  <ion-radio checked>Two</ion-radio>
</ion-radio-group>

Después

<ion-radio-group value="one">
  <ion-radio value="one">One</ion-radio>
</ion-radio-group>

<ion-radio-group value="two">
  <ion-radio value="one">One</ion-radio>
  <ion-radio value="two">Two</ion-radio>
</ion-radio-group>

Searchbar

La propiedad show-cancel-button de la barra de búsqueda ya no acepta valores booleanos. Los valores aceptados son cadenas: «focus», «always», «never».

Antes

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

Después

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

La propiedad inputmode para ion-searchbar ahora es por defecto undefined. Para obtener el comportamiento anterior, hay que establecer la propiedad inputmode en «search».

Segment

Segment se renovó por completo para usar el nuevo diseño de iOS, incluido un gesto completamente nuevo que se aplica tanto para Material Design como para iOS. Debido a estos cambios, inevitablemente se introdujeron algunos cambios importantes para respaldar el nuevo diseño.

Eventos renombrados
ion-segment ya no emite un evento ionSelect. Debemos escuchar si se emite un evento ionChange en el ion-segment.

Estados del botón
Se han eliminado los activaded styles y las propiedades CSS personalizadas. Estos ya no se usan en la última especificación, ya que el indicador se usa para mostrar la activación.

Propiedades eliminadas:
–color-activated
–background-activated

Los estados Focused y Hover han sido actualizados.

Indicador Color
–indicator-color ahora se aplica al botón de segmento marcado (tanto para ios como para Material Design).
–indicator-color-checked ha sido eliminado.
La especificación de Material Design no incluye un color indicador en botones no marcados.
Para diseñar Segment y que coincida con la especificación anterior, hay que utilizar CSS personalizado. Por ejemplo, para actualizar Material Design para incluir una línea de fondo todo el tiempo:

.md ion-segment::after {
    position: absolute;
    bottom: 0;
    height: 2px;
    width: 100%;
    content: '';
    background: rgba(0,0,0,0.5);
    z-index: -1;
}

Background y Color
Se ha agregado una variable –background para diseñar el componente ion-segment. Como resultado de esto, las siguientes variables de background para un segment button ahora deben establecerse en el ion-segment-button:
— background: Fondo del segment button
— background-checked: Fondo del botón para un segment button seleccionado.
— background-disabled: Fondo del botón para un segment button deshabilitado
–background-hover: Fondo del botón para un segment button al pasar el mouse.

Nota: iOS ya no verifica el fondo del botón, por lo que configurar la variable –background-checked puede tener un resultado no deseado. En cambio, Segment usa un indicador para deslizarse entre los botones, mostrando cuál está marcado.

Las variables anteriores no se heredarán en el botón si se configuran en el ion-segment. Además de esto, todas las variables de color también deben configurarse en el botón para mantener la coherencia:
–color: Color del segment button.
–color-check: Color del segment button marcado.
–color-disabled: Color del segment button deshabilitado.
–color-hover: Color del segment button al pasar el mouse.

Segment Button

Select Option

Skeleton Text

Tabs

Toast

Colors

Events

Mode

Ionicons

Cambios en paquetes y dependencias

Para proyectos Angular
npm install @ionic/angular@latest @ionic/angular-toolkit@latest –save

Para proyectos React
npm install @ionic/react@latest @ionic/react-router@latest ionicons@latest