RNFloatingBubble

一个可拖拽的浮动气泡组件，支持显示图片、标题和描述，适用于 React Native 应用。

特性

• 🔄 可拖拽的浮动气泡，支持限制拖拽方向
• 📱 支持显示图片、标题和描述
• 🎨 支持自定义内容和样式
• 🧲 支持磁吸效果（吸附到屏幕边缘）
• 🌐 支持国际化（英语、中文、意大利语、日语）
• 📐 支持自定义位置和边距
• 🪶 轻量级，低依赖

安装

# 使用 npm
npm install @cniot/rn-floating-bubble

# 使用 yarn
yarn add @cniot/rn-floating-bubble

必要依赖

本组件依赖以下库，请确保它们已安装：

npm install react-native-gesture-handler react-native-reanimated
# 如果需要国际化支持
npm install react-i18next i18next

使用方法

基本用法

import React from 'react';
import { View } from 'react-native';
import { RNFloatingBubble } from '@cniot/rn-floating-bubble';

const App = () => {
  return (
    <View style={{ flex: 1 }}>
      <RNFloatingBubble
        imageSource={require('./assets/logo.png')}
        title="ATM"
        onPress={() => console.log('气泡被点击了！')}
      />
    </View>
  );
};

export default App;

自定义位置和样式

import React from 'react';
import { View } from 'react-native';
import { RNFloatingBubble } from '@cniot/rn-floating-bubble';

const App = () => {
  return (
    <View style={{ flex: 1 }}>
      <RNFloatingBubble
        imageSource={require('./assets/logo.png')}
        title="ATM Location"
        description="Tap to view details"
        x={20}
        y={100}
        bubbleStyle={{ backgroundColor: '#003D78' }}
        titleStyle={{ color: '#FFFFFF', fontWeight: 'bold' }}
        descriptionStyle={{ color: '#CCCCCC' }}
      />
    </View>
  );
};

export default App;

拖拽方向和磁吸效果

import React from 'react';
import { View, Text } from 'react-native';
import { RNFloatingBubble } from '@cniot/rn-floating-bubble';

const App = () => {
  return (
    <View style={{ flex: 1 }}>
      {/* 水平方向拖拽 */}
      <RNFloatingBubble
        imageSource={require('./assets/logo.png')}
        title="水平拖拽"
        dragDirection="horizontal"
        x={20}
        y={100}
      />

      {/* 垂直方向拖拽 */}
      <RNFloatingBubble
        imageSource={require('./assets/logo.png')}
        title="垂直拖拽"
        dragDirection="vertical"
        x={150}
        y={100}
      />

      {/* 启用磁吸效果 */}
      <RNFloatingBubble
        imageSource={require('./assets/logo.png')}
        title="磁吸效果"
        description="拖拽后会吸附到边缘"
        magneticEdges={true}
        x={20}
        y={200}
      />
    </View>
  );
};

export default App;

自定义内容

import React from 'react';
import { View, Text, Image } from 'react-native';
import { RNFloatingBubble } from '@cniot/rn-floating-bubble';

const App = () => {
  return (
    <View style={{ flex: 1 }}>
      <RNFloatingBubble x={20} y={100}>
        <View style={{ alignItems: 'center', padding: 10 }}>
          <Image source={require('./assets/logo.png')} style={{ width: 80, height: 80 }} />
          <Text style={{ color: 'white', marginTop: 10 }}>自定义内容</Text>
        </View>
      </RNFloatingBubble>
    </View>
  );
};

export default App;

国际化支持

组件内部支持国际化，但也可以与应用程序的 i18next 实例集成：

import React from 'react';
import { View } from 'react-native';
import { RNFloatingBubble } from '@cniot/rn-floating-bubble';
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';

// 初始化i18next
i18n.use(initReactI18next).init({
  resources: {
    en: {
      translation: {
        floatingBubble: {
          atmLocation: 'ATM Location',
          tapForDetails: 'Tap for details',
        },
      },
    },
    zh: {
      translation: {
        floatingBubble: {
          atmLocation: 'ATM位置',
          tapForDetails: '点击查看详情',
        },
      },
    },
  },
  lng: 'zh',
  fallbackLng: 'en',
});

// 将i18next实例暴露给全局，以便组件可以访问
window.i18next = i18n; // 在Web环境
global.i18next = i18n; // 在React Native环境
global.i18nextLng = 'zh'; // 设置当前语言

const App = () => {
  return (
    <View style={{ flex: 1 }}>
      <RNFloatingBubble
        imageSource={require('./assets/logo.png')}
        title="atmLocation"
        description="tapForDetails"
      />
    </View>
  );
};

export default App;

API 参考

RNFloatingBubbleProps

| 属性 | 类型 | 默认值 | 描述 | | ---------------- | ----------------------------------------------------------------- | ---------------------------------------- | ---------------------------------- | | visible | boolean | true | 是否显示气泡 | | imageSource | any | undefined | 图片源 | | imageSize | number | 25 | 图片大小 | | title | string | undefined | 气泡标题 | | description | string | undefined | 气泡描述 | | dragDirection | 'horizontal' | 'vertical' | 'both' | 'none' | 'both' | 拖拽方向限制 | | magneticEdges | boolean | false | 是否启用磁吸效果（吸附到屏幕边缘） | | onPress | () => void | undefined | 点击气泡的回调函数 | | containerStyle | StyleProp | undefined | 气泡容器样式 | | bubbleStyle | StyleProp | undefined | 气泡内容容器样式 | | titleStyle | StyleProp | undefined | 标题文本样式 | | descriptionStyle | StyleProp | undefined | 描述文本样式 | | children | React.ReactNode | undefined | 自定义内容 | | edgeInsets | { top?: number; left?: number; right?: number; bottom?: number; } | { top: 0, left: 0, right: 0, bottom: 0 } | 气泡边距 | | x | number | 0 | 初始 X 坐标 | | y | number | 0 | 初始 Y 坐标 |

注意事项

1. 使用children属性时，将覆盖默认的图片和标题/描述渲染。
2. 组件使用react-native-gesture-handler和react-native-reanimated实现拖拽功能，确保在父组件中不要有阻止触摸事件传播的元素。
3. 在 Android 上，确保气泡不会被系统导航栏遮挡。
4. 在 iOS 上，确保气泡不会被安全区域（如刘海屏）遮挡。
5. 使用magneticEdges属性可以让气泡在拖拽结束后自动吸附到屏幕边缘。

示例

查看 src/App.js 获取更多使用示例。

许可证

MIT