# vbe-cluster-map2

**Repository Path**: vbes/vbe-cluster-map2

## Basic Information

- **Project Name**: vbe-cluster-map2
- **Description**: React Native Mapview cluster component for Android Native
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-08
- **Last Updated**: 2025-12-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# vbe-cluster-map

React Native Mapview cluster component for Android Native

支持 **React Native 新架构 (Fabric/TurboModule)**

## 特性

- 🗺️ 基于 Google Maps 的地图聚合组件
- ⚡ 支持 React Native 新架构 (New Architecture)
- 🔄 向后兼容旧架构 (Paper)
- 🎯 自定义标记状态 (available, favorite, upcoming 等)
- 📍 支持显示用户位置
- 🎬 聚合动画效果
- 🧭 指南针显示控制
- 🚗 交通图层显示
- 🏢 室内地图支持
- 🛰️ 卫星地图视图
- 🌓 明暗风格切换

## 要求

- React Native >= 0.73.0
- React >= 18.0.0
- Android minSdk 23+
- Google Play Services

## 安装

```bash
npm install vbe-cluster-map@https://gitee.com/vbes/vbe-cluster-map2.git
# 或
yarn add vbe-cluster-map@https://gitee.com/vbes/vbe-cluster-map2.git
```

## 使用方法

```jsx
import VbeClusterMap from 'vbe-cluster-map';

function MapScreen() {
  const mapRef = useRef(null);

  return (
    <VbeClusterMap
      ref={mapRef}
      style={{ flex: 1 }}
      region={{
        latitude: 39.9,
        longitude: 116.4,
        latitudeDelta: 0.1,
        longitudeDelta: 0.1,
        zoom: 12
      }}
      data={[
        {
          id: 1,
          name: "站点1",
          latitude: 39.9,
          longitude: 116.4,
          available: true,
          favorite: false
        }
      ]}
      animation={true}
      showUserLocation={false}
      showCompass={true}
      showTraffic={false}
      showIndoors={false}
      showIndoorLevelPicker={false}
      showSatellite={false}
      mapStyle="light"
      moveOnMarkerPress={true}
      onMapReady={() => console.log('地图加载完成')}
      onMarkerPress={(event) => console.log('点击标记', event.id)}
    />
  );
}
```

## Props

| 属性 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `style` | ViewStyle | - | 组件样式 |
| `region` | Region | - | 地图区域配置 |
| `data` | ClusterData[] | - | 聚合数据 |
| `animation` | boolean | true | 是否启用聚合动画 |
| `showUserLocation` | boolean | false | 是否显示用户位置 |
| `showCompass` | boolean | true | 是否显示指南针（地图旋转时显示在右上角的指南针图标） |
| `showTraffic` | boolean | false | 是否显示交通图层 |
| `showIndoors` | boolean | false | 是否显示室内地图 |
| `showIndoorLevelPicker` | boolean | false | 是否显示室内楼层选择器 |
| `showSatellite` | boolean | false | 是否显示卫星地图（开启后显示卫星视图，关闭显示普通地图） |
| `mapStyle` | 'light' \| 'dark' | 'light' | 地图风格（浅色/深色主题） |
| `moveOnMarkerPress` | boolean | true | 点击标记时是否移动相机 |
| `onMapReady` | () => void | - | 地图加载完成回调 |
| `onMarkerPress` | (event) => void | - | 标记点击回调 |

## Ref 方法

| 方法 | 参数 | 描述 |
|------|------|------|
| `moveCamera` | (region, zoom?) | 移动相机到指定区域 |
| `setShowUserLocation` | (show: boolean) | 设置是否显示用户位置 |
| `setShowCompass` | (show: boolean) | 设置是否显示指南针 |
| `setShowTraffic` | (show: boolean) | 设置是否显示交通图层 |
| `setShowIndoors` | (show: boolean) | 设置是否显示室内地图 |
| `setShowIndoorLevelPicker` | (show: boolean) | 设置是否显示室内楼层选择器 |
| `setShowSatellite` | (show: boolean) | 设置是否显示卫星地图 |
| `setMapStyle` | (style: 'light' \| 'dark') | 设置地图风格 |

### Ref 方法使用示例

```jsx
import { useRef } from 'react';
import VbeClusterMap from 'vbe-cluster-map';

function MapScreen() {
  const mapRef = useRef(null);

  // 移动相机到指定位置（完整参数）
  const handleMoveToShanghai = () => {
    mapRef.current?.moveCamera({
      latitude: 31.2304,
      longitude: 121.4737,
      latitudeDelta: 0.1,
      longitudeDelta: 0.1,
      zoom: 15
    });
  };

  // 移动相机（简化调用，第二个参数是 zoom）
  const handleMoveToBeijing = () => {
    mapRef.current?.moveCamera({
      latitude: 39.9042,
      longitude: 116.4074,
    }, 12);
  };

  // 显示/隐藏用户位置
  const toggleUserLocation = (show) => {
    mapRef.current?.setShowUserLocation(show);
  };

  // 显示/隐藏指南针
  const toggleCompass = (show) => {
    mapRef.current?.setShowCompass(show);
  };

  // 显示/隐藏交通图层
  const toggleTraffic = (show) => {
    mapRef.current?.setShowTraffic(show);
  };

  // 显示/隐藏室内地图
  const toggleIndoors = (show) => {
    mapRef.current?.setShowIndoors(show);
  };

  // 显示/隐藏室内楼层选择器
  const toggleIndoorLevelPicker = (show) => {
    mapRef.current?.setShowIndoorLevelPicker(show);
  };

  // 显示/隐藏卫星地图
  const toggleSatellite = (show) => {
    mapRef.current?.setShowSatellite(show);
  };

  // 切换地图风格
  const changeMapStyle = (style) => {
    mapRef.current?.setMapStyle(style); // 'light' 或 'dark'
  };

  return (
    <VbeClusterMap
      ref={mapRef}
      style={{ flex: 1 }}
      region={{
        latitude: 39.9,
        longitude: 116.4,
        latitudeDelta: 0.1,
        longitudeDelta: 0.1,
        zoom: 12
      }}
      data={[]}
      onMapReady={() => console.log('地图已加载')}
    />
  );
}
```

## ClusterData 类型

```typescript
interface ClusterData {
  id: number;          // 唯一标识
  name: string;        // 站点名称
  latitude: number;    // 纬度
  longitude: number;   // 经度
  available: boolean;  // 是否可用
  favorite?: boolean;  // 是否收藏
  upcoming?: boolean;  // 是否即将开放
  hasLabel?: boolean;  // 是否有标签
  zIndex?: string;     // z轴顺序
}
```

## 新架构支持

此组件完全支持 React Native 新架构 (Fabric)。

### 启用新架构

在你的项目 `android/gradle.properties` 中添加：

```properties
newArchEnabled=true
```

## 仓库

- GitHub: https://github.com/vbea/vbe-cluster-map
- Gitee: https://gitee.com/vbes/vbe-cluster-map2

## License

MIT License

©2025 VbeStudio