版本：v7

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>空白</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>

<!-- ...styles... -->

这将创建一个带有标题和可滚动内容区域的页面。第二个标题显示一个可折叠大标题，当位于内容顶部时显示，然后当向下滚动时收起，以在第一个标题中显示较小的标题。

了解更多

有关 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 样式以及整个应用中一致的布局行为至关重要。

导航到新页面

要导航到新页面，请先在其路由中创建路由，在 HomePage 导入之后，在 router/index.ts 的顶部导入它：

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 组件
在 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 组件的 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。