版本：v8

Ionic Vue 快速入门

欢迎！本指南将引导您了解 Ionic Vue 开发的基础知识。您将学习如何设置开发环境、生成一个简单的项目、探索项目结构，并理解 Ionic 组件的工作原理。这对于在构建第一个真实应用之前熟悉 Ionic Vue 来说是完美的。

如果您想了解 Ionic Vue 是什么以及它如何融入 Vue 生态系统的高层次概述，请参见 Ionic Vue 概述。

先决条件

开始之前，请确保您的计算机上已安装 Node.js 和 npm。您可以运行以下命令来检查：

node -v
npm -v

如果您没有 Node.js 和 npm，请在此处下载 Node.js（其中包含 npm）。

使用 Ionic CLI 创建项目

首先，安装最新的 Ionic CLI：

npm install -g @ionic/cli

然后，运行以下命令来创建并运行一个新项目：

ionic start myApp blank --type vue

cd myApp
ionic serve

运行 ionic serve 后，您的项目将在浏览器中打开。

Ionic Vue 主页截图

探索项目结构

您新应用的目录结构如下：

└── src/
    ├── App.vue
    ├── main.ts
    ├── router
    │   └── index.ts
    └── views
       └── HomePage.vue

信息

以下示例中的所有文件路径都是相对于项目根目录的。

让我们逐一查看这些文件，以了解应用的结构。

查看应用根组件

应用根组件定义在 App.vue 中：

src/App.vue
<template>
  <ion-app>
    <ion-router-outlet />
  </ion-app>
</template>

<script setup lang="ts">
import { IonApp, IonRouterOutlet } from '@ionic/vue';
</script>

这设置了应用的根组件，使用了 Ionic 的 ion-app 和 ion-router-outlet 组件。路由出口（router outlet）是您的页面将要显示的地方。

查看路由

路由定义在 router/index.ts 中：

src/router/index.ts
import { createRouter, createWebHistory } from '@ionic/vue-router';
import { RouteRecordRaw } from 'vue-router';
import HomePage from '../views/HomePage.vue';

const routes: Array<RouteRecordRaw> = [
  {
    path: '/',
    redirect: '/home',
  },
  {
    path: '/home',
    name: 'Home',
    component: HomePage,
  },
];

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes,
});

export default router;

当您访问根 URL (/) 时，将加载 HomePage 组件。

查看主页

主页组件定义在 HomePage.vue 中，它导入 Ionic 组件并定义页面模板：

src/views/HomePage.vue
<template>
  <ion-page>
    <ion-header :translucent="true">
      <ion-toolbar>
        <ion-title>空白</ion-title>
      </ion-toolbar>
    </ion-header>

    <ion-content :fullscreen="true">
      <ion-header collapse="condense">
        <ion-toolbar>
          <ion-title size="large">空白</ion-title>
        </ion-toolbar>
      </ion-header>

      <div id="container">
        <strong>准备好创建应用了吗？</strong>
        <p>
          从 Ionic
          <a target="_blank" rel="noopener noreferrer" href="https://ionicframework.com/docs/components"
            >UI 组件</a
          >
          开始
        </p>
      </div>
    </ion-content>
  </ion-page>
</template>

<script setup lang="ts">
import { IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/vue';
</script>

<!-- ...样式... -->

这创建了一个带有头部和可滚动内容区域的页面。第二个头部显示一个可折叠大标题，当位于内容顶部时显示，向下滚动时则缩合为第一个头部中显示的小标题。

了解更多

有关 Ionic 布局组件的详细信息，请参阅 Header、Toolbar、Title 和 Content 文档。

添加 Ionic 组件

您可以使用更多 Ionic UI 组件来增强主页。例如，在 ion-content 的末尾添加一个按钮：

src/views/HomePage.vue
<ion-content>
  <!-- 现有内容 -->

  <ion-button>导航</ion-button>
</ion-content>

然后，在 <script> 标签中导入 IonButton 组件：

src/views/HomePage.vue
<script setup lang="ts">
import { IonButton, IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/vue';
</script>

添加新页面

在 NewPage.vue 创建一个新页面：

src/views/NewPage.vue
<template>
  <ion-page>
    <ion-header :translucent="true">
      <ion-toolbar>
        <ion-buttons slot="start">
          <ion-back-button default-href="/"></ion-back-button>
        </ion-buttons>
        <ion-title>新页面</ion-title>
      </ion-toolbar>
    </ion-header>

    <ion-content :fullscreen="true">
      <ion-header collapse="condense">
        <ion-toolbar>
          <ion-title size="large">新页面</ion-title>
        </ion-toolbar>
      </ion-header>
    </ion-content>
  </ion-page>
</template>

<script setup lang="ts">
import { IonBackButton, IonButtons, IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/vue';
</script>

这将创建一个在工具栏中带有返回按钮的页面。返回按钮将自动处理导航回上一页，如果没有历史记录则导航到 /。

注意

创建自己的页面时，请始终将 ion-page 作为根组件。这对于页面之间的正确过渡、Ionic 组件依赖的基础 CSS 样式以及应用中一致的布局行为至关重要。

导航到新页面

要导航到新页面，首先在 router/index.ts 的顶部（在 HomePage 导入之后）导入它：

src/router/index.ts
import NewPage from '../views/NewPage.vue';

然后，在 routes 数组中添加其路由：

src/router/index.ts
const routes: Array<RouteRecordRaw> = [
  {
    path: '/',
    redirect: '/home',
  },
  {
    path: '/home',
    name: 'Home',
    component: HomePage,
  },
  {
    path: '/new',
    name: 'New',
    component: NewPage,
  },
];

完成后，更新 HomePage.vue 中的按钮：

src/views/HomePage.vue
<ion-button router-link="/new">导航</ion-button>

信息

导航也可以使用 Vue Router 以编程方式执行，并且可以懒加载路由以获得更好的性能。更多信息请参见 Vue 导航文档。

向新页面添加图标

Ionic Vue 预装了 Ionicons。您可以通过设置 ion-icon 组件的 icon 属性来使用任何图标。

更新 NewPage.vue 中的导入，以导入 IonIcon 以及 heart 和 logoIonic 图标：

src/views/NewPage.vue
<script setup lang="ts">
import { IonBackButton, IonButtons, IonContent, IonHeader, IonIcon, IonPage, IonTitle, IonToolbar } from '@ionic/vue';
import { heart, logoIonic } from 'ionicons/icons';
</script>

然后，将它们包含在 ion-content 内部：

src/views/NewPage.vue
<ion-icon :icon="heart"></ion-icon>
<ion-icon :icon="logoIonic"></ion-icon>

请注意，我们传递的是导入的 SVG 引用，而不是字符串形式的图标名称。

更多信息，请参阅图标文档和 Ionicons 文档。

调用组件方法

让我们添加一个可以滚动内容区域到底部的按钮。

更新 NewPage.vue，在 ion-content 上添加一个引用，并在现有图标之后添加一个按钮和一些项目：

src/views/NewPage.vue
<ion-content ref="content">
  <ion-button @click="scrollToBottom">滚动到底部</ion-button>

  <!-- 添加大量内容以便滚动 -->
  <ion-item v-for="i in 50" :key="i">
    <ion-label>项目 {{ i }}</ion-label>
  </ion-item>
</ion-content>

在脚本部分，添加新的组件导入并定义 scrollToBottom 函数：

src/views/NewPage.vue
<script setup lang="ts">
import {
  IonBackButton,
  IonButtons,
  IonButton,
  IonContent,
  IonHeader,
  IonIcon,
  IonItem,
  IonLabel,
  IonPage,
  IonTitle,
  IonToolbar,
} from '@ionic/vue';
import { heart, logoIonic } from 'ionicons/icons';
import { ref } from 'vue';

const content = ref();

const scrollToBottom = () => {
  content.value.$el.scrollToBottom(300);
};
</script>

要调用 Ionic 组件的方法：

为组件创建一个 ref
通过 $el 访问底层的 Web 组件
在 Web 组件上调用方法

这种模式是必要的，因为 Ionic 组件是作为 Web 组件构建的。$el 属性让您可以访问实际定义方法的 Web 组件实例。

您可以在每个组件的 API 文档的方法部分找到可用的方法。

在设备上运行

Ionic 的组件在所有地方都能工作：iOS、Android 和 PWA。要部署到移动设备，请使用 Capacitor：

ionic build
ionic cap add ios
ionic cap add android

在各自的 IDE 中打开原生项目：

ionic cap open ios
ionic cap open android

更多信息请参见 Capacitor 入门指南。

使用 TypeScript 或 JavaScript 构建

Ionic Vue 项目默认使用 TypeScript 创建，但如果您愿意，可以轻松转换为 JavaScript。生成空白 Ionic Vue 应用后，请按照以下步骤操作：

移除 TypeScript 依赖项：

npm uninstall --save typescript @types/jest @typescript-eslint/eslint-plugin @typescript-eslint/parser @vue/cli-plugin-typescript @vue/eslint-config-typescript vue-tsc

将所有 .ts 文件的扩展名更改为 .js。在空白 Ionic Vue 应用中，这将是 src/router/index.ts、src/main.ts 和 tests 目录中的文件。
在 index.html 中，将导入的 <script> 文件从 /src/main.ts 更改为 /src/main.js。
从 .eslintrc.js 中移除 @vue/typescript/recommended 和 @typescript-eslint/no-explicit-any: 'off'。
从 src/router/index.js 中移除 Array<RouteRecordRaw> 和 RouteRecordRaw 的导入。
从您的 Vue 组件中任何带有 lang="ts" 的 script 标签中移除 lang="ts"。在空白 Ionic Vue 应用中，这应该只是 src/App.vue 和 src/views/HomePage.vue。
删除 tsconfig.json 和 vite-env.d.ts。
在 package.json 中，将构建脚本从 "build": "vue-tsc && vite build" 更改为 "build": "vite build"。
安装 terser：npm i -D terser。