暂无描述

当前项目代码仓暂无内容

flutter_custom_cursor

简介

flutter_custom_cursor 是一个 Flutter 插件，用于直接从内存缓冲区创建和设置自定义鼠标光标。该插件提供了 CursorManager 管理光标生命周期，并通过 FlutterCustomMemoryImageCursor（MouseCursor 子类）将自定义光标应用到界面组件，支持注册、激活和删除光标。

下载安装

进入到工程目录并在 pubspec.yaml 中添加以下依赖：

dependencies:
  flutter_custom_cursor:
    git:
      url: https://gitcode.com/CPF-Flutter/fluttertpc_flutter_custom_cursor.git
      # ref: 根据下方表格选择不同框架适配的TAG版本
      ref: 0.0.4-ohos-1.0.0

执行命令

flutter pub get

TAG 命名规则：原库版本-ohos-版本号-betax，不同 TAG 之间的变更详见 CHANGELOG.OpenHarmony.md。

Flutter 框架版本	TAG 名称	分支名
3.7	0.0.4-ohos-1.0.0	master
3.22	0.0.4-ohos-1.0.0	master
3.35	0.0.4-ohos-1.0.0	master

约束与限制

兼容性

在以下版本中已测试通过：

Flutter: 3.7.12-ohos-1.1.3; DevEco Studio: 5.1.0.828; SDK: 5.0.0(12); ROM: 5.1.0.130 SP8;
Flutter: 3.22.1-ohos-1.0.3; DevEco Studio: 5.1.0.828; SDK: 5.0.0(12); ROM: 5.1.0.130 SP8;
Flutter: 3.35.8-ohos-0.0.1; DevEco Studio: 6.0.2.640; SDK: 6.0.2(22); ROM: 6.0.0.130 SP15;

权限要求

无

使用示例

以下片段展示从资源加载光标图像并注册、应用到 MouseRegion 的最简用法：

import 'dart:typed_data';

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_custom_cursor/cursor_manager.dart';
import 'package:flutter_custom_cursor/flutter_custom_cursor.dart';

late String _cursorName;

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 1. 从 assets 读取 PNG 光标图像
  final ByteData bytes = await rootBundle.load('assets/cursors/data.png');
  final Uint8List cursorBuffer = bytes.buffer.asUint8List();

  // 2. 注册自定义光标，返回光标名称
  _cursorName = await CursorManager.instance.registerCursor(
    CursorData()
      ..name = 'test'
      ..buffer = cursorBuffer
      ..width = 32
      ..height = 32
      ..hotX = 0
      ..hotY = 0,
  );

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('flutter_custom_cursor 示例')),
        body: Center(
          // 3. 通过 FlutterCustomMemoryImageCursor 应用自定义光标
          child: MouseRegion(
            cursor: FlutterCustomMemoryImageCursor(key: _cursorName),
            child: const Text('鼠标悬停在此区域显示自定义光标'),
          ),
        ),
      ),
    );
  }
}

使用说明

1. 光标数据格式

CursorData.buffer 为 Uint8List 类型的光标图像数据。

平台差异：

Windows：buffer 需为 rawBGRA 格式的原始像素数据；

macOS / Linux / OpenHarmony：buffer 需为 PNG 格式的图像数据。

在 OpenHarmony 平台，插件内部通过 image.createImageSource 将 PNG 数据解码为 PixelMap，再调用 pointer.setCustomCursorSync 设置系统光标。

2. 注册光标

通过 CursorManager.instance.registerCursor 注册光标，返回光标名称字符串。

final String cursorName = await CursorManager.instance.registerCursor(
  CursorData()
    ..name = 'circle'
    ..buffer = pngBuffer
    ..width = 48
    ..height = 48
    ..hotX = 24
    ..hotY = 24,
);

返回的 cursorName 与传入的 name 一致，后续设置和删除光标均使用该名称。

3. 设置光标

将 FlutterCustomMemoryImageCursor 作为 MouseRegion 的 cursor 属性，即可在鼠标进入区域时自动激活自定义光标。

MouseRegion(
  cursor: FlutterCustomMemoryImageCursor(key: cursorName),
  child: Container(
    width: 200,
    height: 200,
    color: Colors.yellow,
  ),
)

4. 删除光标

光标不再使用时，通过名称删除以释放资源。

await CursorManager.instance.deleteCursor(cursorName);

删除光标后，引用该名称的 FlutterCustomMemoryImageCursor 将无法再激活光标，需重新注册。

5. 热点（hotspot）设置

hotX 和 hotY 指定光标的点击热点相对于图像左上角的坐标。

// 铅笔光标：热点位于笔尖（图像底部中点）
CursorData()
  ..name = 'pencil'
  ..buffer = pencilPngBuffer
  ..width = 32
  ..height = 48
  ..hotX = 16
  ..hotY = 48,

接口说明

"ohos Support" 列为 yes 表示 ohos 平台支持该属性；no 表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。

FlutterCustomMemoryImageCursor

名称	描述	类型	参数	返回值	ohos Support
key	已注册的光标名称	属性	String	/	yes
createSession	创建并管理光标样式会话	方法	int device	MouseCursorSession	yes
debugDescription	调试输出时显示的字符串信息	方法	/	String	yes

CursorData

名称	描述	类型	参数	返回值	ohos Support
name	光标名称，用于后续设置和删除	属性	String	/	yes
buffer	光标图像数据，OpenHarmony 使用 PNG 格式	属性	Uint8List	/	yes
width	光标图像宽度，单位：像素	属性	int	/	yes
height	光标图像高度，单位：像素	属性	int	/	yes
hotX	热点 X 坐标，从左侧算起	属性	double	/	yes
hotY	热点 Y 坐标，从顶部算起	属性	double	/	yes

CursorManager

名称	描述	类型	参数	返回值	ohos Support
instance	获取 CursorManager 单例实例	属性	/	CursorManager	yes
registerCursor	注册自定义光标，返回光标名称	方法	CursorData data	Future<String>	yes
setSystemCursor	按名称设置当前系统光标	方法	String name	Future<void>	yes
deleteCursor	按名称删除已注册的光标	方法	String name	Future<void>	yes

遗留问题

无

常见问题

1. 光标不显示？

确认 CursorData.buffer 为 PNG 格式数据（OpenHarmony 平台不支持 rawBGRA）。
确认 registerCursor 已执行且返回的名称与 FlutterCustomMemoryImageCursor 的 key 一致。
确认 width 和 height 与实际图像尺寸匹配。

2. 删除光标后程序报错？

删除光标后，引用该名称的 FlutterCustomMemoryImageCursor 无法再激活光标。请在删除前移除相关 MouseRegion，或重新注册光标后再使用。

目录结构

flutter_custom_cursor/
├── lib/                              # Dart 接口实现
│   ├── flutter_custom_cursor.dart    # FlutterCustomMemoryImageCursor 定义
│   └── cursor_manager.dart           # CursorManager 与 CursorData 定义
├── ohos/                             # OpenHarmony 平台实现
│   ├── src/main/ets/
│   │   └── FlutterCustomCursorPlugin.ets  # OHOS 插件实现
│   └── Index.ets                     # 插件入口
├── windows/                          # Windows 平台实现
├── macos/                            # macOS 平台实现
├── linux/                            # Linux 平台实现
├── example/                          # 示例工程
│   ├── lib/main.dart                 # 示例代码
│   └── assets/cursors/               # 光标图像资源
├── pubspec.yaml                      # 包配置
└── CHANGELOG.OpenHarmony.md          # OpenHarmony 适配变更记录

贡献代码

欢迎提交 Issue 和 Pull Request 参与贡献，请遵循贡献指南。

开源协议

本项目基于 The Apache-2.0 License，请自由地享受和参与开源。

项目介绍