集成 Ionic 框架

此向导将向你展示如何在 Analog 应用里集成 Ionic 框架，这样你就可以在你的 Analog 项目里应用 Ionic 强大的 iOS 以及 Andriod 组件了。

步骤 1: 安装 Ionic 框架

你先要安装 @ionic/angular@latest 包。基于你的包管理器，运行下面命令中的一种：

npm
yarn
pnpm

npm install @ionic/angular@latest

yarn add @ionic/angular@latest

pnpm install @ionic/angular@latest

可选: 安装 Ionic Angular 原理器工具

Ionic 也提供了一系列原理器帮助你按照 Ionic 的结构创建组件。你可以通过安装 @ionic/angular-toolkit 包到你的 devDependencies 来添加。

npm
yarn
pnpm

npm install -D @ionic/angular-toolkit

yarn add -D @ionic/angular-toolkit

pnpm install -D @ionic/angular-toolkit

可选: 安装 Ionicons: Ionic 自定义图标库

Ionic 还提供了一个包括了移动应用所需的超过了 500 个的图标库。你可以通过添加 ionicons 包到你的项目来安装它：

npm
yarn
pnpm

npm install ionicons

yarn add ionicons

pnpm install ionicons

步骤 2: 在你的应用里配置 Ionic 框架

更新你的 vite.config.ts 文件，在 SSR 处理里添加 Ionic 包，把他们添加到 noExternal 列表。如果你安装了 ionicons 包，你可以也加进去。如果你使用 Vitest，把 @ionic/angular 包添加到 inline 以允许 Vitest 能正确构建。

export default defineConfig(({ mode }) => {
  return {
    // ...

    // add these lines
    ssr: {
      noExternal: ['@ionic/**', '@stencil/**', 'ionicons'],
    },

    // ...

    // add these lines if you use Vitest
    test: {
      server: {
        deps: {
          inline: ['@ionic/angular'],
        },
      },
    },
  };
});

在 app.config.ts 里添加 provideIonicAngular 方法和 IonicRouteStrategy 依赖提供者

import { RouteReuseStrategy, provideRouter } from '@angular/router';
import {
  IonicRouteStrategy,
  provideIonicAngular,
} from '@ionic/angular/standalone';

export const appConfig: ApplicationConfig = {
  providers: [
    provideFileRouter(),
    provideClientHydration(),
    provideHttpClient(withFetch()),
    { provide: RouteReuseStrategy, useClass: IonicRouteStrategy },
    provideIonicAngular(),
  ],
};

更新你的 app.component.ts 文件以在模板中设置所需的 Ionic 标签。你可能要查看服务端渲染注意事项因为 Ionic 尚不支持客户端水合

import { Component } from '@angular/core';
import { IonApp, IonRouterOutlet } from '@ionic/angular/standalone';

@Component({
  selector: 'demo-root',
  standalone: true,
  imports: [IonApp, IonRouterOutlet],
  template: `<ion-app><ion-router-outlet></ion-router-outlet></ion-app>`,
})
export class AppComponent {}

重命名 styles.css 为 styles.scss.
设置 vite.config.ts 文件里的 inlineStylesExtension 属性为 'scss'：

export default defineConfig(({ mode }) => {
  return {
    plugins: [
      analog({
        vite: {
          inlineStylesExtension: 'scss',
        },
      }),
    ],
  };
});

更新 index.html 文件并应用 SCSS 文件：

<head>
  <!-- other headers -->
  <link rel="stylesheet" href="/src/styles.scss" />
</head>
<body>
  <!-- content -->
</body>

更新 styles.scss 文件，导入 Ionic 样式并定义你的自定义主题：

/* Core CSS required for Ionic components to work properly */
@import '@ionic/angular/css/core.css';

/* Basic CSS for apps built with Ionic */
@import '@ionic/angular/css/normalize.css';
@import '@ionic/angular/css/structure.css';
@import '@ionic/angular/css/typography.css';
@import '@ionic/angular/css/display.css';

/* Optional CSS utils that can be commented out */
@import '@ionic/angular/css/padding.css';
@import '@ionic/angular/css/float-elements.css';
@import '@ionic/angular/css/text-alignment.css';
@import '@ionic/angular/css/text-transformation.css';
@import '@ionic/angular/css/flex-utils.css';

/**
 * Ionic Dark Mode
 * -----------------------------------------------------
 * For more info, please see:
 * https://ionicframework.com/docs/theming/dark-mode
 */

/* @import "@ionic/angular/css/palettes/dark.always.css"; */
/* @import "@ionic/angular/css/palettes/dark.class.css"; */
@import '@ionic/angular/css/palettes/dark.system.css';

服务端渲染注意事项

Ionic 框架尚不支持 Angular 新的客户端水合, 因为 Angular 不支持带有 web components 的 SSR, 并且当它们受支持时，必须对 Stencil 组件进行一些工作才能启用它。因此目前有三个选项可以解决这个问题:

从 app.config.ts 依赖提供者里移除 provideClientHydration()。

下面的代码移除 Angular 新的客户端水合机制并改为上一个版本，新的版本会导致客户端重渲染时的闪屏现象。

import { RouteReuseStrategy, provideRouter } from '@angular/router';
import {
  IonicRouteStrategy,
  provideIonicAngular,
} from '@ionic/angular/standalone';

export const appConfig: ApplicationConfig = {
  providers: [
    provideFileRouter(),
    //provideClientHydration(), // remove this.
    provideHttpClient(withFetch()),
    { provide: RouteReuseStrategy, useClass: IonicRouteStrategy },
    provideIonicAngular(),
  ],
};

在 ion-app 标签上添加 ngSkipHydration 属性。

这将在 ion-app 元素及其子元素上禁用客户端水合机制，但将继续对其他元素使用客户端水合。这还会导致 Ionic 组件的页面闪，而且对其他元素/组件没有太大帮助，因为对于 Ionic 应用，您的所有 Ionic 组件都存在于 ion-app 标签内。

import { Component } from '@angular/core';
import { IonApp, IonRouterOutlet } from '@ionic/angular/standalone';

@Component({
  selector: 'demo-root',
  standalone: true,
  imports: [IonApp, IonRouterOutlet],
  template: `
    <ion-app ngSkipHydration>
      <ion-router-outlet></ion-router-outlet>
    </ion-app>
  `,
})
export class AppComponent {}

完全禁用 SSR
- 在 vite.config.ts 里禁用 SSR。这将 消除闪烁 但是你将失去 SSR 带来的任何好处。
```
plugins: [
  analog({
    ssr: false,
  }),
],
```

你必须选择一种方案，不然的话你的应用将会抛出运行时错误，就像下面这样：

ERROR Error: NG0500: During hydration Angular expected <ion-toolbar> but found a comment node.

Angular expected this DOM:

  <ion-toolbar color="secondary">…</ion-toolbar>  <-- AT THIS LOCATION
  …


Actual DOM is:

<ion-header _ngcontent-ng-c1775393043="">
  <!--  -->  <-- AT THIS LOCATION
  …
</ion-header>

Note: attributes are only displayed to better represent the DOM but have no effect on hydration mismatches.

To fix this problem:
  * check the "AppComponent" component for hydration-related issues
  * check to see if your template has valid HTML structure
  * or skip hydration by adding the `ngSkipHydration` attribute to its host node in a template

步骤 3: 添加 Capacitor (可选)

Capacitor 将帮助你便捷的开发可以在 iOS 和 Android 设备上运行的 web 原生应用。

步骤 3.1 安装并配置你的 Capacitor 应用

首先，你需要安装 @capacitor/core 和 @capacitor/cli 包。基于你的包管理器，运行下面命令中的一种：

npm
yarn
pnpm

npm install @capacitor/core
npm install -D @capacitor/cli

yarn add @capacitor/core
yarn add -D @capacitor/cli

pnpm install @capacitor/core
pnpm install -D @capacitor/cli

然后你要执行以下命令初始化 Capacitor 项目。这个 CLI 会提供一些选项，从你的 app 名字开始，然后是你的应用包的 ID。

npx cap init

更新 capacitor.config.ts 的 webDir 属性指向 analog 构建的 dist 目录

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.ionic.capacitor',
  appName: 'ionic-capacitor',
  webDir: 'dist/analog/public',
};

export default config;

步骤 3.2 创建你的 Android 和 iOS 项目

基于你想要支持的手机平台，安装 @capacitor/android 和/或 @capacitor/ios 包。

npm
yarn
pnpm

npm install @capacitor/android
npm install @capacitor/ios

yarn add @capacitor/android
yarn add @capacitor/ios

pnpm install @capacitor/android
pnpm install @capacitor/ios

将 Android 和/或 iOS 项目添加到你的应用

npx cap add android
npx cap add ios

将文件同步到你安装的平台

npx cap sync

你可以用下面的命令运行你的应用了

npx cap run android
npx cap run ios

就这样！你成功的在你的 Analog 应用里安装并配置了 Ionic 框架和 Capacitor！

集成 Ionic 框架

步骤 1: 安装 Ionic 框架​

可选: 安装 Ionic Angular 原理器工具​

可选: 安装 Ionicons: Ionic 自定义图标库​

步骤 2: 在你的应用里配置 Ionic 框架​

服务端渲染注意事项​

步骤 3: 添加 Capacitor (可选)​

步骤 3.1 安装并配置你的 Capacitor 应用​

步骤 3.2 创建你的 Android 和 iOS 项目​