uni-app 项目中 template 无法访问 setup script 定义的常量问题解析

在 uni-app 项目开发过程中，开发者可能会遇到一个常见问题：在 Vue 3 的 <script setup> 语法中定义的常量，在模板(template)中无法正常访问。本文将深入分析这一问题的原因和解决方案。

问题现象

当开发者使用 Vue 3 的组合式 API 和 <script setup> 语法时，可能会写出如下代码：

<script setup>
const str = 'message'
</script>

<template>
  <view>{{str}}</view>
</template>

在 H5 环境下，这段代码能够正常工作，但在微信小程序平台中，模板中的 str 会显示为 undefined。只有当使用 ref 或 reactive 包装变量时，模板才能正常访问。

问题原因

这个问题的根源在于 uni-app 对不同平台的编译处理机制不同：

1. H5 平台：直接使用 Vue 3 的原生实现，<script setup> 语法能够正常工作
2. 小程序平台：由于小程序环境的特殊性，uni-app 需要进行额外的编译转换
3. 响应式要求：在小程序环境中，模板只能访问响应式数据，普通常量不会被自动暴露到模板作用域

解决方案

针对这个问题，开发者可以采用以下几种解决方案：

1. 使用 ref 包装变量

<script setup>
import { ref } from 'vue'
const str = ref('message')
</script>

<template>
  <view>{{str}}</view>
</template>

2. 使用 reactive 包装对象

<script setup>
import { reactive } from 'vue'
const state = reactive({
  str: 'message'
})
</script>

<template>
  <view>{{state.str}}</view>
</template>

3. 使用 defineExpose 显式暴露

<script setup>
const str = 'message'
defineExpose({
  str
})
</script>

<template>
  <view>{{str}}</view>
</template>

最佳实践建议

1. 统一使用响应式数据：即使某些平台支持直接访问常量，为了代码一致性，建议始终使用响应式数据
2. 平台兼容性考虑：开发时应考虑多平台兼容性，避免仅在一个平台测试通过就认为代码没有问题
3. 关注 uni-app 更新：这个问题在 uni-app 的后续版本中可能会得到修复，建议关注官方更新日志

总结

在 uni-app 项目开发中，特别是在使用 Vue 3 的组合式 API 时，开发者需要注意不同平台对 <script setup> 语法的支持差异。通过使用响应式数据或显式暴露变量，可以确保代码在所有平台上都能正常工作。理解这些底层机制有助于开发者写出更健壮、可维护的跨平台应用代码。