1. 引言

uniapp 是一套基于 Vue.js 的跨端开发框架，能够一套代码同时发布到 iOS、Android、H5 以及各种小程序平台。对于刚接触 uniapp 的开发者来说，掌握其核心语法和开发中的注意事项，是保证项目顺利推进的关键。本文将从常用语法、生命周期、组件通信、平台差异和性能优化等方面展开介绍。

2. 基础语法

uniapp 的页面结构由 template、script 和 style 三部分组成，整体写法与 Vue 单文件组件保持一致。

<template>
  <view class="container">
    <text>{{ message }}</text>
    <button @click="handleClick">点击</button>
  </view>
</template>

<script>
export default {
  data() {
    return {
      message: 'Hello uniapp'
    }
  },
  methods: {
    handleClick() {
      this.message = '已点击'
    }
  }
}
</script>

<style>
.container {
  padding: 20rpx;
}
</style>

在模板中，数据绑定使用双大括号，事件绑定使用 @ 符号，条件渲染使用 v-if 和 v-show，列表渲染使用 v-for。需要注意的是，uniapp 中推荐使用 view、text、button 等内置组件，而不是直接使用 HTML 标签。

3. 生命周期

uniapp 的生命周期分为应用生命周期、页面生命周期和组件生命周期三类。页面生命周期中常用的有 onLoad、onShow、onReady 和 onUnload。

export default {
  onLoad(options) {
    // 页面加载时触发，options 为页面参数
    console.log('页面加载', options)
  },
  onShow() {
    // 页面显示时触发
    console.log('页面显示')
  },
  onReady() {
    // 页面初次渲染完成时触发
    console.log('页面渲染完成')
  },
  onUnload() {
    // 页面卸载时触发
    console.log('页面卸载')
  }
}

与 Vue 的 created、mounted 不同，uniapp 的页面生命周期是框架特有的，需要按平台规范使用。组件内部仍然可以使用 Vue 的 created、mounted 等生命周期。

4. 组件通信

组件通信是开发中经常遇到的问题。uniapp 支持父子组件通信、兄弟组件通信和全局状态管理。

父子组件通信通过 props 和自定义事件实现：

<!-- 父组件 -->
<template>
  <child-component :title="title" @update="handleUpdate" />
</template>

<script>
import ChildComponent from '@/components/child-component.vue'
export default {
  components: { ChildComponent },
  data() {
    return {
      title: '父组件标题'
    }
  },
  methods: {
    handleUpdate(value) {
      console.log('子组件更新', value)
    }
  }
}
</script>

<!-- 子组件 -->
<template>
  <view>
    <text>{{ title }}</text>
    <button @click="emitUpdate">更新</button>
  </view>
</template>

<script>
export default {
  props: {
    title: {
      type: String,
      default: ''
    }
  },
  methods: {
    emitUpdate() {
      this.$emit('update', '子组件传来的值')
    }
  }
}
</script>

对于跨页面或跨组件的状态共享，推荐使用 Vuex 或 Pinia 进行全局状态管理，避免层层传递 props 造成代码冗余。

5. 常用 API 与条件编译

uniapp 提供了丰富的 API，例如网络请求 uni.request、本地存储 uni.setStorageSync、页面跳转 uni.navigateTo 等。这些 API 在不同平台上表现一致，方便开发者调用。

// 网络请求
uni.request({
  url: 'https://api.example.com/data',
  method: 'GET',
  success: (res) => {
    console.log('请求成功', res.data)
  },
  fail: (err) => {
    console.log('请求失败', err)
  }
})

// 本地存储
uni.setStorageSync('token', 'abc123')
const token = uni.getStorageSync('token')

// 页面跳转
uni.navigateTo({
  url: '/pages/detail/detail?id=1'
})

由于不同平台存在差异，uniapp 提供了条件编译语法，通过注释的方式让特定代码只在指定平台生效：

<!-- #ifdef MP-WEIXIN -->
<view>仅微信小程序平台显示</view>
<!-- #endif -->

<!-- #ifndef H5 -->
<view>非 H5 平台显示</view>
<!-- #endif -->

条件编译同样适用于 script 和 style 中，是处理平台差异的重要工具。

6. 开发注意事项

在实际开发中，有几个容易踩坑的地方需要特别留意。

第一，单位选择。uniapp 推荐使用 rpx 作为尺寸单位，它会根据屏幕宽度自动适配。在 H5 端 1rpx 对应 0.5px，在小程序端则按 750 设计稿宽度换算。

第二，图片资源。小程序端不支持本地图片的远程引用，图片应使用网络地址或放入 static 目录。同时要注意图片的压缩，避免影响页面加载速度。

第三，样式隔离。小程序端的样式默认是隔离的，页面样式不会自动作用于自定义组件。需要时可以通过 styleIsolation 配置调整。

第四，导航栏配置。不同平台的导航栏样式存在差异，建议使用 pages.json 统一配置导航栏标题、背景色等属性，减少平台差异带来的视觉不一致。

第五，兼容性测试。由于目标平台较多，发布前务必在微信小程序、App 和 H5 等主要平台分别进行真机测试，重点检查布局、交互和 API 调用是否正常。

7. 性能优化建议

性能优化是提升用户体验的关键。在 uniapp 项目中，可以从以下几个方面入手。

• 减少 setData 频率：小程序端频繁更新数据会带来性能开销，尽量合并多次数据更新。
• 合理使用 v-if 和 v-show：v-if 会销毁和重建节点，v-show 仅切换显示状态，高频切换场景优先使用 v-show。
• 长列表优化：使用 v-for 渲染长列表时，建议配合分页加载或虚拟列表方案。
• 图片懒加载：为图片设置懒加载属性，减少首屏加载压力。
• 分包加载：小程序端可以将非核心页面放入分包，加快首屏启动速度。

8. 总结

uniapp 的开发体验与 Vue 高度一致，上手门槛较低，但跨端特性也带来了一些需要特别注意的细节。掌握基础语法、生命周期、组件通信和条件编译，并在开发中关注单位、图片、样式隔离和性能优化，就能有效减少踩坑，提升开发效率和产品质量。建议在项目初期就建立统一的代码规范和平台适配方案，为后续迭代打好基础。