【Uni-App】嵌入悬浮球全局组件的详细教程和防踩坑点

十八朵郁金香

已于 2025-04-06 22:28:00 修改

阅读量1.3k

点赞数 17

CC 4.0 BY-SA版权

文章标签： uni-app

于 2025-03-28 17:25:22 首次发布

本文链接：https://blog.csdn.net/orbit4/article/details/146605244

一、前言

近期接到一个业务需求是为为h5页面嵌入悬浮球，而且还得是全局化（这样所有页面就可以看见了），在开发的过程中也遇到一些坑，在此和大家一起学习、讨论。

二、准备工作

下载悬浮球组件代码

悬浮球 - DCloud 插件市场

我用的是这一个插件：自由拖拽，吸附在屏幕两侧。

三、实现步骤

1、将组件代码写到项目中。

注意点：这一步主要引入悬浮组件和素材资源

2、全局注册和使用

全局注册 main.js

引入悬浮球组件和全局注册

全局使用 App.vue

<template>
  <view id="app">
    <!-- 悬浮球组件 -->
    <HoverBall />
  </view>
</template>

3、启动项目调试，你以为这样就完了...？

这里列举一种情况：启动项目渲染的页面应该是A页面，但结果却是空白页面+悬浮球？

（注意：小红点以及条数是本人新增的功能需求，非本次案例讲解内容）

可能的原因？

在 App.vue 里，除了添加悬浮球组件，还需要确保原有的页面内容能正常渲染。Uni-app 的页面路由是通过 pages 配置文件来管理的，在 App.vue 中要给页面内容留出渲染空间。

加入<router-view> 组件，它会根据当前的路由自动渲染对应的页面。

所以代码应该是

<template>
  <view id="app">
    <!-- 渲染当前路由对应的页面 -->
    <router-view></router-view>
    <!-- 悬浮球组件 -->
    <HoverBall />
  </view>
</template>

这样就好了吗...?

这时候发现页面是正常渲染应该加载的页面，但悬浮球却不见了...

（脱敏，已对页面打码）

-问题分析

可能是由于路由跳转时的一些生命周期或者样式覆盖等原因导致的

-解决方案参考

-1. 组件未正确全局注册

确保在 main.js 中已经正确全局注册了 HoverBall 组件。

-2. 样式冲突问题

可能是功能页面的样式覆盖了悬浮球的样式，导致悬浮球不可见。你\可以检查功能页面的样式，特别是 z-index 属性。悬浮球的样式中需要设置一个较高的 z-index 值，确保它始终显示在最上层。

-3. 路由跳转时组件被销毁

在某些情况下，路由跳转可能会导致组件被销毁，从而使悬浮球消失。你可以尝试使用 keep-alive 包裹 router-view，确保组件不会被销毁。

<template>
    <view id="app">
        <!-- 使用 keep-alive 包裹 router-view -->
        <keep-alive>
            <router-view></router-view>
        </keep-alive>
        <!-- 悬浮球组件 -->
        <HoverBall />
    </view>
</template>

<script>
export default {
    onLaunch() {
        console.log('App Launch');
    },
    onShow() {
        console.log('App Show');
    },
    onHide() {
        console.log('App Hide');
    }
};
</script>

<style>
/* 全局样式 */
page {
    background-color: #ffffff;
}
</style>

-4. 组件初始化问题

检查 HoverBall.vue 组件中的初始化逻辑，确保在路由跳转后组件能够正常显示。特别是 created 生命周期钩子中的代码，确保获取系统信息等操作不会出现问题。

-本次案例采用：z-index:999

.hover_ball_cell {
    position: fixed;
    // overflow: hidden;
    border-radius: 50%;
    border: 4upx solid #67c23a;
    background: #ffffff;
    transform: translate(-50%, 0);
    padding: 4upx;
    display: flex;
    justify-content: center;
    align-items: center;
    z-index: 9999;  //新增
}

四、小结

以上就是一个悬浮球全局使用的教程和防踩坑细节，大家可以根据需求添加新的业务功能，这里提供几个思路：比如悬浮球的信息提示（小红点，而且有显示条数）、点击悬浮球后跳转到对应的信息处理页面等等。

二次更新

感谢评论区大佬指出的问题：关于router-view是不能直接在uniapp项目中使用。

以下经搜索和整理得出：

在 UniApp 中，`<router-view>` 是不能直接使用的，

原因如下：

1. UniApp 的路由机制与 Vue.js 的区别

UniApp 是基于 Vue.js 框架开发的跨平台应用框架，但它对路由机制进行了封装和适配，以适应多端（如微信小程序、App、H5 等）的开发需求。UniApp 默认使用的是页面跳转方式来实现路由功能，而不是像 Vue.js 那样通过 <router-view> 来动态渲染路由对应的组件。

在 Vue.js 中，<router-view> 是 Vue Router 的核心组件，用于动态渲染当前路由匹配到的组件。而在 UniApp 中，页面的跳转和渲染是通过 uni.navigateTo、uni.redirectTo、uni.switchTab 等 API 来实现的，而不是通过类似 <router-view> 的方式。

2. UniApp 的页面结构与路由

UniApp 的项目结构中，页面是通过 pages 目录下的 .vue 文件来定义的。每个页面文件都对应一个页面，页面的跳转是通过页面路径来实现的，而不是通过 Vue Router 的路由配置。

例如，如果你在 pages 目录下有一个 home/index.vue 文件，那么可以通过 uni.navigateTo({ url: '/pages/home/index' }) 来跳转到该页面。

3. 如何实现类似 `<router-view>` 的功能

在 UniApp 中实现类似 <router-view> 的功能

（1）使用条件渲染

如果需要在某个页面中动态切换不同的组件，可以使用 Vue 的条件渲染功能。例如：

<template>
  <view>
    <view v-if="currentComponent === 'ComponentA'">
      <ComponentA />
    </view>
    <view v-else-if="currentComponent === 'ComponentB'">
      <ComponentB />
    </view>
  </view>
</template>

<script>
import ComponentA from './ComponentA.vue';
import ComponentB from './ComponentB.vue';

export default {
  components: {
    ComponentA,
    ComponentB,
  },
  data() {
    return {
      currentComponent: 'ComponentA', // 默认显示 ComponentA
    };
  },
  methods: {
    switchComponent(componentName) {
      this.currentComponent = componentName;
    },
  },
};
</script>

（2）使用自定义路由逻辑

如果你需要更复杂的路由逻辑，可以自己实现一个简单的路由系统。例如，可以通过监听 URL 的变化来动态渲染不同的组件：

<template>
  <view>
    <view v-if="currentComponent === 'ComponentA'">
      <ComponentA />
    </view>
    <view v-else-if="currentComponent === 'ComponentB'">
      <ComponentB />
    </view>
  </view>
</template>

<script>
import ComponentA from './ComponentA.vue';
import ComponentB from './ComponentB.vue';

export default {
  components: {
    ComponentA,
    ComponentB,
  },
  data() {
    return {
      currentComponent: 'ComponentA', // 默认显示 ComponentA
    };
  },
  methods: {
    switchComponent(componentName) {
      this.currentComponent = componentName;
    },
  },
};
</script>

小结

在 UniApp 中不能直接使用 <router-view>，因为 UniApp 的路由机制与 Vue.js 不同。UniApp 使用页面跳转 API 来实现路由功能，而不是通过 <router-view>。如果需要实现类似 <router-view> 的功能，可以通过条件渲染或自定义路由逻辑来实现。