public.js 公共工具函数详解
本文档介绍项目中的公共方法集合，主要用于uni-app开发环境。
导入方式
import { serverRef, disablePageScroll, enablePageScroll, openUrl, sleep } from '@/common/js/public.js'
一、serverRef 方法
功能说明
响应式数据获取方法。当绑定的响应式变量值发生改变时，自动向服务器发起请求获取最新数据。
平台限制
由于H5存在跨域问题，在H5端使用时请求URL必须位于同域名下。
参数说明
serverRef({
url: '', // [String] 请求地址，必需
method: 'GET', // [String] 请求方式，可选，默认GET
data: {}, // [JSON] 响应式绑定变量，必需
validate: function() {}, // [Function] 前置验证，返回false则不发起请求
delay: 200, // [Number] 防抖延迟毫秒数，可选，默认200ms
success: function(data) {}, // [Function] 请求成功回调
fail: function(msg) {}, // [Function] 请求失败回调
complete: function() {} // [Function] 请求完成回调
})
使用示例一：组合式API（setup函数内）
<template>
<uni-data-picker
:localdata="gradeList"
placeholder="请选择年级"
v-model="selectedGrade">
</uni-data-picker>
<view>
服务器返回数据：{{ responseData }}
</view>
</template>
<script setup>
import { ref } from 'vue'
import { serverRef } from '@/common/js/public.js'
// 年级数据
const gradeList = [
{
text: "一年级",
value: "1-0",
children: [
{ text: "1.1班", value: "1-1" },
{ text: "1.2班", value: "1-2" }
]
},
{
text: "二年级",
value: "2-0"
}
]
const responseData = ref('')
const selectedGrade = ref('')
// 监听年级选择变化，自动获取班级数据
serverRef({
url: 'http://example.com/api/classes',
method: 'GET',
data: {
gradeId: selectedGrade
},
validate: function() {
return selectedGrade.value.length > 0
},
success: function(data) {
responseData.value = data
},
fail: function(error) {
console.error('请求失败：', error)
}
})
</script>
使用示例二：选项式API（data选项中）
<template>
<uni-data-picker
:localdata="gradeList"
placeholder="请选择年级"
v-model="queryParams.gradeId">
</uni-data-picker>
<view>
服务器返回数据：{{ responseData }}
</view>
</template>
<script>
import { serverRef } from '@/common/js/public.js'
export default {
data() {
return {
responseData: '',
queryParams: {
gradeId: ''
},
gradeList: [
{
text: "一年级",
value: "1-0",
children: [
{ text: "1.1班", value: "1-1" },
{ text: "1.2班", value: "1-2" }
]
},
{
text: "二年级",
value: "2-0"
}
]
}
},
created() {
const vm = this
serverRef({
url: 'http://example.com/api/classes',
method: 'GET',
data: vm.queryParams,
validate: function() {
return vm.queryParams.gradeId !== ''
},
success: function(data) {
vm.responseData = data
},
fail: function(error) {
console.error('请求失败：', error)
}
})
}
}
</script>
注意事项
- data参数必须是ref或reactive包装的响应式变量
- 当响应式变量值发生变化时，会自动触发服务器请求
- validate函数返回false时会跳过本次请求
- delay参数用于防止频繁请求，可根据实际需求调整
二、页面滚动控制方法
方法说明
在弹层显示时，需要禁止底层页面滚动；弹层关闭后，恢复页面滚动功能。
disablePageScroll() // 禁用页面滚动
enablePageScroll() // 恢复页面滚动
平台支持
仅支持H5端，APP端暂不支持。
使用示例
<template>
<button @click="togglePopup">切换弹窗 - {{ showPopup }}</button>
<view style="height: 2000px;">页面内容区域</view>
</template>
<script>
import { disablePageScroll, enablePageScroll } from '@/common/js/public.js'
export default {
data() {
return {
showPopup: false
}
},
watch: {
'showPopup': function(newVal) {
newVal ? disablePageScroll() : enablePageScroll()
}
},
methods: {
togglePopup() {
this.showPopup = !this.showPopup
}
}
}
</script>
三、openUrl 方法
功能说明
打开指定URL地址，或拨打联系电话。
平台支持
APP端和H5端均支持。
参数说明
openUrl(url, target)
- url: [String] 网址链接或电话号码，必需参数
- target: [String] 跳转方式，可选，默认值_blank，仅H5端有效
使用示例
<template>
<view @click="callService">
联系客服：0556-5371498
</view>
</template>
<script>
import { openUrl } from '@/common/js/public.js'
export default {
methods: {
callService: function() {
openUrl('0556-5371498', '_self')
}
}
}
</script>
四、sleep 方法
功能说明
使程序暂停执行一段时间，常用于模拟延迟操作或等待异步任务完成。
参数说明
sleep(seconds, interval)
- seconds: [Number] 暂停时长，单位秒，必需参数
- interval: [Number] 刷新间隔，可选，默认1000ms
注意事项
调用sleep的函数必须使用async修饰，并在调用时使用await等待。
使用示例
<template>
<button @click="delayedShow">点击后3秒显示内容</button>
<view v-if="isVisible">
内容已显示
</view>
</template>
<script>
import { sleep } from '@/common/js/public.js'
export default {
data() {
return {
isVisible: false
}
},
methods: {
delayedShow: async function() {
console.log('开始等待...')
await sleep(3)
console.log('等待结束')
this.isVisible = true
}
}
}
</script>
进阶使用
当暂停时间较短时（如0.5秒），可调整interval参数：
// 暂停0.5秒，interval设为100
await sleep(0.5, 100)
