Ionic Vue 快速入门
欢迎！本指南将带你了解 Ionic Vue 开发的基础知识。你将学习如何设置开发环境、生成一个简单的项目、探索项目结构，以及理解 Ionic 组件的工作原理。这对于在构建你的第一个真实应用之前熟悉 Ionic Vue 非常适合。
🌐 Welcome! This guide will walk you through the basics of Ionic Vue development. You'll learn how to set up your development environment, generate a simple project, explore the project structure, and understand how Ionic components work. This is perfect for getting familiar with Ionic Vue before building your first real app.
如果你想要了解 Ionic Vue 是什么以及它如何融入 Vue 生态系统的高级概述，请参见 Ionic Vue 概述。
🌐 If you're looking for a high-level overview of what Ionic Vue is and how it fits into the Vue ecosystem, see the Ionic Vue Overview.
先决条件
🌐 Prerequisites
在开始之前，确保你的计算机上已安装 Node.js 和 npm。你可以通过运行以下命令来检查：
🌐 Before you begin, make sure you have Node.js and npm installed on your machine. You can check by running:
node -v
npm -v
如果你没有 Node.js 和 npm，请在此下载 Node.js（其中包含 npm）。
🌐 If you don't have Node.js and npm, download Node.js here (which includes npm).
使用 Ionic CLI 创建项目
🌐 Create a Project with the Ionic CLI
首先，安装最新的 Ionic CLI ：
🌐 First, install the latest Ionic CLI:
npm install -g @ionic/cli
然后，运行以下命令来创建并运行一个新项目：
🌐 Then, run the following commands to create and run a new project:
ionic start myApp blank --type vue
cd myApp
ionic serve
运行 ionic serve 后，你的项目将在浏览器中打开。
🌐 After running ionic serve, your project will open in the browser.
探索项目结构
🌐 Explore the Project Structure
你的新应用的目录将如下所示：
🌐 Your new app's directory will look like this:
└── src/
├── App.vue
├── main.ts
├── router
│ └── index.ts
└── views
└── HomePage.vue
下面示例中的所有文件路径都是相对于项目根目录的。
让我们浏览这些文件来了解应用的结构。
🌐 Let's walk through these files to understand the app's structure.
查看应用组件
🌐 View the App Component
你的应用的根目录定义在 App.vue 中：
🌐 The root of your app is defined in App.vue:
<template>
<ion-app>
<ion-router-outlet />
</ion-app>
</template>
<script setup lang="ts">
import { IonApp, IonRouterOutlet } from '@ionic/vue';
</script>
This sets up the root of your application, using Ionic's ion-app and ion-router-outlet components. The router outlet is where your pages will be displayed.
View Routes
Routes are defined in 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;
When you visit the root URL (/), the HomePage component will be loaded.
View the Home Page
The Home page component, defined in HomePage.vue, imports the Ionic components and defines the page template:
<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>Ready to create an app?</strong>
<p>
Start with Ionic
<a target="_blank" rel="noopener noreferrer" href="https://ionicframework.com/docs/components"
>UI Components</a
>
</p>
</div>
</ion-content>
</ion-page>
</template>
<script setup lang="ts">
import { IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/vue';
</script>
这会创建一个带有标题和可滚动内容区域的页面。第二个标题显示一个可折叠的大标题，当内容位于顶部时显示，然后在向下滚动时收缩以在第一个标题中显示较小的标题。
🌐 This creates a page with a header and scrollable content area. The second header shows a collapsible large title that displays when at the top of the content, then condenses to show the smaller title in the first header when scrolling down.
添加一个 Ionic 组件
🌐 Add an Ionic Component
你可以通过添加更多 Ionic UI 组件来增强你的主页。例如，在 ion-content 的末尾添加一个 按钮：
🌐 You can enhance your Home page with more Ionic UI components. For example, add a Button at the end of the ion-content:
<ion-content>
<ion-button>Navigate</ion-button>
</ion-content>
然后，在 <script> 标签中导入 IonButton 组件：
🌐 Then, import the IonButton component in the <script> tag:
<script setup lang="ts">
import { IonButton, IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/vue';
</script>
添加新页面
🌐 Add a New Page
在 NewPage.vue 创建一个新页面：
🌐 Create a new page at 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>
这将创建一个带有 返回按钮 的页面，该按钮位于 工具栏 中。返回按钮将自动处理返回到上一页的导航，如果没有历史记录，则返回到 /。
🌐 This creates a page with a Back Button in the Toolbar. The back button will automatically handle navigation back to the previous page, or to / if there is no history.
在创建自己的页面时，始终使用 ion-page 作为根组件。这对于页面之间的正确过渡、Ionic 组件依赖的基础 CSS 样式以及应用内一致的布局行为都是必不可少的。
导航到新页面
🌐 Navigate to the New Page
要导航到新页面，请为其创建一个路由，首先在 HomePage 导入之后，在 router/index.ts 顶部导入它：
🌐 To navigate to the new page, create a route for it by first importing it at the top of router/index.ts after the HomePage import:
import NewPage from '../views/NewPage.vue';
然后，将它的路由添加到 routes 数组中：
🌐 Then, add its route in the routes array:
const routes: Array<RouteRecordRaw> = [
{
path: '/',
redirect: '/home',
},
{
path: '/home',
name: 'Home',
component: HomePage,
},
{
path: '/new',
name: 'New',
component: NewPage,
},
];
完成后，更新 HomePage.vue 中的按钮：
🌐 Once that is done, update the button in HomePage.vue:
<ion-button router-link="/new">Navigate</ion-button>
导航也可以使用 Vue Router 以编程方式执行，并且路由可以进行懒加载以提高性能。有关更多信息，请参阅 Vue 导航文档。
将图标添加到新页面
🌐 Add Icons to the New Page
Ionic Vue 自带 Ionicons。你可以通过设置 ion-icon 组件的 icon 属性来使用任何图标。
🌐 Ionic Vue comes with Ionicons pre-installed. You can use any icon by setting the icon property of the ion-icon component.
更新 NewPage.vue 中的导入，以导入 IonIcon 以及 heart 和 logoIonic 图标：
🌐 Update the imports in NewPage.vue to import IonIcon and the heart and logoIonic icons:
<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 内：
🌐 Then, include them inside of the ion-content:
<ion-icon :icon="heart"></ion-icon>
<ion-icon :icon="logoIonic"></ion-icon>
请注意，我们传递的是导入的 SVG 引用，而不是作为字符串的图标名称。
🌐 Note that we are passing the imported SVG reference, not the icon name as a string.
欲了解更多信息，请参阅 Icon 文档 和 Ionicons 文档。
🌐 For more information, see the Icon documentation and the Ionicons documentation.
调用组件方法
🌐 Call Component Methods
让我们添加一个可以将内容区域滚动到底部的按钮。
🌐 Let's add a button that can scroll the content area to the bottom.
更新 NewPage.vue 以包含对 ion-content 的引用，以及在现有图标之后添加一个按钮和一些项目：
🌐 Update NewPage.vue to include a ref on ion-content and a button and some items after the existing icons:
<ion-content ref="content">
<ion-button @click="scrollToBottom">Scroll to Bottom</ion-button>
<ion-item v-for="i in 50" :key="i">
<ion-label>Item {{ i }}</ion-label>
</ion-item>
</ion-content>
在脚本部分，添加新的组件导入并定义 scrollToBottom 函数：
🌐 In the script section, add the new component imports and define the scrollToBottom function:
<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 组件的方法：
🌐 To call methods on Ionic components:
- 为组件创建一个
ref - 通过
$el访问底层网页组件 - 在 Web 组件上调用方法
这个模式是必要的，因为 Ionic 组件是作为 Web 组件构建的。$el 属性让你可以访问实际的 Web 组件实例，其中定义了这些方法。
🌐 This pattern is necessary because Ionic components are built as Web Components. The $el property gives you access to the actual Web Component instance where the methods are defined.
你可以在它们的 API 文档的 方法 部分找到每个组件的可用方法。
🌐 You can find available methods for each component in the Methods section of their API documentation.
在设备上运行
🌐 Run on a Device
Ionic 的组件无处不在：在 iOS、Android 和 PWA 上都能使用。要部署到移动端，请使用 Capacitor：
🌐 Ionic's components work everywhere: on iOS, Android, and PWAs. To deploy to mobile, use Capacitor:
ionic build
ionic cap add ios
ionic cap add android
在它们的 IDE 中打开本地项目：
🌐 Open the native projects in their IDEs:
ionic cap open ios
ionic cap open android
更多信息请参阅 电容器入门指南。
🌐 See Capacitor's Getting Started guide for more.
使用 TypeScript 或 JavaScript 构建
🌐 Build with TypeScript or JavaScript
Ionic Vue 项目默认使用 TypeScript 创建，但如果你愿意，可以轻松转换为 JavaScript。在生成一个空的 Ionic Vue 应用后，按照以下步骤操作：
🌐 Ionic Vue projects are created with TypeScript by default, but you can easily convert to JavaScript if you prefer. After generating a blank Ionic Vue app, follow these steps:
- 移除 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。
探索更多
🌐 Explore More
本指南涵盖了创建 Ionic Vue 应用、添加导航以及引入 Capacitor 用于原生构建的基础知识。要深入了解，请查看：
🌐 This guide covered the basics of creating an Ionic Vue app, adding navigation, and introducing Capacitor for native builds. To dive deeper, check out:
使用 Ionic Vue 和原生设备功能构建一个真正的照片图库应用。
从官方 Vue 文档了解更多关于 Vue 核心概念、工具和最佳实践的信息。
了解如何在 Ionic Vue 应用中使用 Vue Router 处理路由和导航。
探索 Ionic 丰富的 UI 组件库，用于构建美观的应用。
了解如何使用 Ionic 强大的主题系统自定义应用的外观和感觉。
探索如何访问本地设备功能，并使用 Capacitor 将你的应用部署到 iOS、Android 和网络。