版本：v6

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/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>Blank</ion-title>
      </ion-toolbar>
    </ion-header>

    <ion-content :fullscreen="true">
      <ion-header collapse="condense">
        <ion-toolbar>
          <ion-title size="large">Blank</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>New</ion-title>
      </ion-toolbar>
    </ion-header>

    <ion-content :fullscreen="true">
      <ion-header collapse="condense">
        <ion-toolbar>
          <ion-title size="large">New</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 的 ref、一个按钮和一些项目：

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 Component
在 Web Component 上调用方法

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

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

在设备上运行

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 组件中 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。