更新记录

1.0.0（2025-08-09）

初稿

平台兼容性

uni-app(4.72)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
- - - - - - - - -
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 快应用-华为 快应用-联盟
- - - - - - - - - - -

uni-app x(4.74)

Chrome Safari Android iOS 鸿蒙 微信小程序
√ √ √ √ √ √

组件库说明文档

一、布局类组件

1. aries-fluid（流式布局组件）

概述

  • 文件路径：@/subs/components/aries-fluid/aries-fluid.uvue
  • 功能：自适应流式布局组件，可根据容器宽度、元素边距及最大显示数量，自动计算每行显示的元素数量，实现卡片类元素的灵活排列。

核心特性

  • 自动适配容器宽度，动态调整每行元素数量
  • 支持自定义元素边距与最大显示数量
  • 通过插槽实现内容定制，适配多场景
  • 支持多端适配（H5、APP等）

主要属性

属性名 类型 默认值 说明
marginLeft number 10 元素左侧外边距（单位：px）
marginRight number 10 元素右侧外边距（单位：px）
maxCount number 3 每行最多显示的元素数量（实际数量会自动调整）

插槽说明

插槽名 说明 传递参数
header 用于定义分组头部内容（如标题、说明等） -
default 用于定义流式布局的主体内容（如卡片、按钮等） fluidStyle：组件计算出的元素样式（需绑定到子元素）

使用场景

适用于表单列表、功能入口、数据卡片等需要自适应布局的场景。

二、数据展示类组件

2. DataList（数据列表组件）

概述

  • 文件路径：components/data-list/data-list.vue
  • 功能：实现支持滚动加载、下拉刷新、数据统计的分页列表组件，自动管理分页数据与加载状态。

核心特性

  • 滚动到底部自动加载下一页数据
  • 下拉刷新获取最新数据
  • 显示数据统计信息（总条数/已加载/剩余）
  • 提供滚动到顶部/底部快捷按钮
  • 错误状态处理与重试机制

主要属性

属性名 类型 默认值 说明
api Function - 获取分页数据的API函数（参数为分页配置，返回PageContent）
pageSize number 10 每页数据条数
containerHeight string 100% 列表容器高度
immediateLoad boolean true 是否初始加载数据
showDataStats boolean true 是否显示数据统计提示
paramPageNum string "page" 分页参数中页码的键名
paramPageSize string "size" 分页参数中每页条数的键名

主要事件

事件名 说明 回调参数
loadSuccess 数据加载成功时触发 加载的分页数据
loadError 数据加载失败时触发 错误信息
scrollToLower 滚动到底部时触发 -
dataChange 数据列表变更时触发 最新的扁平化数据列表

暴露方法

  • refreshData()：刷新数据
  • loadNextPage()：加载下一页
  • scrollToTop()：滚动到顶部
  • scrollToBottom()：滚动到底部
  • removeItem()：移除列表项

使用场景

需展示大量分页数据的列表页（如订单列表、消息列表）。

三、交互类组件

3. ContextMenus（上下文菜单组件）

概述

  • 文件路径：components/context-menus/context-menus.vue
  • 功能：提供右键或点击触发的上下文菜单，支持自定义菜单项与位置计算。

核心特性

  • 支持右键（H5）或点击触发菜单
  • 自动根据点击位置计算菜单显示位置（避免超出屏幕）
  • 点击菜单项后自动关闭菜单
  • 支持自定义菜单项列表

主要属性

属性名 类型 默认值 说明
contextMenus string[] - 菜单项文本列表
dataId string - 绑定的数据ID，用于标识当前操作的项

主要事件

事件名 说明 回调参数
current 点击菜单项时触发 { item: 菜单项文本, currentData: 绑定的dataId }

暴露方法

  • showPopupMenus(e: UniTouchEvent)：手动触发菜单显示（需传入触摸事件对象）

使用场景

需要为列表项、卡片等元素提供右键/点击操作菜单的场景（如删除、编辑、详情）。

四、表单类组件

4. AriesFormApply（表单申请组件）

概述

  • 文件路径：components/aries-form/apply.vue
  • 功能：基于form-create-mobile的表单申请组件，支持表单展示、暂存与提交。

核心特性

  • 动态渲染表单规则（formRule）
  • 表单验证（通过fApi.validate()）
  • 支持“暂存”和“提交”两种操作
  • 适配弹窗式页面布局

主要属性

  • 依赖oaform传入表单配置（包含formRule、formName等）
  • 内部使用form-create-mobile的rule和option配置表单

暴露方法

  • show(data: IActivitiForm)：显示表单弹窗
  • close()：关闭表单弹窗

使用场景

OA系统、审批流程中的表单填写与提交场景（如请假申请、报销申请）。

5. AriesDatepicker（日期选择器组件）

概述

  • 文件路径：components/aries-datepicker/aries-datepicker.vue
  • 功能：支持日期、日期时间、日期范围、日期时间范围的选择器。

核心特性

  • 支持四种选择类型：date（日期）、datetime（日期时间）、daterange（日期范围）、datetimerange（日期时间范围）
  • 可配置最小/最大可选日期
  • 自动过滤无效年月日后的可选值
  • 支持清除已选值与自定义按钮文本

主要属性

属性名 类型 默认值 说明
type string - 选择类型（date/datetime/daterange/datetimerange）
modelValue string\|string[] - 绑定值（单个日期为字符串，范围为数组）
placeholder string - 单个日期占位符
startPlaceholder/endPlaceholder string - 范围选择的开始/结束占位符
minDate/maxDate string - 最小/最大可选日期
clearable boolean - 是否支持清除

主要事件

事件名 说明 回调参数
update:modelValue 选中值变化时触发 选中的日期（字符串或数组）
confirm 确认选择时触发 选中的日期（字符串或数组）
cancel 取消选择时触发 -

使用场景

需要选择日期或日期范围的表单场景（如筛选时间、设置有效期）。

五、工具类组件

6. AriesDateformat（日期格式化组件）

概述

  • 文件路径：components/aries-dateformat/aries-dateformat.vue
  • 功能：格式化日期为相对时间（如“刚刚”）或指定格式的字符串。

核心特性

  • 支持时间戳（10位/13位）、日期字符串、Date对象作为输入
  • 自动计算相对时间（如“3分钟前”“1小时前”）
  • 可自定义时间阈值与格式化模板
  • 输入无效时显示“无效日期”

主要属性

属性名 类型 默认值 说明
date number\|string\|Date - 需格式化的日期
threshold number[] [60000, 3600000] 时间阈值（毫秒），分别对应“分钟级”“小时级”
format string "yyyy-MM-dd hh:mm" 完整日期格式模板（支持yyyy/MM/dd/hh/mm）

使用场景

需展示相对时间（如消息时间、动态发布时间）或格式化日期的场景。

7. CameraUpload（相机上传组件）

概述

  • 文件路径：components/camera-upload/camera-upload.vue
  • 功能：支持拍照或从相册选择图片上传、预览的组件。

核心特性

  • 支持相机拍摄或相册选择图片
  • 图片上传状态提示（加载中/成功/失败）
  • 已上传图片预览功能
  • 节流处理避免重复操作

主要属性

属性名 类型 默认值 说明
modelValue Object - 图片信息（id/name/hasImage等）
getImageApi Function - 获取图片URL的API函数
saveApi Function - 保存图片信息的API函数
showUpdate boolean true 是否显示上传按钮
width/height number 50/100 图片展示区域的宽/高（px）

主要事件

事件名 说明 回调参数
update:modelValue 图片信息更新时触发 最新的图片信息对象
update:refreshPicture 图片刷新时触发 刷新标识（随机数）

使用场景

需要上传图片的表单或信息展示场景（如头像上传、证件上传）。

8. 头像裁剪组件（avatar-cropper）

概述

  • 用于头像上传和裁剪的组件，支持从相册选择或拍摄照片，并提供可视化裁剪功能，最终返回裁剪后的图片数据。

组件属性（Props）

属性名 类型 默认值 说明
titleBackground string - 标题栏背景色
saveLoading string - 保存按钮加载状态文本
selectButtonText string - 选择按钮文本
selectButtonColor string - 选择按钮文字颜色
selectButtonBackgroundColor string - 选择按钮背景色
saveButtonText string "确定" 保存按钮文本
saveButtonColor string - 保存按钮文字颜色
saveButtonBackgroundColor string "#FF2E80" 保存按钮背景色
image string - 初始图片路径
fileType string - 文件类型
quality number 1 图片质量（0-1之间）

组件事件（Events）

事件名 参数 说明
dataUrl string 裁剪完成后触发，返回裁剪后的图片base64数据

组件方法（Exposed）

方法名 参数 说明
show - 显示裁剪弹窗
close - 关闭裁剪弹窗

功能说明

  1. 图片选择：支持拍照获取新照片或从相册选择已有照片
  2. 图片裁剪：提供可视化裁剪区域，支持横向和纵向滚动调整裁剪位置，保持图片原始比例
  3. 交互流程：调用show()方法显示裁剪组件，选择图片后进入裁剪界面，调整裁剪区域后点击保存按钮，通过dataUrl事件获取裁剪结果

使用场景

头像上传与裁剪场景，如用户中心头像设置功能。

联系作者

  • VX：haijian_guo

隐私、权限声明

1. 本插件需要申请的系统权限列表：

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

无

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

评论列表 撰写评论 向官方投诉

暂无用户评论。