roxy-cobewebgl 1.0.0 → 1.1.0

package/README.md

@@ -37,6 +37,100 @@ pnpm dev
 
 浏览器将打开 [examples/playground/index.html](examples/playground/index.html)：本地直连 `src/` 源码，带参数面板与示例弧线（**不**打进 npm 包）。
 
+## Vue 3 组件
+
+依赖 **Vue ^3.3**，构建工具需正确处理 `.vue`（如 Vite + `@vitejs/plugin-vue`）。
+
+```bash
+pnpm add roxy-cobewebgl vue
+```
+
+```vue
+<script setup>
+import RoxyCobewebgl from 'roxy-cobewebgl/vue';
+
+const arcs = [
+  { startLat: 39.9, startLng: 116.4, endLat: 35.6, endLng: 139.6, color: '#ff6633' },
+];
+</script>
+
+<template>
+  <div style="width: 100%; height: 400px">
+    <RoxyCobewebgl
+      :arcs="arcs"
+      :dots="1800"
+      :globe-radius="0.55"
+      @error="(e) => console.error(e)"
+      @ready="() => {}"
+    />
+  </div>
+</template>
+```
+
+- **Props**：与 `createGlobe` 的 `CreateGlobeOptions` 一致，**无** `onError`；错误用 **`@error`**。
+- **`@ready`**：参数为 `GlobeInstance | null`（与 `createGlobe` 返回值相同语义）。
+- **`ref` 暴露**：`setState`、`resize`、`destroy`、`getGlobe()`。
+- 修改 **`map` / `mapUrl` / `arcs` / `preferWorker` / `debugShowTexture`** 会销毁并重建地球；其余视觉参数走 `setState`。
+
+示例项目（通过 `file:../..` 依赖本地包，可对照集成方式）：
+
+```bash
+pnpm install
+pnpm dev:vue
+```
+
+或进入 [examples/vue-demo](examples/vue-demo) 执行 `pnpm install` 与 `pnpm dev`（默认端口 `5174`）。
+
+## React 18+ 组件
+
+依赖 **React / React-DOM ^18 或 ^19**，需能解析 **JSX** 与 `.jsx`（如 Vite + `@vitejs/plugin-react`）。
+
+```bash
+pnpm add roxy-cobewebgl react react-dom
+```
+
+```jsx
+import { useMemo } from 'react';
+import RoxyCobewebgl from 'roxy-cobewebgl/react';
+
+export function GlobeCard() {
+  const arcs = useMemo(
+    () => [
+      { startLat: 39.9, startLng: 116.4, endLat: 35.6, endLng: 139.6, color: '#ff6633' },
+    ],
+    []
+  );
+
+  return (
+    <div style={{ width: '100%', height: 400 }}>
+      <RoxyCobewebgl
+        arcs={arcs}
+        dots={1800}
+        globeRadius={0.55}
+        onError={(e) => console.error(e)}
+        onReady={() => {}}
+      />
+    </div>
+  );
+}
+```
+
+另支持 **`import { RoxyCobewebgl } from 'roxy-cobewebgl/react'`**。可传 **`className` / `style`** 到内部 `<canvas>`。
+
+- **Props**：与 `CreateGlobeOptions` 一致，并增加 **`onReady`**（`onError` 仍与底层 API 相同）。
+- **`ref`**：`setState`、`resize`、`destroy`、`getGlobe()`。
+- **`map` / `mapUrl` / `arcs` / `preferWorker` / `debugShowTexture`** 变化会整实例重建；其余走 `setState`。
+- **`onError` / `onReady`** 通过 ref 保持最新，避免因父组件重渲染导致整球重建。
+
+示例：
+
+```bash
+pnpm install
+pnpm dev:react
+```
+
+或 [examples/react-demo](examples/react-demo)（默认端口 `5175`）。
+
 ## 地图数据
 
 | 文件 | 说明 |
@@ -119,6 +213,8 @@ pnpm run build:globe
 ## 子路径导出（package exports）
 
 - `roxy-cobewebgl` — 主入口
+- `roxy-cobewebgl/vue` — Vue 3 封装组件 `RoxyCobewebgl`
+- `roxy-cobewebgl/react` — React 封装组件 `RoxyCobewebgl`
 - `roxy-cobewebgl/globe.worker.js` — Worker 源码（多数场景无需直接 import）
 - `roxy-cobewebgl/globe.min.json` / `roxy-cobewebgl/globe.json` — 地图文件
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roxy-cobewebgl",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Cobe-style dotted globe with WebGL (ESM): OffscreenCanvas worker or main-thread fallback",
   "type": "module",
   "main": "./src/index.js",
@@ -13,17 +13,47 @@
     },
     "./globe.worker.js": "./src/globe.worker.js",
     "./globe.json": "./globe.json",
-    "./globe.min.json": "./globe.min.json"
+    "./globe.min.json": "./globe.min.json",
+    "./vue": {
+      "types": "./vue.d.ts",
+      "import": "./src/vue-entry.js",
+      "default": "./src/vue-entry.js"
+    },
+    "./react": {
+      "types": "./react.d.ts",
+      "import": "./src/react-entry.js",
+      "default": "./src/react-entry.js"
+    }
+  },
+  "peerDependencies": {
+    "vue": "^3.3.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vue": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
   },
   "files": [
     "src",
     "globe.json",
     "globe.min.json",
     "index.d.ts",
+    "vue.d.ts",
+    "react.d.ts",
     "README.md"
   ],
   "scripts": {
     "dev": "vite",
+    "dev:vue": "pnpm --dir examples/vue-demo dev",
+    "dev:react": "pnpm --dir examples/react-demo dev",
     "build:globe": "node scripts/slim-globe.mjs"
   },
   "keywords": [

package/react.d.ts

@@ -0,0 +1,27 @@
+import type {
+  ForwardRefExoticComponent,
+  RefAttributes,
+  CSSProperties,
+} from 'react';
+import type { CreateGlobeOptions, GlobeInstance } from './index';
+
+export type RoxyCobewebglProps = Partial<CreateGlobeOptions> & {
+  /** 地球实例创建完成（与 `createGlobe` 返回值相同语义） */
+  onReady?: (instance: GlobeInstance | null) => void;
+  className?: string;
+  style?: CSSProperties;
+};
+
+export type RoxyCobewebglRef = {
+  setState: GlobeInstance['setState'];
+  resize: GlobeInstance['resize'];
+  destroy: GlobeInstance['destroy'];
+  getGlobe: () => GlobeInstance | null;
+};
+
+declare const RoxyCobewebgl: ForwardRefExoticComponent<
+  RoxyCobewebglProps & RefAttributes<RoxyCobewebglRef>
+>;
+
+export { RoxyCobewebgl };
+export default RoxyCobewebgl;

package/src/react/RoxyCobewebgl.jsx

@@ -0,0 +1,157 @@
+import React, {
+  forwardRef,
+  useImperativeHandle,
+  useRef,
+  useEffect,
+} from 'react';
+import { createGlobe } from '../index.js';
+
+const SET_STATE_KEYS = [
+  'phi', 'theta', 'baseColor', 'glowColor', 'dotColor', 'arcColor',
+  'dots', 'dotSize', 'globeRadius', 'glowOn', 'debug', 'opacity',
+  'autoRotate', 'rotationSpeed',
+];
+
+function pickGlobeInitProps(props) {
+  const { onReady: _r, onError: _e, ...globe } = props;
+  return Object.fromEntries(
+    Object.entries(globe).filter(([, v]) => v !== undefined)
+  );
+}
+
+function pickSetStatePatch(props) {
+  const patch = {};
+  for (const k of SET_STATE_KEYS) {
+    if (props[k] !== undefined) patch[k] = props[k];
+  }
+  return patch;
+}
+
+/**
+ * React 封装：props 与 `createGlobe` 一致，另可传 `onReady(instance)`、`onError(err)`。
+ * ref：`setState`、`resize`、`destroy`、`getGlobe`
+ */
+export const RoxyCobewebgl = forwardRef(function RoxyCobewebgl(props, ref) {
+  const {
+    onReady,
+    onError,
+    preferWorker = true,
+    arcs = [],
+    debugShowTexture = false,
+    className,
+    style,
+    ...globeRest
+  } = props;
+
+  const fullProps = {
+    preferWorker,
+    arcs,
+    debugShowTexture,
+    ...globeRest,
+  };
+
+  const onErrorRef = useRef(onError);
+  const onReadyRef = useRef(onReady);
+  onErrorRef.current = onError;
+  onReadyRef.current = onReady;
+
+  const canvasRef = useRef(null);
+  const globeRef = useRef(null);
+  const readyRef = useRef(false);
+  const mountSeqRef = useRef(0);
+
+  useImperativeHandle(ref, () => ({
+    setState: (partial) => globeRef.current?.setState(partial),
+    resize: () => globeRef.current?.resize(),
+    destroy: () => {
+      globeRef.current?.destroy();
+      globeRef.current = null;
+      readyRef.current = false;
+    },
+    getGlobe: () => globeRef.current,
+  }), []);
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return undefined;
+
+    const id = ++mountSeqRef.current;
+    readyRef.current = false;
+    globeRef.current?.destroy();
+    globeRef.current = null;
+
+    let cancelled = false;
+
+    (async () => {
+      const instance = await createGlobe(canvas, {
+        ...pickGlobeInitProps(fullProps),
+        onError: (e) => onErrorRef.current?.(e),
+      });
+      if (cancelled || id !== mountSeqRef.current) {
+        instance?.destroy();
+        return;
+      }
+      globeRef.current = instance;
+      readyRef.current = true;
+      onReadyRef.current?.(instance);
+    })();
+
+    return () => {
+      cancelled = true;
+      mountSeqRef.current += 1;
+      readyRef.current = false;
+      globeRef.current?.destroy();
+      globeRef.current = null;
+    };
+  }, [
+    fullProps.map,
+    fullProps.mapUrl,
+    fullProps.arcs,
+    fullProps.preferWorker,
+    fullProps.debugShowTexture,
+  ]);
+
+  useEffect(() => {
+    if (!globeRef.current || !readyRef.current) return;
+    const patch = pickSetStatePatch(fullProps);
+    if (Object.keys(patch).length) globeRef.current.setState(patch);
+  }, [
+    fullProps.phi,
+    fullProps.theta,
+    fullProps.baseColor,
+    fullProps.glowColor,
+    fullProps.dotColor,
+    fullProps.arcColor,
+    fullProps.dots,
+    fullProps.dotSize,
+    fullProps.globeRadius,
+    fullProps.glowOn,
+    fullProps.debug,
+    fullProps.opacity,
+    fullProps.autoRotate,
+    fullProps.rotationSpeed,
+  ]);
+
+  const canvasClass =
+    className != null && className !== ''
+      ? `roxy-cobewebgl-canvas ${className}`
+      : 'roxy-cobewebgl-canvas';
+
+  return (
+    <canvas
+      ref={canvasRef}
+      className={canvasClass}
+      style={{
+        display: 'block',
+        width: '100%',
+        height: '100%',
+        verticalAlign: 'middle',
+        ...style,
+      }}
+    />
+  );
+});
+
+RoxyCobewebgl.displayName = 'RoxyCobewebgl';
+
+export default RoxyCobewebgl;

package/src/react-entry.js

@@ -0,0 +1,4 @@
+/**
+ * React 子路径：import RoxyCobewebgl from 'roxy-cobewebgl/react'
+ */
+export { RoxyCobewebgl, default } from './react/RoxyCobewebgl.jsx';

package/src/vue/RoxyCobewebgl.vue

@@ -0,0 +1,151 @@
+<template>
+  <canvas
+    ref="canvasRef"
+    class="roxy-cobewebgl-canvas"
+  />
+</template>
+
+<script setup>
+import { ref, watch, onMounted, onBeforeUnmount, shallowRef } from 'vue';
+import { createGlobe } from '../index.js';
+
+const SET_STATE_KEYS = [
+  'phi', 'theta', 'baseColor', 'glowColor', 'dotColor', 'arcColor',
+  'dots', 'dotSize', 'globeRadius', 'glowOn', 'debug', 'opacity',
+  'autoRotate', 'rotationSpeed',
+];
+
+const RECREATE_KEYS = ['map', 'mapUrl', 'arcs', 'preferWorker', 'debugShowTexture'];
+
+const props = defineProps({
+  map: { type: Object, default: undefined },
+  mapUrl: { type: [String, Object], default: undefined },
+  preferWorker: { type: Boolean, default: true },
+  arcs: { type: Array, default: () => [] },
+  debugShowTexture: { type: Boolean, default: false },
+  phi: { type: Number, default: undefined },
+  theta: { type: Number, default: undefined },
+  baseColor: { type: Array, default: undefined },
+  glowColor: { type: Array, default: undefined },
+  dotColor: { type: Array, default: undefined },
+  arcColor: { type: Array, default: undefined },
+  dots: { type: Number, default: undefined },
+  dotSize: { type: Number, default: undefined },
+  globeRadius: { type: Number, default: undefined },
+  glowOn: { type: Number, default: undefined },
+  debug: { type: Number, default: undefined },
+  opacity: { type: Number, default: undefined },
+  autoRotate: { type: Boolean, default: undefined },
+  rotationSpeed: { type: Number, default: undefined },
+});
+
+const emit = defineEmits(['error', 'ready']);
+
+const canvasRef = ref(null);
+const globeRef = shallowRef(null);
+const ready = ref(false);
+let mountSeq = 0;
+
+function toCreateOptions() {
+  const o = {
+    map: props.map,
+    mapUrl: props.mapUrl,
+    preferWorker: props.preferWorker,
+    arcs: props.arcs,
+    debugShowTexture: props.debugShowTexture,
+    onError: (e) => emit('error', e),
+    phi: props.phi,
+    theta: props.theta,
+    baseColor: props.baseColor,
+    glowColor: props.glowColor,
+    dotColor: props.dotColor,
+    arcColor: props.arcColor,
+    dots: props.dots,
+    dotSize: props.dotSize,
+    globeRadius: props.globeRadius,
+    glowOn: props.glowOn,
+    debug: props.debug,
+    opacity: props.opacity,
+    autoRotate: props.autoRotate,
+    rotationSpeed: props.rotationSpeed,
+  };
+  return Object.fromEntries(
+    Object.entries(o).filter(([, v]) => v !== undefined)
+  );
+}
+
+function pickSetStatePatch() {
+  const patch = {};
+  for (const k of SET_STATE_KEYS) {
+    if (props[k] !== undefined) patch[k] = props[k];
+  }
+  return patch;
+}
+
+async function mountGlobe() {
+  const canvas = canvasRef.value;
+  if (!canvas) return null;
+  const id = ++mountSeq;
+  ready.value = false;
+  globeRef.value?.destroy();
+  globeRef.value = null;
+  const instance = await createGlobe(canvas, toCreateOptions());
+  if (id !== mountSeq) {
+    instance?.destroy();
+    return null;
+  }
+  globeRef.value = instance;
+  ready.value = true;
+  emit('ready', instance);
+  return instance;
+}
+
+onMounted(() => {
+  mountGlobe();
+});
+
+onBeforeUnmount(() => {
+  mountSeq++;
+  ready.value = false;
+  globeRef.value?.destroy();
+  globeRef.value = null;
+});
+
+watch(
+  () => RECREATE_KEYS.map((k) => props[k]),
+  async () => {
+    if (!canvasRef.value) return;
+    await mountGlobe();
+  },
+  { deep: true }
+);
+
+watch(
+  () => pickSetStatePatch(),
+  (patch) => {
+    if (!globeRef.value || !ready.value) return;
+    if (Object.keys(patch).length) globeRef.value.setState(patch);
+  },
+  { deep: true }
+);
+
+defineExpose({
+  setState: (partial) => globeRef.value?.setState(partial),
+  resize: () => globeRef.value?.resize(),
+  destroy: () => {
+    globeRef.value?.destroy();
+    globeRef.value = null;
+    ready.value = false;
+  },
+  getGlobe: () => globeRef.value,
+});
+</script>
+
+<style scoped>
+.roxy-cobewebgl-canvas {
+  display: block;
+  width: 100%;
+  height: 100%;
+  vertical-align: middle;
+}
+</style>

package/src/vue-entry.js

@@ -0,0 +1,5 @@
+/**
+ * Vue 3 组件子路径：import RoxyCobewebgl from 'roxy-cobewebgl/vue'
+ */
+export { default } from './vue/RoxyCobewebgl.vue';
+export { default as RoxyCobewebgl } from './vue/RoxyCobewebgl.vue';

package/vue.d.ts

@@ -0,0 +1,20 @@
+import type { DefineComponent } from 'vue';
+import type { CreateGlobeOptions, GlobeInstance } from './index';
+
+/** 与 CreateGlobeOptions 一致，无 onError（请用 @error 事件） */
+export type RoxyCobewebglProps = Partial<Omit<CreateGlobeOptions, 'onError'>>;
+
+export type RoxyCobewebglExpose = {
+  setState: GlobeInstance['setState'];
+  resize: GlobeInstance['resize'];
+  destroy: GlobeInstance['destroy'];
+  getGlobe: () => GlobeInstance | null;
+};
+
+declare const RoxyCobewebgl: DefineComponent<
+  RoxyCobewebglProps,
+  RoxyCobewebglExpose
+>;
+
+export { RoxyCobewebgl };
+export default RoxyCobewebgl;