前端UI组件跨平台【免费下载链接】uv-uiuv-ui 破釜沉舟之兼容vue32、app、h5、小程序等多端基于uni-app和uView2.x的生态框架支持单独导入开箱即用利剑出击。项目地址https://gitcode.com/gh_mirrors/uv/uv-ui点击查看免费下载导读本文围绕 uv-ui 生态中的uv-upload 上传组件展开系统讲解其在 uni-app 多端项目中处理图片、视频与文件选择的完整方案。你将掌握该组件的全部 props 参数与事件回调的用法理解「选择文件 → 读取前校验 → 大小检查 → 上传回调 → 删除与预览」的底层工作链路并学会结合仓库示例快速落地一个带上传状态、进度反馈与预览能力的功能页面。一、组件定位与适用场景uv-upload是 uv-ui 中用于「上传图片等文件场景」的核心组件见 组件说明文档。它本身不负责真正的网络上传——实际的文件传输仍由开发者基于uni.uploadFile完成组件负责的是更繁琐的前半段工作调用各平台的文件选择能力相册、摄像头、聊天文件等对选中文件做类型格式化、数量与大小校验渲染缩略图网格、上传中遮罩、失败提示、删除按钮与成功角标提供图片全屏预览与视频弹层预览。从 components.config.js 可以看到uv-ui 官方示例将其归类于「表单组件」组示例页面位于 upload.nvue。组件源码主体在 uv-upload.vue共依赖uv-ui-tools、uv-icon、uv-loading-icon、uv-popup四个模块见 package.json。二、快速上手基础用法组件支持easycom 规范在 uni-app 项目中无需手动注册模板中直接使用即可template uv-upload :fileListfileList afterReadafterRead deletedeletePic name1 multiple :maxCount10 /uv-upload /template script export default { data() { return { fileList: [] } }, methods: { // 删除图片 deletePic(event) { this.fileList this.fileList.filter((item, index) { return index ! event.index }) }, // 新增图片 async afterRead(event) { // 当设置 multiple 为 true 时, file 为数组格式否则为对象格式 let lists [].concat(event.file) let fileListLen this.fileList.length lists.map((item) { this.fileList.push({ ...item, status: uploading, message: 上传中 }) }) // 此写法可以避免使用老写法在 VUE3 中不更新 // #ifdef VUE3 this.fileList this.fileList.filter((item, index) { return index 0 }) // #endif for (let i 0; i lists.length; i) { const result await this.uploadFilePromise(lists[i].url) let item this.fileList[fileListLen] this.fileList.splice(fileListLen, 1, Object.assign(item, { status: success, message: , url: result })) fileListLen } }, uploadFilePromise(url) { return new Promise((resolve, reject) { let a uni.uploadFile({ url: http://www.example.com/upload, // 仅为示例非真实的接口地址 filePath: url, name: file, formData: { user: test }, success: (res) { setTimeout(() { resolve(res.data.data) }, 1000) } }); }) } } } /script关键约定双向数据流由你维护组件是纯展示 事件驱动的fileList并不被组件内部直接修改选择文件后组件只派发afterRead事件你必须在回调中把新文件追加进自己的fileList点击删除只派发delete事件并携带index由你在回调中从fileList里移除对应项。组件通过watch深度监听fileList见 uv-upload.vue变化后自动调formatFileList()重算缩略图网格与剩余可选数量。示例中把列表先标记为status: uploading, message: 上传中上传完成后替换为status: success正是为了驱动组件渲染状态遮罩。三、参数配置全解析所有参数定义在 props.js并可通过uni.$uv.props.upload做全局默认配置覆盖。完整参数表如下参数类型默认值说明acceptStringimage接受的文件类型可选all/media/image/file/videocaptureString | Array[album, camera]图片或视频拾取模式accept为 image 时追加camera可允许直接调起摄像头compressedBooleantrueaccept为 video 时生效是否压缩视频cameraStringbackaccept为 video 时生效可选back或frontmaxDurationNumber60accept为 video 时生效拍摄视频最长时长秒uploadIconStringcamera-fill上传区域的图标只能使用内置图标uploadIconColorString#D3D4D6上传区域图标的颜色useBeforeReadBooleanfalse是否开启「文件读取前事件」模式afterReadFunctionnull读取后的处理函数等价于afterRead事件beforeReadFunctionnull读取前的处理函数等价于beforeRead事件previewFullImageBooleantrue是否开启图片预览功能previewFullVideoBooleantrue是否开启视频预览功能maxCountString | Number52最大上传数量disabledBooleanfalse是否禁用组件imageModeStringaspectFill预览图的裁剪模式与image的mode属性一致nameString标识符可在回调函数的第二项参数中获取sizeTypeArray[original, compressed]所选图片的尺寸可选original/compressedmultipleBooleanfalse是否开启图片多选部分安卓机型不支持deletableBooleantrue是否展示删除按钮maxSizeString | NumberNumber.MAX_VALUE文件大小限制单位为 bytefileListArray[]已上传文件列表uploadTextString上传区域的提示文字widthString | Number80预览区域与选择按钮区域宽度heightString | Number80预览区域与选择按钮区域高度previewImageBooleantrue是否在上传完成后展示预览图customStyleObject-组件自定义样式内部经$uv.addStyle合并几个需要留意的参数行为maxCount默认 52组件通过isInCount lists.length maxCount控制「」按钮是否继续显示传入 52 是给微信小程序chooseMedia等接口的上限兜底留出的余量uv-upload.vue。multiple与maxCount的组合选择器内部对单次选择数量做了二次收敛图片/媒体接口单次最多min(maxCount, 9)文件接口为multiple ? maxCount : 1见 utils.js。maxSize单位是字节例如限制 2MB 应传2 * 1024 * 1024。deletable支持逐项覆盖fileList中每个 item 可携带布尔型deletable字段优先级高于组件级配置uv-upload.vuechangelog 中 1.0.6 版本专门修复了「动态设置deletable为 false 不生效」的问题。四、事件与回调组件在 uv-upload.vue 中声明了 6 个事件事件触发时机回调参数要点error文件选择失败用户取消、系统异常等底层选择接口的错误对象beforeRead文件读取前需开启useBeforeRead{ file, name, index, callback }callback(ok)可异步放行/拦截oversize文件超出maxSize限制{ file, name, index }afterRead文件读取后{ file, name, index }multiple时file为数组delete点击删除按钮{ file, name, index }clickPreview点击预览图片或视频均触发文件 item 与{ name, index }三种拦截/校验姿势从源码onBeforeRead/onAfterReaduv-upload.vue可以看到组件提供的校验链路beforeRead函数返回false则中断返回 Promise 则等待其 resolve 后继续useBeforeRead事件模式组件会把callback一并传入事件业务侧异步调用callback(false)即可拦截该文件oversize事件文件大小超过maxSize时触发并终止本次读取流程不会进入afterRead。三者可按需组合例如先拦截非图片文件再在oversize中提示「文件过大」。五、实战案例六种典型用法官方示例页 upload.nvue 提供了可直接对照的完整代码这里提炼其核心配置场景关键配置基础用法:fileListfileList1multiple:maxCount10上传视频acceptvideo选择走uni.chooseVideo文件预览:previewFullImagetrue点击缩略图全屏预览隐藏上传按钮当fileList长度达到maxCount时按钮自动消失如:maxCount2限制上传数量:maxCount3超出后不再显示「」按钮自定义上传样式width250height150 默认插槽内放置自定义image此时仍保留全部选择、上传与删除逻辑示例页通过name1name6区分六组互不干扰的文件列表并在回调中借助event.name定位目标数组这一「多实例区分」技巧在多表单场景下非常实用。六、上传链路源码级解析组件把「选择 → 读取 → 校验 → 展示 → 删除/预览」拆成了清晰的方法链整体流程如下用户点击上传区 │ ▼ chooseFile() // 按 accept 分发到平台选择接口 │ Promise resolve ▼ onBeforeRead(file) // beforeRead 函数 / useBeforeRead 事件可拦截 │ ▼ onAfterRead(file) // 检查 maxSize → 触发 oversize 或 afterRead │ ▼ 业务侧 afterRead 回调 // 开发者调用 uni.uploadFile 真正上传 │ ▼ 更新 fileList 的 status // uploading → success / failed组件 watch 重绘选择器分发逻辑核心实现在 utils.js 的chooseFile()按accept走不同底层 APIaccept底层 API平台限制imageuni.chooseImage全端mediawx.chooseMedia仅微信小程序videouni.chooseVideo全端filewx.chooseMessageFile微信/uni.chooseFileH5仅微信小程序与 H5且 H5 需 HBuilderX 2.9.9其他保底按all类型选取全部文件同上各分支还会把原生返回结果统一格式化为{ url, thumb, size, type, name }结构的标准文件对象formatImage/formatVideo/formatMedia/formatFile这正是afterRead回调里event.file的数据来源。类型识别与状态渲染组件在formatFileList()中通过accept或 URL 后缀判断isImage/isVideouv-upload.vue底层正则来自 test.js图片匹配jpeg|jpg|gif|png|svg|webp|jfif|bmp|dpg视频匹配mp4|mpg|mpeg|dat|asf|avi|rm|rmvb|mov|wmv|flv|mkv|m3u8因此本地 blob 地址无法识别类型时会优先以accept判断渲染层依据item.status显示三种状态uploading旋转 loading、failed叉号 message、success右下角对勾角标。其中成功角标在 APP-NVUE 下使用内置 base64 图片其余平台用 CSS 绘制三角形源码注释中明确说明了这一平台差异uv-upload.vue。预览能力图片调用uni.previewImage并先过滤出所有图片项、以当前点击项作为current起始位置uv-upload.vue视频交给内置的 uv-preview-video.vue通过uv-popup弹层承载video并默认自动播放。七、accept 的平台约束重要不同accept值对运行平台有硬性要求组件通过 mixin.js 在accept变化时主动error提示非微信小程序平台不允许配置all或media非微信小程序且非 H5 平台不允许配置file。也就是说file与media类型具有较强的平台排他性。建议在跨端项目中按条件分支配置accept例如#ifdef MP-WEIXIN下才启用file并在oversize/error回调中做降级处理。组件在 package.json 中声明的兼容矩阵覆盖 Vue2/Vue3、Appvue/nvue、H5PC 与移动端主流浏览器以及微信、阿里、百度、字节跳动、QQ 等小程序端。八、样式定制要点组件样式基于 SCSS 变量体系uv-upload.vue常用可覆盖变量包括预览格尺寸$uv-upload-preview-border-radius、$uv-upload-preview-margin按钮区$uv-upload-button-bgColor、$uv-upload-button-border-radius、$uv-upload-hover-bgColor、$uv-upload-disabled-opacity删除角标$uv-upload-deletable-bgColor状态遮罩$uv-upload-status-bgColor默认rgba(0, 0, 0, 0.5)。此外uploadIcon/uploadText/width/height/customStyle以及默认插槽自定义整个上传按钮区域已覆盖绝大多数 UI 定制诉求一般无需改动组件源码。九、版本演进与已知修复根据 changelog.md组件自 1.0.02023-05-10发布以来的关键演进如下1.0.1优化依赖组件导入即可使用无需全局引入1.0.2fileList的 watch 增加deep深层字段变更也能正确重绘1.0.3去除插槽判断规避部分平台显示异常1.0.4修复图片预览位置错误、视频预览不生效、视频宽高修改不生效1.0.5新增uv-popup依赖视频预览弹层底层1.0.6修复动态设置deletable为 false 不生效。这些修复记录对排查旧版本问题有直接参考价值若你遇到预览定位偏差、视频弹层无法打开或删除按钮无法动态隐藏可优先核对当前依赖版本是否 ≥ 对应修复版本。结语uv-upload的价值在于把「多端文件选择 校验 状态化缩略图 预览」这套极易踩平台差异的样板逻辑收敛进一个组件而把「真正上传」的控制权完整交还开发者。基于本文的参数表、事件链与示例代码你可以直接落地带上传进度、失败重试、数量/大小限制与自定义样式的能力页面需要更细的边界行为时可继续研读 uv-upload.vue、utils.js 与 upload.nvue 三份核心源码。赞分享前端UI组件跨平台【免费下载链接】uv-uiuv-ui 破釜沉舟之兼容vue32、app、h5、小程序等多端基于uni-app和uView2.x的生态框架支持单独导入开箱即用利剑出击。项目地址https://gitcode.com/gh_mirrors/uv/uv-ui点击查看免费下载相关推荐cube-ui Upload 组件完全指南文件对象模型、上传配置与源码级解析cube ui Upload 组件完全指南文件对象模型、上传配置与源码级解析 本指南以 cube ui 官方文档 document/components/do前端UI组件移动开发uv-ui uv-tags 标签组件实战指南多端标记与选择的完整参数解析uv ui uv tags 标签组件实战指南多端标记与选择的完整参数解析 uv ui 的 uv tags 标签组件位于 uni_modules/uv tag前端UI组件跨平台uv-picker 选择器组件全解基于 uv-ui 实现单列、多列与多列联动选择uv picker 选择器组件全解基于 uv ui 实现单列、多列与多列联动选择 导读 uv picker 是 uv ui 生态中用于「单列、多列、多列联动」前端UI组件跨平台上一篇X-BUILD项目结构解析理解大型Vue3应用的最佳组织方式下一篇Awesome Claude Skills插件开发实战技能发布与推广完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考