Skip to main content

故障排除

本指南涵盖了使用 Ionic Vue 开发时可能遇到的一些更常见的问题。

🌐 This guide covers some of the more common issues you may run into when developing with Ionic Vue.

有你认为应该在这里讨论的问题吗？ 告诉我们吧！

无法解析组件​

🌐 Failed to resolve component

[Vue warn]: Failed to resolve component: ion-button

如果你看到此警告，那么很可能是因为你没有从 @ionic/vue 导入你的组件。默认情况下，所有的 Ionic Vue 组件都是局部注册的，这意味着每次你想使用它们时都需要导入它们。

🌐 If you see this warning, then it is likely you did not import your component from @ionic/vue. By default, all Ionic Vue components are locally registered, meaning you need to import them each time you want to use them.

如果不导入该组件，你将只能获得底层的 Web 组件，而 Vue 特有的功能如 v-model 将无法使用。

🌐 Without importing the component, you will only get the underlying Web Component, and Vue-specific features such as v-model will not work.

要解决此问题，你需要从 @ionic/vue 导入组件并将其提供给你的 Vue 组件：

🌐 To resolve this issue, you need to import the component from @ionic/vue and provide it to your Vue component:

<template>
  <ion-button>Hello World</ion-button>
</template>

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

想一次性将组件全局注册？我们为你提供了方案。我们的优化构建指南向你展示了如何全局注册 Ionic Vue 组件，以及使用这种方法时需要注意的潜在缺点。

🌐 Prefer to register your components globally once? We have you covered. Our Optimizing Your Build Guide shows you how to register Ionic Vue components globally as well as the potential downsides to be aware of when using this approach.

插槽属性已弃用​

🌐 Slot attributes are deprecated

`slot` attributes are deprecated  vue/no-deprecated-slot-attribute

在 Ionic Vue 中使用的插槽是 Web 组件插槽，这与 Vue 2 中使用的插槽不同。不幸的是，两者的 API 非常相似，你的代码检查工具很可能会将它们混淆。

所有 Ionic Vue 入门项目默认关闭此规则，但你可以通过在你的 .eslintrc.js 文件中添加以下内容来自己启用它：

🌐 All Ionic Vue starters ship with this rule turned off, but you can do it yourself by adding the following to your .eslintrc.js file:

module.exports = {
  rules: {
    'vue/no-deprecated-slot-attribute': 'off',
  },
};

如果你正在使用 VSCode 并且安装了 Vetur 插件，你很可能收到这个警告是因为 Vetur，而不是 ESLint。默认情况下，Vetur 会加载默认的 Vue 3 规则，并忽略任何自定义 ESLint 规则。

🌐 If you are using VSCode and have the Vetur plugin installed, you are likely getting this warning because of Vetur, not ESLint. By default, Vetur loads the default Vue 3 linting rules and ignores any custom ESLint rules.

要解决此问题，你需要使用 vetur.validation.template: false 关闭 Vetur 的模板验证。更多信息请参见 Vetur Linting 指南 。

组件上的方法不是函数​

🌐 Method on component is not a function

为了访问 Vue 中 Ionic Framework 组件的方法，你需要首先访问底层 Web 组件实例：

🌐 In order to access a method on an Ionic Framework component in Vue, you will need to access the underlying Web Component instance first:

// ✅ This is correct
ionContentRef.value.$el.scrollToBottom();

// ❌ This is incorrect and will result in an error.
ionContentRef.value.scrollToBottom();

在其他框架集成中，例如 Ionic React，这不是必需的，因为你提供的任何 ref 会自动转发到底层的 Web 组件实例。由于 Vue 管理 refs 的方式存在限制，我们无法在这里做同样的事情。

🌐 In other framework integrations such as Ionic React, this is not needed as any ref you provide is automatically forwarded to the underlying Web Component instance. We are unable to do the same thing here due to limitations in how Vue manages refs.

有关更多信息，请参见快速入门指南。

🌐 See the Quickstart Guide for more information.

页面转换不起作用​

🌐 Page transitions are not working

为了使页面切换正常工作，每个页面的根部必须有一个 ion-page 组件：

🌐 In order for page transitions to work correctly, each page must have an ion-page component at the root:

<template>
  <ion-page>
    <ion-header>
      <ion-toolbar>
        <ion-title>Home</ion-title>
      </ion-toolbar>
    </ion-header>
    <ion-content class="ion-padding">Hello World</ion-content>
  </ion-page>
</template>

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

有关更多信息，请参见 IonPage 文档。

🌐 See the IonPage documentation for more information.

JavaScript 中绑定的 Ionic 事件不会触发​

🌐 Ionic events bound in JavaScript are not firing

在 JavaScript 中创建事件监听器时（即 addEventListener），事件名称应以 kebab-case 形式书写：

🌐 When creating event listeners in JavaScript (i.e. addEventListener), event names should be written as kebab-case:

const modal = await modalController.create({
  component: Modal
});

modal.addEventListener('ion-modal-did-present', () => {
  ...
});

await modal.present();

这样做是为了与开发者在 Vue 模板中使用 kebab-case 绑定事件的方式保持一致：https://vuejs.org/guide/essentials/component-basics.html#case-insensitivity

🌐 This is done to align with how developers bind events in their Vue templates by using kebab-case: https://vuejs.org/guide/essentials/component-basics.html#case-insensitivity

目录