简介

movable-button 是一个悬浮按钮容器，适用于 AI 入口、快捷操作、辅助浮窗等固定在页面上的轻量入口。组件支持拖动、松手后左右吸边、边界限制、位置记忆，并可通过 dragTrigger 控制长按拖动或触摸后立即拖动。

使用方法

局部引入，在页面或组件的 index.json 中配置：

{
  "usingComponents": {
    "movable-button": "/avaui-sub/movable-button/index"
  },
  "componentPlaceholder": {
    "movable-button": "view"
  }
}

基础用法：

<movable-button
  biz-key="contact-entry"
  start="{{start}}"
  bound="{{bound}}"
>
  <view class="entry">AI</view>
</movable-button>

Page({
  data: {
    start: { left: 16, top: 280 },
    bound: { left: 16, top: 88, right: 16, bottom: 34 }
  }
})

代码演示

API

Properties

参数	说明	类型	默认值
bizKey	位置记忆的业务标识；为空时不缓存拖动位置	String	''
start	初始位置，格式为 { left, top }，单位 px	Object	null
bound	拖动边界，格式为 { left, top, right, bottom }，单位 px	Object	null
dragTrigger	拖动触发方式，可选值：longpress / touchstart	String	longpress

Slots

插槽名	说明
default	悬浮按钮内容

External Classes

类名	说明
i-btn-wrap	挂载在组件固定定位容器上，用于调整 z-index、尺寸辅助样式等

参数说明

dragTrigger

值	行为	适用场景
longpress	长按后进入拖动	页面存在滚动、点击等高频手势时，降低误拖动概率
touchstart	触摸后立即进入拖动	明确需要直接拖动的悬浮工具、调试面板、可移动入口

bound

bound 用于限制悬浮按钮可移动范围，单位为 px：

{
  left: 16,
  top: 88,
  right: 16,
  bottom: 34
}

组件会在拖动中、松手吸边、初始位置恢复三个阶段使用同一套边界计算。松手后按钮只会吸附到 bound.left 或 windowWidth - bound.right - buttonWidth，不会越过配置边界。

bizKey 与位置缓存

设置 bizKey 后，组件会在拖动结束时缓存 { left, top }。下次渲染时优先使用缓存位置；如果没有缓存，再使用 start；两者都不存在时使用默认位置 { left: 0, top: 200 }。

使用示例

长按拖动

<movable-button
  biz-key="longpress-entry"
  start="{{start}}"
  bound="{{bound}}"
>
  <view class="entry">AI</view>
</movable-button>

触摸直接拖动

<movable-button
  biz-key="touch-entry"
  drag-trigger="touchstart"
  start="{{start}}"
  bound="{{bound}}"
>
  <view class="entry">AI</view>
</movable-button>

自定义外层样式

<movable-button
  i-btn-wrap="custom-float-wrap"
  start="{{start}}"
  bound="{{bound}}"
>
  <view class="entry">AI</view>
</movable-button>

.custom-float-wrap {
  z-index: 99;
}

注意事项

1. start 和 bound 均使用 px，不支持 rpx 自动换算。
2. 默认 dragTrigger 为 longpress，用于兼容已有调用方的长按拖动行为。
3. touchstart 会在触摸开始时立即进入拖动，如果悬浮入口内部还有点击态，需要确认交互不会互相干扰。
4. 使用 bizKey 时，缓存位置优先级高于 start；如果需要恢复初始位置，应更换 bizKey 或清理对应缓存。
5. 悬浮内容由默认插槽提供，组件只负责外层 fixed 定位、拖动和吸边；按钮尺寸由插槽内容决定。

打开预览