scifi-earth

科幻风格 React + Three.js 地球可视化组件

当前版本：0.0.1

安装

npm install scifi-earth

快速使用

布局样式由组件内联注入，无需单独引入 CSS 文件。

1. 最小示例

function Demo() {
  return <SciFiEarth />
}

2. 事件标记（泛型 data）

import { SciFiEarth } from 'scifi-earth'
import type { EventMarker } from 'scifi-earth'

type Payload = { name: string }

const markers: EventMarker<Payload>[] = [
  { id: 'bj', lat: 39.9, lon: 116.4, data: { name: '北京' } },
  { id: 'tk', lat: 35.68, lon: 139.76, data: { name: '东京' } },
]

function App() {
  return (
    <SciFiEarth<Payload>
      width={960}
      aspectRatio={4 / 3}
      eventMarkers={markers}
      onEventMarkerClick={(data) => {
        console.log(data?.name)
      }}
    />
  )
}

3. 布局相关 Props

| 属性 | 说明 | |------|------| | width | 宽度，数字为 px，也可传 CSS 字符串 | | height | 高度；与 width 同时省略时由默认宽度 + aspectRatio 推算 | | aspectRatio | 宽/高，默认 4/3（常量 SCI_FI_EARTH_DEFAULT_ASPECT） | | className / style | 外层容器 |

仅需要根据宽高比算出容器样式时，可使用：

import { resolveSciFiEarthSize, type SciFiEarthLayoutProps } from 'scifi-earth'

const layout: SciFiEarthLayoutProps = { width: 1200, aspectRatio: 16 / 9 }
const style = resolveSciFiEarthSize(layout)

4. EventMarker<T>

type EventMarker<T = undefined> = {
  lat: number
  lon: number
  data?: T
  id?: string | number
}

• 使用 SciFiEarth<MyData> 时，建议为 EventMarker<MyData>[]，并在 onEventMarkerClick 中获得类型推断。

其他导出（进阶）

在自有 Canvas 内拼装时可用：

| 导出 | 说明 | |------|------| | SciFiEarthScene | 仅 R3F 场景（海洋、岸线、轨道控制、标记等） | | GlobeEventMarkers | 球面红色脉冲标记 | | useEarthMapData | 异步加载 Natural Earth 几何（岸线/国界） |

本仓库开发

npm install
npm run dev          # 本地演示
npm run build        # 演示站构建 → dist-app/
npm run build:lib    # npm 包构建 → dist/

Changelog

0.0.1

• 首次发布：SciFiEarth 主组件（Canvas + 地图数据 + 后处理）。
• 支持 EventMarker<T>、onEventMarkerClick、布局 Props 与 resolveSciFiEarthSize。
• 容器与画布样式为内联，无需 import '…/style.css'。

License

MIT