Skip to main content

故障排除

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

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

你认为这里应该讨论一个问题吗？让我们知道！

¥Have an issue that you think should be covered here? Let us know!

无法解析组件​

¥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 组件，而 v-model 等 Vue 特有的功能将无法使用。

¥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 lang="ts">
  import { IonButton } from '@ionic/vue';
  import { defineComponent } from 'vue';

  export default defineComponent({
    components: { IonButton },
  });
</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 Component 插槽，与 Vue 2 中使用的插槽不同。不幸的是，两者的 API 非常相似，你的 linter 可能会将两者混淆。

¥The slots that are used in Ionic Vue are Web Component slots, which are different than the slots used in Vue 2. Unfortunately, the APIs for both are very similar, and your linter is likely getting the two confused.

所有 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 linting 规则并忽略任何自定义 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 指南 了解更多信息。

¥To resolve this issue, you will need to turn off Vetur's template validation with vetur.validation.template: false. See the Vetur Linting Guide for more information.

组件上的方法不是函数​

¥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 管理引用方式的限制，我们无法在这里做同样的事情。

¥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 lang="ts">
  import { IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/vue';
  import { defineComponent } from 'vue';

  export default defineComponent({
    components: {
      IonContent,
      IonHeader,
      IonPage,
      IonTitle,
      IonToolbar,
    },
  });
</script>

请参阅 IonPage 文档 了解更多信息。

¥See the IonPage documentation for more information.

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

¥Ionic events bound in JavaScript are not firing

在 JavaScript 中创建事件监听器（即 addEventListener）时，事件名称应写成短横线大小写：

¥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();

这样做是为了与开发者使用 kebab-case 在 Vue 模板中绑定事件的方式保持一致：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

目录