更新记录

1.0.1（2026-10-30）下载此版本

文档

补充单按钮、列表模式及图片、文字、图标展示的使用示例。
补全 Props、ListItem 字段、事件参数和 uni-icons 依赖说明。
说明触摸拖动、初始布局、列表边界与平台验证范围。
本版本为文档完善更新，同步调整插件版本号；组件功能、接口和运行配置未变更。

1.0.0（2025-10-20）下载此版本

初始化第一个版本

平台兼容性

uni-app(4.21)

Vue2	Vue3	Vue3插件版本	Chrome	Chrome插件版本	Safari	app-vue	app-nvue	Android	iOS	鸿蒙
×	√	1.0.0	158.0.8106.0	1.0.0	-	-	-	-	-	-

微信小程序	微信小程序插件版本	支付宝小程序	抖音小程序	百度小程序	快手小程序	京东小程序	鸿蒙元服务	QQ小程序	飞书小程序	小红书小程序	快应用-华为	快应用-联盟
3.0.2	1.0.0	-	-	-	-	-	-	-	-	-	×	×

jf-floating-button

可触摸拖动的悬浮操作按钮，支持单按钮和展开列表两种模式，适用于快捷操作、工具入口等场景。

功能

主按钮支持图片、文字、uni-icons 图标三种展示方式。
触摸拖动时限制主按钮在窗口范围内，并收起操作列表。
列表项支持文字、图片或图标，可分别设置背景颜色；点击列表项后自动收起。
提供点击缩放、列表展开和图标旋转动画。

安装与环境

将本模块放入项目的 uni_modules 目录，启用 easycom 后可直接使用标签。组件基于 Vue 3、TypeScript 和 SCSS。

模块声明的环境要求：HBuilderX ^3.1.0、uni-app ^4.21。package.json 标记支持 Vue 3、Chrome 和微信小程序（基础库最低 3.0.2）；其他平台需自行验证。

使用 type="icon" 或列表项的 icon 字段时，需要安装并确保能够解析 uni-icons。当前模块未在依赖列表中自动声明该依赖；仅使用图片或文字时不需要图标资源。

单按钮示例

<template>
  <jf-floating-button
    type="text"
    text="新建"
    bg-color="#0052d9"
    @click="handleClick"
  />
</template>

<script setup>
const handleClick = () => {
  uni.showToast({ title: '点击了新建', icon: 'none' })
}
</script>

列表模式示例

<template>
  <jf-floating-button
    type="text"
    text="工具"
    mode="list"
    :list-items="actions"
    @list-item-click="handleAction"
  />
</template>

<script setup>
const actions = [
  { text: '新增', bgColor: '#0052d9' },
  { text: '刷新', bgColor: '#009944' }
]
const handleAction = (item, index) => {
  uni.showToast({ title: `${index + 1}. ${item.text}`, icon: 'none' })
}
</script>

图片按钮可设置 type="image" 和 src；图标按钮可设置 type="icon" 和 name。列表模式下图标主按钮固定使用 plusempty，不使用 name。

Props

参数	类型	默认值	说明
type	`'image' / 'text' / 'icon'`	`'image'`	主按钮展示类型
bgColor	string	`'#0052d9'`	主按钮背景颜色
mode	`'button' / 'list'`	`'button'`	单按钮或列表模式
text	string	`'按钮'`	文字按钮文案
listItems	ListItem[]	`[]`	列表模式的操作项
src	string	`''`	主按钮图片；为空时使用模块自带的加号图片
name	string	`'plusempty'`	单按钮图标名称，对应 `uni-icons` 的 `type`

ListItem

字段	类型	必填	说明
text	string	是	操作项文字
src	string	否	图片地址，优先于 `icon` 展示
icon	string	否	`uni-icons` 图标名称
bgColor	string	否	背景颜色；未指定时使用内置循环配色

事件

事件	回调参数	触发时机
click	`(event: Event)`	单按钮模式点击主按钮
listItemClick	`(item: ListItem, index: number)`	点击操作项；索引从 0 开始

模板中可写作 @list-item-click。列表模式点击主按钮仅切换展开状态，不触发 click。

使用注意

主按钮固定为 50px × 50px，初始位置距窗口右侧 30px、底部 100px；当前没有尺寸、初始位置或层级配置接口。
拖动通过触摸事件实现，不提供鼠标拖动、自动吸边、位置持久化或位置变化事件。
列表向主按钮上方展开，不会自动避开窗口边缘；列表较长或按钮靠近顶部时应检查遮挡。
位置边界在挂载时获取，窗口尺寸变化后不会自动重新计算。
无自定义插槽或对外暴露的方法。拖动结束后的点击行为需在目标设备上验证。

本说明根据当前源码整理，平台标记不等同于本次进行了真机测试。