# FloatingButton

**Repository Path**: chenshipeng0914/floating-button

## Basic Information

- **Project Name**: FloatingButton
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-08-27
- **Last Updated**: 2025-12-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🏆 FloatingButton4HarmonyOS

**原生鸿蒙悬浮按钮组件，功能强大，易于使用**

一个基于HarmonyOS原生开发的高度可定制悬浮按钮组件，支持自动贴边、自动隐藏、拖拽操作、自定义内容等丰富功能。

[![HarmonyOS](https://img.shields.io/badge/HarmonyOS-Native-blue)](https://www.harmonyos.com/)
[![ArkTS](https://img.shields.io/badge/Language-ArkTS-orange)](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/arkts-get-started-0000001504769321-V3)
[![License](https://img.shields.io/badge/License-MulanPSL2-green)](http://license.coscl.org.cn/MulanPSL2)

## ✨ 特性亮点

- 🎯 **智能交互** - 支持自动贴边、自动隐藏、拖拽阈值控制
- 🎨 **高度定制** - 21个配置参数，6种事件回调，满足各种场景需求  
- 🧩 **灵活内容** - 支持自定义组件内容，不仅限于图片
- 📱 **用户友好** - 默认右下角位置，符合用户操作习惯
- ⚡ **性能优化** - 智能定时器管理，低资源占用
- 🔧 **开箱即用** - 简单配置即可使用，像ImageView一样简单

## 🚀 快速开始

### 安装

```bash
ohpm i @csp/floatingbutton
```

> OpenHarmony ohpm 环境配置等更多内容，请参考 [如何安装 OpenHarmony ohpm 包](https://ohpm.openharmony.cn/#/cn/help/downloadandinstall)

### 基本使用

```arkts
import { FloatingButton } from '@csp/floatingbutton';

// 在你的组件中使用
FloatingButton({
  content: () => {
    Text('⚙️')
      .fontSize(24)
      .fontColor(Color.White)
  },
  onClickEvent: () => {
    // 点击事件处理
    return true
  }
})
```

## 📝 API 文档

### 基础属性

| 属性名 | 类型 | 必需 | 默认值 | 说明 |
|:---------|:-----|:-----|:-------|:----|
| `radius` | `number` | ✖️ | `25` | 悬浮按钮半径 |
| `opacityWhenVisible` | `number` | ✖️ | `1.0` | 可见状态透明度 |
| `opacityWhenHidden` | `number` | ✖️ | `0.5` | 隐藏状态透明度 |
| `marginWhenShow` | `number` | ✖️ | `25` | 显示时的边距 |

### 位置配置

| 属性名 | 类型 | 必需 | 默认值 | 说明 |
|:---------|:-----|:-----|:-------|:----|
| `initialLeft` | `number` | ✖️ | `-1` | 初始 X 坐标（-1 表示自动） |
| `initialTop` | `number` | ✖️ | `-1` | 初始 Y 坐标（-1 表示自动） |

### 行为控制

| 属性名 | 类型 | 必需 | 默认值 | 说明 |
|:---------|:-----|:-----|:-------|:----|
| `enableAutoEdge` | `boolean` | ✖️ | `true` | 开启自动贴边 |
| `enableAutoHide` | `boolean` | ✖️ | `true` | 开启自动隐藏 |
| `enableDragOutOfBounds` | `boolean` | ✖️ | `true` | 允许拖拽超出边界 |
| `enableDragWhenHidden` | `boolean` | ✖️ | `true` | 隐藏时允许拖拽 |
| `dragThreshold` | `number` | ✖️ | `5` | 拖拽阈值（vp） |

### 时间配置

| 属性名 | 类型 | 必需 | 默认值 | 说明 |
|:---------|:-----|:-----|:-------|:----|
| `autoEdgeDelayTime` | `number` | ✖️ | `300` | 贴边延迟时间（ms） |
| `autoHideDelayTime` | `number` | ✖️ | `3000` | 隐藏延迟时间（ms） |
| `edgeAnimationDuration` | `number` | ✖️ | `300` | 贴边动画时长（ms） |
| `showAnimationDuration` | `number` | ✖️ | `500` | 显示动画时长（ms） |
| `hideAnimationDuration` | `number` | ✖️ | `1000` | 隐藏动画时长（ms） |

### 内容配置

| 属性名 | 类型 | 必需 | 默认值 | 说明 |
|:---------|:-----|:-----|:-------|:----|
| `content` | `@BuilderParam` | ✖️ | `undefined` | 自定义内容组件 |
| `image` | `Resource` | ✖️ | `$r('app.media.app_icon')` | 默认图片资源 |

### 事件回调

| 事件名 | 类型 | 说明 |
|:--------|:-----|:----|
| `onClickEvent` | `() => boolean` | 点击事件，返回 false 可阻止后续事件 |
| `onEdgeEvent` | `() => boolean` | 贴边事件，返回 false 可阻止后续事件 |
| `onHideEvent` | `() => boolean` | 隐藏事件，返回 false 可阻止后续事件 |
| `onShowEvent` | `() => boolean` | 显示事件，返回 false 可阻止后续事件 |
| `onDragStartEvent` | `() => void` | 拖拽开始事件 |
| `onDragEndEvent` | `() => void` | 拖拽结束事件 |

### 演示
![演示](./演示.gif)

## 💡 使用示例

### 基础使用 - 图片悬浮按钮

```arkts
import { FloatingButton } from '@csp/floatingbutton';
import { promptAction } from '@kit.ArkUI';

FloatingButton({
  image: $r('app.media.startIcon'),          // 图片资源
  radius: 25,                                // 悬浮按钮半径
  marginWhenShow: 25,                        // 显示时的边距
  enableAutoEdge: true,                      // 开启自动贴边
  enableAutoHide: true,                      // 开启自动隐藏
  opacityWhenHidden: 0.5,                    // 隐藏时的透明度
  onClickEvent: (): boolean => {
    promptAction.showToast({ message: '点击了悬浮按钮' });
    return true
  }
})
```

### 高级使用 - 自定义内容悬浮按钮

```arkts
import { FloatingButton } from '@csp/floatingbutton';
import { promptAction } from '@kit.ArkUI';
import { webview } from '@kit.ArkWeb';

@Entry
@Component
struct Index {
  controller: WebviewController = new webview.WebviewController();

  @Builder
  CustomButton() {
    Column() {
      Text('⚙️')
        .fontSize(24)
        .fontColor(Color.White)
      Text('设置')
        .fontSize(10)
        .fontColor(Color.White)
        .margin({ top: 2 })
    }
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
    .width('100%')
    .height('100%')
    .backgroundColor('#007AFF')
    .borderRadius(30)
  }

  build() {
    Stack() {
      // 业务内容
      Web({ src: "www.baidu.com", controller: this.controller })
        .width('100%')
        .height('100%')

      // 悬浮按钮
      FloatingButton({
        radius: 30,                                    // 悬浮按钮半径
        marginWhenShow: 25,                            // 显示时的边距
        enableAutoEdge: true,                          // 开启自动贴边
        enableAutoHide: false,                         // 关闭自动隐藏
        opacityWhenHidden: 0.5,                        // 隐藏时的透明度
        dragThreshold: 8,                              // 拖拽阈值
        // 延迟时间配置
        autoEdgeDelayTime: 500,                        // 贴边延迟时间
        autoHideDelayTime: 2000,                       // 隐藏延迟时间
        // 动画时长配置
        edgeAnimationDuration: 250,                    // 贴边动画时长
        showAnimationDuration: 400,                    // 显示动画时长
        hideAnimationDuration: 800,                    // 隐藏动画时长
        // 事件回调
        onClickEvent: (): boolean => {
          promptAction.showToast({ message: '点击了悬浮按钮' });
          if (this.controller.accessStep(-1)) {
            this.controller.backward();
          }
          return true
        },
        onEdgeEvent: (): boolean => {
          promptAction.showToast({ message: '我贴边了' });
          return true
        },
        onHideEvent: (): boolean => {
          promptAction.showToast({ message: '我隐藏了' });
          return true
        },
        onShowEvent: (): boolean => {
          promptAction.showToast({ message: '我显示了' });
          return true
        },
        onDragStartEvent: () => {
          console.info('开始拖拽悬浮按钮')
        },
        onDragEndEvent: () => {
          console.info('结束拖拽悬浮按钮')
        },
        // 自定义内容组件
        content: () => {
          this.CustomButton()
        }
      })
        .hitTestBehavior(HitTestMode.None)             // 点击事件穿透
        .width("100%")
    }
    .height('100%')
    .width('100%')
  }
}
```

### 📚 完整示例

更多完整示例请见开源仓库：

- [📦 Gitee 地址](https://gitee.com/chenshipeng0914/floating-button)

## 🌏 仓库地址

- [📦 Gitee 地址](https://gitee.com/chenshipeng0914/floating-button)

## 🛠️ 项目结构

```
floating-button4-harmony-os/
├── floating-button/             # 核心组件库
│   ├── src/main/ets/pages/      # 组件源码
│   │   └── FloatingButton.ets   # 悬浮按钮组件
│   ├── Index.ets                # 导出文件
│   └── README.md                # 组件说明文档
├── entry/                       # 示例应用
│   └── src/main/ets/pages/     
│       └── Index.ets            # 使用示例
├── README.md                    # 项目主文档
└── oh-package.json5             # 项目配置
```

## 🔧 系统要求

- **HarmonyOS**: API 12+
- **DevEco Studio**: 4.0+
- **ArkTS**: 支持
- **SDK**: OpenHarmony SDK

## 📋 更新日志

### v2.0.0 (最新)
- 🎉 组件重命名：`FloatBall` → `FloatingButton`
- 🚀 新增自定义内容支持（`@BuilderParam`）
- ⚡ 优化动画性能和交互体验
- 📝 完善属性命名规范
- 🐛 修复自动贴边逻辑问题
- 📚 完善文档和示例代码

## 🤝 沟通与交流

如果您在使用过程中遇到任何问题或有任何建议，欢迎通过以下方式联系：

- 📝 [Issue 反馈](https://gitee.com/chenshipeng0914/floating-button/issues)
- 📧 邮箱联系（通过 Gitee 页面）

## ⚙️ 开发指南

### 本地开发

1. **克隆项目**
   ```bash
   git clone https://gitee.com/chenshipeng0914/floating-button.git
   cd floating-button
   ```

2. **使用 DevEco Studio 打开项目**

3. **运行示例应用**
   - 选择 `entry` 模块
   - 点击运行按钮

### 贡献代码

欢迎大家为这个项目做出贡献！请遵循以下步骤：

1. Fork 这个项目
2. 创建你的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交你的修改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

## 🙏 致谢

本项目基于 [sd1sd2](https://blog.csdn.net/sd1sd2) 的优秀工作进行扩展和完善。

- **原始实现参考**: [HarmonyOS 悬浮球组件实现](https://blog.csdn.net/sd1sd2/article/details/139812386)
- **原作者贡献**: 提供了基础的拖动功能实现思路和核心逻辑
- **我们的扩展**: 在原有基础上增加了自动贴边、自动隐藏、自定义内容、丰富的配置参数等功能

感谢原作者的开源精神和技术分享，为 HarmonyOS 生态的发展做出了贡献！ 🎉

## 📜 开源协议

本项目基于 [MulanPSL2](http://license.coscl.org.cn/MulanPSL2) 开源协议发布。

在使用、修改或分发本项目代码时，请务必遵守相关协议要求，并注明出处。

## 🚀 参考资源

- [HarmonyOS 官方文档](https://developer.harmonyos.com/)
- [ArkTS 语言指南](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/arkts-get-started-0000001504769321-V3)
- [原始参考实现](https://blog.csdn.net/sd1sd2/article/details/139812386) - 原文实现了拖动功能，我们在此基础上封装了更多功能

---

<p align="center">
  ❤️ 感谢使用 FloatingButton4HarmonyOS！
  <br>
  如果这个项目对您有帮助，请给我们一个 ⭐ Star！
</p>