react-swipe-map 1.0.1 → 1.0.3

package/README.md

@@ -1,73 +1,224 @@
-# React + TypeScript + Vite
+# react-swipe-map
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+一个基于 React 和 Leaflet 的卷帘地图组件，支持左右图层对比展示，适用于地图数据对比、变化检测等场景。
 
-Currently, two official plugins are available:
+## ✨ 特性
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+- 🗺️ 基于 Leaflet 的卷帘地图组件
+- 🔄 支持卷帘模式和普通地图模式切换
+- 📍 支持左右图层独立管理
+- 🎨 支持自定义控件图标
+- 🗂️ 支持底图切换
+- 📦 开箱即用，简单易用
 
-## React Compiler
+## 📦 安装
 
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+```bash
+npm install react-swipe-map
+# 或
+yarn add react-swipe-map
+# 或
+pnpm add react-swipe-map
+```
+
+## 🚀 快速开始
 
-## Expanding the ESLint configuration
+### 基本使用
 
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+```tsx
+import React, { useRef, useState } from 'react';
+import L from 'leaflet';
+import 'leaflet/dist/leaflet.css';
+import Map from 'react-swipe-map';
+import { Button } from 'antd';
 
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
+function App() {
+  const [isRollMap, setIsRollMap] = useState(false);
+  const mapRef = useRef(null);
 
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
+  // 在左侧图层上添加 marker
+  const addMarkerToLeft = () => {
+    if (!mapRef.current) return;
+    const marker = L.marker([30.5984, 114.3118], {
+      pane: 'leftPane',
+    });
+    (mapRef.current as any).addLeftLayers([marker]);
+  };
 
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
+  // 在右侧图层上添加 GeoJSON
+  const addGeoJsonToRight = () => {
+    if (!mapRef.current) return;
+    const geojson = L.geoJSON(
+      {
+        type: 'Feature',
+        geometry: {
+          type: 'Polygon',
+          coordinates: [
+            [
+              [115.796, 40.4934],
+              [116.377, 40.3945],
+              [116.236, 39.9146],
+              [115.659, 40.0129],
+              [115.796, 40.4934],
+            ],
+          ],
+        },
+      },
+      {
+        pane: 'rightPane',
+        style: {
+          color: 'red',
+          weight: 3,
+          opacity: 0.5,
+          fillColor: 'red',
+          fillOpacity: 0.2,
+        },
       },
-      // other options...
-    },
-  },
-])
+    ).addTo((mapRef.current as any).getRightLayersGroup());
+    
+    // 定位到 geojson
+    ((mapRef.current as any).getMapRef() as L.Map).fitBounds(geojson.getBounds());
+  };
+
+  return (
+    <div style={{ height: '100vh', width: '100%' }}>
+      <Map
+        ref={mapRef}
+        leftLayers={[]}
+        rightLayers={[]}
+        onIsRollMapChange={setIsRollMap}
+      />
+      <div style={{ position: 'absolute', top: 10, right: 10, zIndex: 1000 }}>
+        <Button onClick={addMarkerToLeft} disabled={!isRollMap}>
+          添加 marker 到左侧图层
+        </Button>
+        <Button onClick={addGeoJsonToRight} disabled={!isRollMap} style={{ marginLeft: 8 }}>
+          添加 GeoJSON 到右侧图层
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+export default App;
 ```
 
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+## 📖 API 文档
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| `leftLayers` | 左侧图层列表 | `L.Layer[]` | `[]` | 否 |
+| `rightLayers` | 右侧图层列表 | `L.Layer[]` | `[]` | 否 |
+| `mapSettings` | 地图配置 | `{ center: number[], zoom: number }` | `{ center: [35.8617, 104.1954], zoom: 4 }` | 否 |
+| `rollIcon` | 卷帘模式图标 | `any` | 内置图标 | 否 |
+| `normalIcon` | 普通模式图标 | `any` | 内置图标 | 否 |
+| `baseMapSelectIcon` | 底图选择图标 | `any` | 内置图标 | 否 |
+| `baseMapList` | 底图列表 | `BaseMapConfig[]` | `[]` | 否 |
+| `onIsRollMapChange` | 卷帘模式变化回调 | `(isRollMap: boolean) => void` | - | 否 |
+
+### BaseMapConfig
+
+```typescript
+interface BaseMapConfig {
+  id: string;
+  name: string;
+  mapUrl: string;
+  type: '4326' | '3857';
+  centre?: [number, number];
+  zoom?: number;
+  zoomOffset?: number;
+  maxZoom?: number;
+  checked?: boolean;
+  icon?: string;
+}
 ```
+
+### Ref Methods
+
+通过 `ref` 可以访问以下方法：
+
+| 方法名 | 说明 | 类型 |
+|--------|------|------|
+| `addLeftLayers` | 添加左侧图层 | `(layers: L.Layer[]) => void` |
+| `addRightLayers` | 添加右侧图层 | `(layers: L.Layer[]) => void` |
+| `clearLeftLayers` | 清除左侧图层 | `() => void` |
+| `clearRightLayers` | 清除右侧图层 | `() => void` |
+| `getMapInstance` | 获取地图实例 | `() => L.Map \| null` |
+| `toggleRollMap` | 切换卷帘模式 | `(enabled: boolean) => void` |
+| `getIsRollMap` | 获取当前是否为卷帘模式 | `() => boolean` |
+| `getLeftLayersGroup` | 获取左侧图层组 | `() => L.LayerGroup \| null` |
+| `getRightLayersGroup` | 获取右侧图层组 | `() => L.LayerGroup \| null` |
+| `getMapRef` | 获取地图引用 | `() => L.Map \| null` |
+
+## 🎯 使用场景
+
+- 🗺️ **地图数据对比**：对比不同时期的地图数据
+- 📍 **变化检测**：检测地理数据的变化情况
+- 🎨 **图层对比**：对比不同图层的数据差异
+- 📊 **数据分析**：辅助地理数据分析和可视化
+
+## 💡 注意事项
+
+1. **Leaflet 样式**：使用前需要引入 Leaflet 的 CSS 文件：
+   ```tsx
+   import 'leaflet/dist/leaflet.css';
+   ```
+
+2. **Pane 设置**：添加图层时，可以通过 `pane` 参数指定图层所属的 pane：
+   - `leftPane`：左侧图层
+   - `rightPane`：右侧图层
+
+3. **卷帘模式**：只有在卷帘模式下，左右图层才会分开显示
+
+4. **图层管理**：使用 `addLeftLayers` 和 `addRightLayers` 方法添加图层时，会自动更新卷帘控制器
+
+## 🔧 依赖
+
+- React >= 18.2.0
+- React DOM >= 18.2.0
+- Leaflet >= 1.9.4
+- leaflet-side-by-side >= 2.2.0
+- antd >= 6.2.3
+
+## 📝 更新日志
+
+### v1.0.2 (当前版本)
+
+- ✨ 初始版本发布
+- 🗺️ 支持卷帘地图基本功能
+- 🔄 支持卷帘模式和普通地图模式切换
+- 📍 支持左右图层独立管理
+- 🎨 支持自定义控件图标
+- 🗂️ 支持底图切换
+
+## 🚧 后续优化计划
+
+- [ ] 添加更多地图控件（比例尺、鹰眼图等）
+- [ ] 支持更多地图服务（WMS、WFS 等）
+- [ ] 优化性能，减少不必要的渲染
+- [ ] 添加更多示例和文档
+- [ ] 支持 TypeScript 类型定义优化
+- [ ] 添加单元测试
+- [ ] 支持自定义主题
+- [ ] 支持移动端适配
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 📄 许可证
+
+MIT License
+
+## 📮 联系方式
+
+如有问题或建议，请通过以下方式联系：
+
+- 提交 Issue：[GitHub Issues](https://github.com/your-username/react-swipe-map/issues)
+- 邮件：your-email@example.com
+
+---
+
+**⭐ 如果这个项目对你有帮助，请给一个 Star 支持一下！**