当前位置：首页 > news >正文

uniapp-内部项目使用文档

news 2025/3/1 4:56:26

uniapp-内部项目使用文档

uniapp-内部项目使用文档
- 阶段1
- - - 自行实现内容：
    - 阶段1问题记录：
- 阶段2
- - - 自行实现内容：
- 阶段3 APP项目介绍及规范
- 阶段4 公共组件方法
- - UseList 列表页面Hooks
  - ListItem 列表项
  - uni-load-more 列表加载更多组件
  - CardTitle 列表卡片标题组件
  - Tags 标签
  - Empty 缺省页
  - 权限
  - - hasPermission 按钮权限
  - FilterPopup 筛选组件
  - PublicPicker 数据字典&省市县镇选择
  - Tips 提示
  - DateRange 日期时间范围组件
  - useSelectSearch 可模糊查询的选择 Hooks
  - SelectSearchItem 可模糊查询的选择器
  - DataForm 数据表单，使用json生成表单

基础教程文档

【内部项目使用文档】
【内部项目使用文档】
【内部项目使用文档】

阶段1

一、介绍【uniapp介绍、项目创建、运行发布、代码写法变化、项目结构】

二、页面&组件&配置&api

三、教程【生命周期、路由、条件编译】

自行实现内容：

创建、运行项目
创建新页面、跳转新页面、传参&接收参数

阶段1问题记录：

升级hbx后项目运行报错
回退hbx版本：帮助 -> 切换到上一个版本
项目突然有异常启动的问题，非页面问题，可以考虑是hbx问题，尝试检查更新版本或回退版本

阶段2

一、基本的list页面

使用uni-card组件
配置下拉刷新、配置触底加载

二、基本表单提交

基本表单提交页面
基本校验链接
自定义校验链接
正则校验 pattern

三、常用生命周期

一般接口请求直接在setup生命周期请求即可。

import {onLoad, onShow} from '@dcloudio/uni-app'
onLoad(() => {console.log('onLoad')
})
onShow(() => {console.log('onShow')
})
console.log('setup');/* 打印结果
setup
onLoad
onShow
*/

自行实现内容：

表格
表单

阶段3 APP项目介绍及规范

样式：公共变量写在uni.scss内，不用在页面内引入即可使用。自带的公共变量在'@/uni_modules/uni-scss/variables.scss';查找，可直接使用。
样式：公共样式写在@/common/styles/public.scss内，已在app.vue内引入，不用在页面内引入即可使用。
辅助样式：链接
样式：页面和组件内写样式，style标签必须加scoped。
```
<style lang="scss" scoped>
</style>
```
页面底部写入安全区域适配代码

考虑到开屏广告适配情况，不配置全局的安全区域适配，需要在各个页面内单独适配
```
<view class="padding-bottom-safe"></view>
```
组件：公共组件写在@/components/组件名/组件名.vue；页面级组件写在 页面/components/组件。
api：接口请求statusCode!==200时，封装方法内有公共错误提示，页面内不用管；其他情况错误和正确提示需要在页面内自行处理。
api：以接口地址第一个单词作为api文件名，将api单个导出，单个引入。注意get和post传参写法不一样。

如/bill/billLading/list,则创建 @/apis/bill.js

import {http} from '@/common/service/service.js'// 需求确认列表
export const listCheckDataApi = (params) => http.get('/demand/listCheckData', {params});// 更新需求
export const updateStatusApi = (params) => http.post('/demand/updateStatus', params);

页面内使用

import Tips from "@/common/utils/tip";
import {listCheckDataApi, updateStatusApi} from "@/api/demand";
const initData = async () => {const [err, res] = await listCheckDataApi({// 参数xxx:xxx})if (err) {// 错误处理Tips.toast(err.data?.msg || '操作失败')return}// 成功处理
}

安装eslint-vue插件

https://ext.dcloud.net.cn/plugin?id=2005

eslint-vue简介
rpx

页面内尽量使用rpx

rpx介绍-自行查看

阶段4 公共组件方法

为什么要做组件封装？：

代码复用： 通过将一些常用的功能或界面元素封装成组件，可以在不同的地方多次使用，避免重复编写相同的代码。
易于维护： 将一些功能或界面元素封装成组件后，可以更容易地对其进行修改、更新和扩展，而不会影响到其他部分的代码。
提高开发效率： 通过使用现有的组件，开发人员可以更快地构建新的界面，而不必从头开始编写所有的代码。
抽象复杂性： 封装组件可以帮助将复杂的功能或界面元素抽象成简单的接口，使得整个系统更易于理解和管理。

封装组件的条件：

可定制性： 组件应该具有足够的参数和选项，以便在不同的上下文中进行定制和配置。
灵活性： 组件应该能够适应不同的数据和状态，而不是过于依赖特定的数据结构或业务逻辑。
可组合性： 组件应该能够与其他组件进行组合和嵌套，以构建更复杂的界面。
可测试性： 组件应该具有清晰的API和明确定义的行为，以便进行单元测试和集成测试。
文档和示例： 组件应该有清晰的文档和示例，以便其他开发者能够快速理解和正确使用组件。
样式隔离： 组件应该具有良好的样式隔离，以防止组件的样式影响到其他部分的页面。

UseList 列表页面Hooks

参数：

initData初始化方法，Function，必传，接口请求放在该方法内
pageSize?每页条数，Number，默认 5
pullDownRefresh?是否下拉刷新，Boolean，默认true
reachBottom?是否触底加载，Boolean，默认true

返回值：

total 总数，initData方法内需要对其赋值
pageNo 当前页码
pageSize每页条数
loadMoreStatus 加载更多状态
changeIsApiPostDoing(Boolean)改变是否请求中状态

基本的列表数据请求：

import Tips from "@/common/utils/tip";
import {useList} from "@/hooks/useList";
import {listData1Api} from "@/apis/mock-data"; // 导入要调用的apiconst {total,pageNo,pageSize,loadMoreStatus,changeIsApiPostDoing,listData
} = useList({initData
})async function initData(reset = false) {if (reset) {pageNo.value = 1;}// listDataApi：导入的APIconst [err, res] = await listDataApi({pageSize: pageSize.value,pageNo: pageNo.value})// 在此调用该方法changeIsApiPostDoing(false)if (err) {Tips.toast(err.message || '操作失败，请稍后再试')listData.value = [];return}listData.value = pageNo.value === 1 ? res.data : listData.value.concat(res.data)total.value = res.total
}

ListItem 列表项

showPoint? 前面显示红点，默认false
single? 一行一个，没有 max-width限制，默认false

<uni-card v-for="(item) in listData" :key="item.id"><ListItem><text>买家：</text><template #right><text>xxxx有限责任公司</text></template></ListItem><ListItem><text>账户标识：</text><text class="list-value">4599</text><template #right><text class="list-label">销售片区：</text><text>西咸片区</text></template></ListItem><ListItem><text>产品信息</text><template #right><view>螺纹钢  HRB400E  Φ18*9m  检尺  293.4</view><view>螺纹钢  HRB400E  Φ18*9m  检尺  293.4</view></template></ListItem><ListItem><text>总重量：</text><text class="color-red">2566.01</text><template #right><text class="list-label">总金额：</text><text class="color-red">2566.01</text></template></ListItem>
</uni-card>

特殊情况使用下面代码，自行编写

    <view class="list-item"><view class="list-item-left"><text class="list-label">卖家：</text></view><view class="list-item-right"><text class="list-value"xxxx有限公司</text></view></view><view class="list-item"><view class="list-item-left"><text class="list-label">账户标识：</text><text class="list-value">4599</text></view><view class="list-item-right"><text class="list-label">销售片区：</text><text class="list-value">西咸片区</text></view></view>

uni-load-more 列表加载更多组件

https://uniapp.dcloud.net.cn/component/uniui/uni-load-more.html

loadMoreStatus more/loading/noMore，直接取 useList内返回的loadMoreStatus

<template><!--在页面底部加入--><uni-load-more :status="loadMoreStatus" v-if="listData.length" />
</template>

CardTitle 列表卡片标题组件

leftText? 默认left是蓝色字体
rightText? right是红色字体
showArrow?是否显示右箭头，默认true

<!-- 方式1  -->
<CardTitle leftText="SG-SJHT1722587699823310" rightText="执行中" :showArrow="false" />
<!-- 方式2 : 适用于自定义的样式 -->
<CardTitle><template #left>SG-SJHT1722587699823310</template><template #right>执行中</template>
</CardTitle>

Tags 标签

type? 为不一样的颜色，【1~5】
text? 文字

<Tags text="标签" type="1"/>
<Tags text="标签" type="2"/>
<Tags text="标签" type="3"/>
<Tags text="标签" type="4"/>
<Tags text="标签" type="5"/>

Empty 缺省页

isShow 是否显示
text? 提示文字
img? 提示图片

<Empty :is-show="!listData.length" />

权限

hasPermission 按钮权限

<template><!--传字符串--><button size="mini" class="button" v-if="hasPermission('权限code1')">编辑</button><!--传数组--><button size="mini" class="button" v-if="hasPermission(['权限code1', '权限code2'])">编辑</button>
</template>
<script setup>import {usePermission} from "@/hooks/usePermission";const {hasPermission} = usePermission()
</script>

FilterPopup 筛选组件

页面筛选组件使用方法
uni-easyinput传filter-input样式时，需要将styles传空对象，否则会导致样式不生效
methods

@reset 重置按钮
@submit 确认按钮

<template><FilterPopup ref="filterPopup" @reset="handleReset" @submit="handleSubmit"><uni-forms ref="baseForm" :modelValue="baseFormData" label-position="top"><uni-forms-item label="买家" name="corpNameBuyer"><uni-easyinput v-model="baseFormData.corpNameBuyer" :styles="{}" :clearable="false" class="filter-input":inputBorder="false" placeholder="请输入买家"/></uni-forms-item><uni-forms-item label="卖家" name="corpName"><uni-easyinput v-model="baseFormData.corpName" :styles="{}" :clearable="false" class="filter-input":inputBorder="false" placeholder="请输入卖家"/></uni-forms-item><uni-forms-item label="申请时间" name="applyStartDate"><uni-datetime-picker type="datetime" :border="false" class="filter-input" v-model="baseFormData.applyStartDate"/><uni-datetime-picker type="datetime" :border="false" class="filter-input uni-mt-4"v-model="baseFormData.applyEndDate"/></uni-forms-item></uni-forms></FilterPopup>
</template>
<script setup>import {onNavigationBarButtonTap} from '@dcloudio/uni-app'import {ref} from "vue";// 初始值const baseFormDataDefault = JSON.stringify({corpNameBuyer: '',corpName: '',applyStartDate: '',applyEndDate: ''})// 筛选弹窗数据const baseFormData = ref(JSON.parse(baseFormDataDefault))const filterPopup = ref()// 右上角筛选按钮点击方法onNavigationBarButtonTap(() => {filterPopup.value.open()})// 重置const handleReset = () => {baseFormData.value = JSON.parse(baseFormDataDefault)console.log('handleReset', baseFormData.value);}// 确认const handleSubmit = () => {console.log('handleSubmit', baseFormData.value);}
</script>

需要在pages.json中配置筛选按钮 app-plus -> titleNView -> buttons

{"path": "pages/demo/list/list","style": {"navigationBarTitleText": "列表","enablePullDownRefresh": true,"app-plus": {"titleNView": {"buttons": [{"text": "筛选 \uE64D","fontSize": "12px","fontSrc": "/static/iconfont.ttf","width": "55px"}]}}}
},

PublicPicker 数据字典&省市县镇选择

该组件支持单选、多选、picker 多种展示方式；
支持多种传数据源的方式。

modelValue: String | Array v-model
dictCode?: String, // 数据字典code，
- 如果dictCode: areas，则获取本地省市县镇数据，
- level? Number 省市县镇组件层级，默认4
localData?: Array, // 数据，优先使用dictCode
api?: Function // 通过api请求获取数据
- fieldNames // 处理字段，默认值 {label: 'label', value: 'value', result:'result'}
showType?: 'picker' | 'checkbox' | undefined, //显示类型 picker/checkbox，默认picker
- multiple?: Boolean, // 多选-checkbox时有效，默认false
popupTitle?: String, 默认 “请选择”

说明： dictCode、api 和localData 必须传一个，优先级dictCode > api > localData

methods

@change 返回选中的数据，为了统一不管单选多选都返回array
- 省市县镇时返回 {areaCodeList, areaNameList}
- 其他类型，不论单选还是多选都返回数组 [{text, value, 其他参数... }]

<!--picker选择-传字典code-->
<PublicPicker v-model="baseFormData.key4" dict-code="accept_type" />
<!--单选-->
<PublicPicker v-model="baseFormData.key5" dict-code="car_brand" show-type="checkbox" />
<!--多选-->
<PublicPicker v-model="baseFormData.key6" dict-code="car_kind" show-type="checkbox" multiple />
<!--picker选择-传localData，也支持单选、多选-->
<PublicPicker v-model="baseFormData.key3" :localData="sexs" />
<!--localData示例
[{text: '男', value: '1'}, {text: '女', value: '2'}]
-->
<!--监听改变  @change -->
<PublicPicker v-model="baseFormData.key4" dict-code="accept_type"  @change="handleSelectChange" /><!--省市县镇组件-->
<PublicPicker v-model="baseFormData.key9" dictCode="areas" />

Tips 提示

注意：显示图标是有字数限制，最多8个字，长了不显示

成功时，字数少的使用 success

错误是使用 error或toast

import Tips from "@/common/utils/tip";Tips.success(title, duration = 1000)  // 对钩图标
Tips.error(title, onHide)  // 叹号图标
Tips.toast(title, onHide = undefined, icon = "none") // 无图标
Tips.confirm(content, ops = {}, payload = {}) // 确定取消提示
Tips.loading(title = "加载中") // '加载中'
Tips.hideLoading() // 隐藏加载中

DateRange 日期时间范围组件

type date | datetime | undefined 默认 datetime
border Boolean，默认false
modelValue

<!--日期范围-->
<DateRange v-model="baseFormData.key7" type="date" /><!--日期时间范围-->
<DateRange v-model="baseFormData.key8" type="datetime" />

校验时间范围方法

{key6: {rules: [{ required: true, errorMessage: '请选择时间' },{ validateFunction: function (rule, value, data, callback) {const [date1, date2] = value;console.log(date1, date2);if (!date1 && !date2) {callback('请选择时间')} else if (!date1) {callback('请选择开始时间')} else if (!date2) {callback('请选择结束时间')}return true;}}]}
}

useSelectSearch 可模糊查询的选择 Hooks

模糊查询选择，打开新页面输入内容进行查询选择

apiUrl: `{type: String, required: true,}, 接口请求地址，非方法
placeholder: { type: String, default: ‘请选择’}, 提示信息
title: { type: String, default: ‘请选择’,}, 搜索页标题
keyword: { type: String, default: ‘keyword’}, 搜索传接口的字段key
valueField: { type: String, default: ‘value’}, 接口返回的value字段
labelField: { type: String, default: ‘label’}, 接口返回的label字段
isInit: { type: Boolean, default: true}, 页面是否初始化时直接调用接口
params: { type: Object, default: () => ({})}, 额外参数
modelValue: String,clearIcon: { type: Boolean, default: true}, v-model
readonly: { type: Boolean, default: false} 禁用
@change 改变方法

<template><button  @click="handleClick">打开搜索页</button>
</template>
<script setup>
import ss from "@/hooks/useSelectSearch";
const handleClick = () => {ss.to({apiUrl: querySysCorpByCorpNameUrl,keyword: 'corpName',title: '请选择买家',valueField: 'corpCode',labelField: 'corpName',init: false,params: {corpType: 'xs_buyer'}})ss.on((check) => {console.log('check', check);})
}
</script>

SelectSearchItem 可模糊查询的选择器

参数同上 useSelectSearch

组件内使用的也是useSelectSearch方法，组件内封装，供表单内使用。

<SelectSearchItem:apiUrl="querySysCorpByCorpNameUrl"keyword="corpName":params="{corpType: 'xs_buyer'}":isInit="false":readonly="false"title="请选择买家"placeholder="请选择买家"valueField="corpCode"labelField="corpName"v-model="baseFormData.key11"@change="handleSelectChange"/>

DataForm 数据表单，使用json生成表单

通过json数据生成表单
注意：组件内数据改变，会直接修改传入的modelValue的源数据。

<!--基本使用示例-->
<DataFormref="dataFormRef":formProps="{}":model="demoForm":schemas="schemas"@change="handleFormChange"@submit="handleSubmit"><template #slot1><input type="text" v-model="demoForm.key10"></template>
</DataForm>

formProps：传到表单uni-forms的属性,
默认值：{labelWidth: '100px',border: true,}

schemas: { type: Array, required: true,}, // 表单schema
component支持的组件类型有：

uniEasyInput 输入框
PublicPicker 公共选择
DateRange 时间范围选择,DateRange传className时，需要加上uni-mt-4，否则会导致没有边距
UniDatetimePicker 日期 / 日期时间选择
SelectSearchItem 模糊搜索选择
slot 插槽

 [{label: '用户名',field: 'key1',component: 'uniEasyInput',required: true,componentProps: {//传递给组件的参数，参考各组件文档inputBorder: false,placeholder: '请输入用户名'},rules: [{ required: true, errorMessage: '请输入用户名' }]},{label: '省市县镇',field: 'key7',component: 'PublicPicker',componentProps: {dictCode: 'areas',level: 3}},{label: '日期时间范围',field: 'key6',component: 'DateRange',componentProps: {type: 'datetime'},rules: [{ required: true, errorMessage: '请选择时间' },{ validateFunction: function (rule, value, data, callback) {const [date1, date2] = value;console.log(date1, date2);if (!date1 && !date2) {callback('请选择时间')} else if (!date1) {callback('请选择开始时间')} else if (!date2) {callback('请选择结束时间')}return true;}}]},]

model: { type: Object, required: true,}, 必填
showSubmitButton: { type: Boolean, default: true,} // 是否显示提交按钮
- @submit 显示提交按钮时，点提交会触发submit方法
@change 表单有数据改变的方法，返回参数：({schema参数, value}, formValue)

setFieldsValue() 设置表单数据方法，setFieldsValue(a: 1)

const handleFormChange = (e, formValue) => {// 设置值dataFormRef.value.setFieldsValue({a: '123123123123'})console.log('数据', formValue);
}

updateSchema() 更新表单schema，传入数组，如下示例：

const updateLocalData = () => {const data = [{text: '男男', value: '1'}, {text: '女女', value: '2'}]dataFormRef.value.updateSchema([{field: 'key2', componentProps: {localData: data}}])
}）