添加到现有的 Vue 项目

本指南介绍了如何将 Ionic Vue 添加到现有的 Vue 项目中。如果你想从头开始创建新项目，请参阅 Ionic Vue 快速入门指南。有关 Ionic Vue 如何与 Vue 配合使用的概述，包括版本支持和工具，请参阅 Ionic Vue 概览。

🌐 This guide covers how to add Ionic Vue to an existing Vue project. If you're looking to start a new project from scratch, check out the Ionic Vue Quickstart guide. For an overview of how Ionic Vue works with Vue, including version support and tooling, check out the Ionic Vue Overview.

tip

本指南使用 JavaScript 示例。如果你使用的是 TypeScript，设置过程相同，但你将使用 .ts 文件扩展名而不是 .js。

🌐 This guide uses JavaScript examples. If you're using TypeScript, the setup process is the same, but you'll use .ts file extensions instead of .js.

设置

🌐 Setup

info

本指南遵循使用 create-vue（使用 Vite）创建的 Vue 应用的结构。如果你使用其他工具（例如 Vue CLI）启动 Vue 应用，你的文件结构和设置可能会有所不同。

🌐 This guide follows the structure of a Vue app created with create-vue (which uses Vite). If you started your Vue app using a different tool (such as Vue CLI), your file structure and setup may differ.

按照以下步骤将 Ionic Vue 添加到你现有的 Vue 项目中：

🌐 Follow these steps to add Ionic Vue to your existing Vue project:

1. 安装软件包

🌐 1. Install the Packages

npm install @ionic/vue @ionic/vue-router vue-router

2. 配置 Ionic Vue

🌐 2. Configure Ionic Vue

更新 src/main.js 以包含 IonicVue 并导入所需的 Ionic Framework 样式表：

🌐 Update src/main.js to include IonicVue and import the required Ionic Framework stylesheets:

src/main.js
import { createApp } from 'vue';
import { IonicVue } from '@ionic/vue';

import App from './App.vue';

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

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

createApp(App).use(IonicVue).mount('#app');

info

虽然需要使用 core.css，但 normalize.css、structure.css 和 typography.css 是推荐使用的，但不是必需的。它们可以统一不同浏览器的差异，确保正确的滚动行为，并提供一致的排版和表单样式。如果不使用它们，你可能需要自己处理这些问题。更多详情，请参阅全局样式表。

🌐 While core.css is required, normalize.css, structure.css, and typography.css are recommended but not required. They normalize cross-browser differences, ensure proper scrolling behavior, and provide consistent typography and form styling. Without them, you may need to handle these concerns yourself. For more details, refer to Global Stylesheets.

使用单个组件

🌐 Using Individual Components

完成上述设置后，你可以在现有的 Vue 应用中开始使用 Ionic 组件。以下是如何使用它们的示例：

🌐 After completing the setup above, you can start using Ionic components in your existing Vue app. Here's an example of how to use them:

将 src/App.vue 更新为以下内容：

🌐 Update src/App.vue to the following:

src/App.vue
<template>
  <ion-button>Button</ion-button>
  <ion-datetime></ion-datetime>
</template>

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

Visit the components page for all of the available Ionic components.

Using Ionic Pages

If you want to use Ionic pages with full navigation and page transitions, follow these additional setup steps.

1. Add Additional Ionic Framework Stylesheets

Update the imported stylesheets in src/main.js:

src/main.js
/* Core CSS required for Ionic components to work properly */
import '@ionic/vue/css/core.css';

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

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

These stylesheets set up the overall page structure and provide CSS utilities for faster development. Some stylesheets are optional. For details on which stylesheets are required, check out Global Stylesheets.

2. Set up Theming

Create a src/theme/variables.css file with the following content:

src/theme/variables.css

/* For information on how to create your own theme, please refer to:
https://ionicframework.com/docs/theming/ */

Then, import the file and the dark palette stylesheet in src/main.js:

src/main.js
import { createApp } from 'vue';
import App from './App.vue';

import { IonicVue } from '@ionic/vue';

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

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

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

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

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

/* Theme variables */
import './theme/variables.css';

createApp(App).use(IonicVue).mount('#app');

The variables.css file can be used to create custom Ionic Framework themes. The dark.system.css import enables dark mode support for your Ionic app when the system is set to prefer a dark appearance. You can customize the theming behavior by uncommenting different dark palette imports or adding custom CSS variables to theme/variables.css.

3. Update the App Component

Update src/App.vue to the following:

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

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

4. Create a Home Page

Create a new file at src/views/HomePage.vue with the following:

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

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

<style scoped>
#container {
  text-align: center;

  position: absolute;
  left: 0;
  right: 0;
  top: 50%;
  transform: translateY(-50%);
}

#container strong {
  font-size: 20px;
  line-height: 26px;
}

#container p {
  font-size: 16px;
  line-height: 22px;

  color: #8c8c8c;

  margin: 0;
}

#container a {
  text-decoration: none;
}
</style>

5. 设置路由

🌐 5. Set up Routing

在 src/router/index.js 添加一个文件来定义路由：

🌐 Add a file at src/router/index.js defining the routes:

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

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

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

export default router;

更新 src/main.js 以包含路由：

🌐 Update src/main.js to include the router:

src/main.js
import { createApp } from 'vue';
import App from './App.vue';
import router from './router';

import { IonicVue } from '@ionic/vue';

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

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

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

/**
 * Ionic Dark Mode
 * -----------------------------------------------------
 * For more info, please refer to:
 * https://ionic.nodejs.cn/theming/dark-mode
 */

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

/* Theme variables */
import './theme/variables.css';

const app = createApp(App).use(IonicVue).use(router);

router.isReady().then(() => {
  app.mount('#app');
});

一切就绪！你的 Ionic Vue 应用现在已配置了完整的 Ionic 页面支持。运行 npm run dev 来启动你的开发服务器并查看你的应用。

🌐 You're all set! Your Ionic Vue app is now configured with full Ionic page support. Run npm run dev to start your development server and view your app.