写在前面

这里记录一些目前为止踩过的坑,如果以后踩到别的坑,也要在这里补充。


约定:


踩坑记录规范:


注意:为避免此文档膨胀,如果某个记录篇幅过长,则应新建一篇文档,然后将在此引用即可。


1. 微信开发者工具关闭 ES6 转 ES5

如果微信开发者工具开启了 ES6 转 ES5 的功能,会导致引入的 uView 组件无法正常使用,会报类似于下面这样的错:

image.png

解决方案就是:把微信开发者工具的 ES6 转 ES5 功能关掉,设置 -> 项目设置 -> 本地设置。


2. ref 不要放在 computed

下面这份代码,在小程序端运行异常:

<template>
  <view class="container">
    <button ref="button">button</button>
  </view>
</template>

<script>
export default {
  computed: {
    buttonRef() {
      return this.$refs.button
    },
  },

  mounted() {
    this.buttonRef.someMethods() // 在 mp-weixin 会报:buttonRef 为空
  },
}
</script>

解决方案就是:不要把 refs 的定义放在 computed,而是每次使用都重新获取: this.$refs.button


3. 小程序端的组件样式问题

有可能你在 h5 编写好一个组件的样式,运行好好的,结果在小程序端却不正常了,原因在于小程序端会在组件外额外增加一层视图容器,这可能会导致诸如一些高度、外边距之类的样式失效,解决方案就是修改这个外层的样式,使它与我们这个组件的最外层样式一致:

<style lang="scss">
// #ifdef MP-WEIXIN
// HACk: 微信小程序端组件外面会多一层,需要给它也设置高度
[data-ref='basicLayout'], // 这里的值在微信开发者工具查看
// #endif
.basic-layout,
.page-content {
  flex: 1;
  display: flex;
  flex-direction: column;
}
</style>

注意:由于这个选择器只针对小程序端,所以我们要加一个条件渲染。


4. 小程序端修改的外部组件样式无效的问题

此处为语雀文档,点击链接查看:https://www.yuque.com/go/doc/31588787


5. 在 HBuilder 运行项目

由于我们是使用 cli 的方式生成的项目,所以基本开发只需要在命令行运行 npm run dev:xxx 即可,但是如果要调试 APP 端,还是使用 HBuilder 要更方便,然而如果在 在 HBuilder 运行 cli 项目 你可能会遇到以下错误:

Node Sass could not find a binding for your current environment: OS X 64-bit with Node.js 8.x

说白就是 node-sass 出了问题了,HBuilder 默认使用的 Node 版本是 v8.x,所以我们要修改一下配置,让它使用我们本机的 Node 版本。


在 偏好设置 -> 运行配置 中修改 npm 和 Node 的路径即可:

image.png

如果你不知道 Node 的路径在哪,可以这样:


参考:https://ask.dcloud.net.cn/question/67852


6. 动态插槽名

此处为语雀文档,点击链接查看:https://www.yuque.com/go/doc/31588789


7. 小程序端 v-for 中使用 v-if 问题

此处为语雀文档,点击链接查看:https://www.yuque.com/go/doc/31588788


8. 小程序端禁止事件冒泡

此处为语雀文档,点击链接查看:https://www.yuque.com/go/doc/31588786


9. uView 两层 tabsSwiper left 计算问题

使用 uView 的 tabSwiper 组件时,如果存在两层或多层嵌套,会出现内层的 swiper-item 的 left 值计算错误,这是 uView 的 bug,具体问题描述和临时解决方案可见:https://github.com/YanxinNet/uView/issues/749


10. scss 文件进行条件渲染

.scss 文件中进行 uni-app 的条件渲染,必须为多行注释,如下:

/* #ifdef MP-WEIXIN */
.u-btn {
  color: red !important;
}
/* #endif */

另外,如果在 .vue 中的 style 标签,则无论使用单行注释还是多行注释,都是有效的。


11. 方法名不能与生命周期名字冲突

如题,写在 methods 下的方法名字不要与生命周期一致,否则会出现错误,这里的生命周期包括:


12. 调试 uView 组件

如果使用 uView 组件过程中遇到莫名其妙的问题,建议使用断点调试,可帮助你快速定位问题。


举个例子,想看看 u-tabs-swiper  组件的某个方法执行过程,可以到 node_modules/uview-ui/components/u-tabs-swiper/u-tabs-swiper.vue ,找到你想调试的方法,打个断点:

image.png

然后在浏览器刷新,进行某些操作以便触发你想调试的方法,然后就可以进行断点调试了:


遗憾的是 uni-app 的自带组件,虽然也可以在 node-module 目录下找到对应的源码位置,但因为是预编译好的,所以进行修改无效,自然也不能打断点。


大部分 uni-app 的组件都在: node_modules/@dcloudio/uni-h5/src 下。


核心要点:当组件莫名其妙地表现不正常时,别忘了使用断点调试。


13. SwipeAction 组件无法自动隐藏按钮

此处为语雀文档,点击链接查看:https://www.yuque.com/go/doc/31588784


14. 小程序子页面自定义导航进入时闪烁问题

此处为语雀文档,点击链接查看:https://www.yuque.com/go/doc/31588785

15. tabSwipe 双层无缝滑动切换

如果想要实现 tabSwipe 双层无缝滑动切换的效果,由于 uni-app 的 swipe 限制,目前没有完美方案可解决,所以暂时搁置。


若以后有这个需求,再根据业务情况,选择是否修改 swipe 组件,或另行开发。


16. IOS 底部空白安全区域

子页面在 IOS 会出现一个空白的安全区域,可以通过修改 manifest.json 禁用它:

{
  "app-plus": {
    "safearea": {
      "bottom": {
        "offset": "none"
      }
    }
  }
}

参考文档:uni-app 全面屏、刘海屏适配(iphoneX适配)及安全区设置


17. APP 端锁定屏幕方向

通过 manifest.jsonorientation 选项可以进行横竖屏配置:

{
  "distribute": {
    "orientation": ["portrait-primary"]
  }
}

但如果在测试基座, 以上选项会失效,所以最保险的方式是在 APP.vue 中进行配置:

export default {
  onLaunch() {
    // #ifdef APP-PLUS
    // 锁定竖屏
    plus.screen.lockOrientation('portrait-primary')
    // #endif
  },
}

使用该 API 还可以实现仅允许特定页面旋转方向,关于更多可见:HTML+ API Reference


关于屏幕旋转的更多可参考:


18. uButton 自定义样式

根据 uView 文档 说明,如果想要给 button 自定义样式,为了兼容小程序,则要在组件中传递 custom-style 属性,也就意味着需要把 CSS 写在 JS 中,这不是我们想要的,毕竟这样就无法使用 Scss 中的变量了。


为什么要这么麻烦呢?因为在小程序端,原本是一层的元素,被它搞成两层了,所以我们传递过去的 class 属性只应用在外层,而内层才是真正 button。


举个例子:

<template>
  <view class="test-page">
    <u-button class="btn">按钮</u-button>
  </view>
</template>

<style lang="scss">
.test-page {
  .btn {
    color: red;
  }
}
</style>

以上代码在 H5 的表现是正常的:

image.png

但在小程序的表现却是这样的:

image.png


如果想 CSS 层面解决该问题,那就是都将它们都作为选择器即可:

<template>
  <view class="test-page">
    <u-button class="btn">按钮</u-button>
  </view>
</template>

<style lang="scss">
.test-page {
  .btn {
+    &,
+    button {
      color: red;
+    }
  }
}
</style>

虽然看上去很丑,但能 work,且兼容性较好,所以推荐使用该方式。


19. uButton 无法自定义 hover-class

根据 uView 文档 说明,Button 组件有 hover-class 属性,可自定义 hover 时的 class,但实际使用并无效果,查看源代码后发现代码存在问题。


目前 GitHub 上已有人指出该问题,但维护者仍未处理:


在不修改原组件的情况下,只能通过强制覆盖它默认的 hover-class 的样式来解决该问题:

<template>
  <view class="test-page">
    <u-button class="btn">退出登录</u-button>
  </view>
</template>

<style lang="scss">
.test-page {
  // HACK: 由于 uButton 的 hover-class 传递无效,暂时只能通过该方式自定义
  /deep/ .btn {
    &.u-default-hover,
    // 兼容小程序
    button.u-default-hover {
      color: white !important;
      background: rgba($color-primary, 0.8) !important;
    }
  }
}
</style>

注意:

  1. 为了避免影响其它 button,需要限制选择器范围
  2. class 不一定是 u-default-hover ,可以自行测试该 button hover 时实际使用哪个 class
  3. 兼容小程序那里详见:18. uButton 自定义样式


20. uni-app 只能在 main.js 注册全局组件

此处为语雀文档,点击链接查看:https://www.yuque.com/go/doc/31588783