一、Demo 能解决哪些痛点？

在实际业务中。开发者常常面临以下困扰：

• ❌ 主题切换只能改 CSS 变量，3D 场景颜色不同步。
• ❌ 颜色硬编码导致维护成本高，新需求需要遍历大量文件。
• ❌ 地图底图风格与 UI 风格耦合，切换时要改两套代码。
• ❌ 下钻后返回首页时主题被重置，使用者体验差。
• ❌ ECharts 与全局主题不联动，需要手动写多套配置。

Demo6 用统一的 Token + ThemeProvider 打通 UI 与 Three.js。实现“一套代码，多套视觉”。

二、主要能力概览

能力	说明
三维中国地图省份挤出、柱状图、标签、Tooltip	省 / 市 / 区三级下钻点击区域逐级深入
套 UI 主题	暖橙、科技蓝、暗黑科技、赛博紫、翡翠绿、金色荣耀
种地图底图风格	卫星 / 矢量 / 路网 + 多种纹理 / 视频贴图
ECharts 图表随主题变色
入场动画 GSAP 镜头推进 + 地图挤出

左上角可一键切换主题和地图风格。适合演示「同一套大屏，多套视觉方案」。

三、技术栈

React → UI 框架
Vite → 建立
@react-three/fiber → React 封装 Three.js
@react-three/drei → 阴影、轨道控制等
Three.js → 3D 地图渲染
d3-geo → GeoJSON 墨卡托投影
GSAP → 镜头 / 下钻动画
ECharts → 左右统计图表
styled-components → 主题 Token + CSS‑in‑JS
Zustand → 全局状态

四、整体架构

┌─────────────────────────────────────────────────────┐
│ index.tsx │
│ ThemeProvider ← Zustand │
│ └─ demo.tsx │
│ ├─ map/index.tsx │
│ └─ panel/ │
└─────────────────────────────────────────────────────┘

分层原则：

1. UI 主题层：面板、标题、图表、按钮。
2. 3D 场景层：地图、灯光、背景、柱状图。
3. 状态层：,。.

UI 和 3D 共用同一套主题 Token，切换时两侧同步变色，从根本上消除「UI 好看但地图发黑」的痛点。话说回来，

五、主题程序设计

5.1 单一数据源：DashboardTheme

export interface DashboardTheme {
说到id。ThemeKey，name: string;colors: {
primary: string;accent: string;background: string;backgroundRgb: string;// rgba 拼接用
至于mapBg，string;// Three.js 场景背景色
mapLight: string;// 平行光颜色
mapSurface: string;// 挤出侧面材质颜色
chartGradient:;chartPalette:;glow: string;// ，其实，更多语义化 Token…}，}

技巧： 用语义 Token 替代硬编码颜色；不过，组件里只写{ => me.colors.accent}。不出现#2563EB​等魔法数字。

5.2 ThemeProvider + Zustand 注入全局主题

// index.tsx
const meKey = useConfigStore;
return (



);

// stores/index.ts
setTheme: key => set。cycleTheme: => { /* 循环切换 */ },reset: => {
const { meKey,mapStyleKey } = store.getState;set,meKey,mapStyleKey });},

切换主题 = 改 ;ThemeProvider 重渲染后所有useTheme/useDashboardTheme拿到最新 Token。技巧： 下钻重置时保留当前 ,;防止使用者返回全国视图时失去已选配色。

5.3 styled-components 类型

// mes/styled.d.ts
declare module 'styled-components' {
export interface DefaultTheme extends DashboardTheme {}
}

这样在任何 styled‑component 中都能获得完整 TypeScript 提示，如 {me.colors.mapBg}.

5.4 单一 Hook：useDashboardTheme

export default function useDashboardTheme: DashboardTheme {
return useTheme;}

六、Three.js 地图实现

6.1 场景入口

 {/* 场景背景 */}
 {/* 环境光 + 平行光 */}
 {/* 地图主体 */}

6.2 GeoJSON → 三维挤出流程

① 加载 /china.json  ② 用 d3-geo geoMercator​投影转成 Vector2 点阵 ③ 用  ④ 在 R3F 中按需渲染四级地图。

文件名/目录	职责说明
map/base.tsx	全国/省/市/区 四级切换及下钻逻辑
map/city.tsx	单区域挤出交互 + 柱状指标展示
map/shape.tsx	UV 映射
map/bar.tsx	Three.js 柱状体渲染

6.3 Three.js 如何响应 UI Theme tsx{12} // map/background.tsx – 场景背景 useEffect => { scene.background = new Color;},)，// map/lights.tsx – 平行光 // map/city.tsx – 挤出侧面材质 技巧： 为 Three.js 专门设计 `mapBg` `mapLight` `mapSurface` 三个语义化 Token，避免「浅色主题背景太亮」或「暗黑主题灯光不足」的问题。

6.4 地图贴图与风格解耦

`mapStyleKey` 控制底图，与 `meKey` 完全独立：

类型	示例	UV 模式
geo 对齐	satellite / vector	uvMode:"geo"
装饰纹理	road + video	uvMode:"decorative"

tsx{8} function uvModeForStyle { return isGeoAlignedStyle?'geo' : 'decorative';}

装饰模式下开启 emissiveMap 与 emissiveIntensity让视频纹理更亮。

技巧： UI me 与 map style 完全解耦。可随意组合如「暗黑科技 + 卫星底图」或「科技蓝 + 视频纹理」，极大提高灵活性。

七、ECharts 随 Theme 切换

tsx{12} const me = useDashboardTheme;const colors = me.colors.chartGradient;

const option = useMemo => ({ series这方面。},{offset:1,color:colors} ] } } }] }),);// 当 me.id 改变时重新计算

return ;

技巧给 Chart 加 key={me.id} 强制实例在切换时完整重建，避免旧配色残留。按理说，

八、三级下钻交互

• drillStack 决定加载哪个 GeoJSON。怎么说呢，
• scale.z 挤出动画。
• 上使用 key={mapStyleKey} 强制重新创建材质。

tsx{8}

这样即使更改了 mapStyleKey旧的 THREE.Texture 缓存也不会被误用。老实说，

九、主题/地图风格切换 UI

tsx{10} {/* panel/meSwitcher.tsx */}

若某风格资源尚未生成。则对应 被置灰——让使用者用起来更舒服并防止报错。

十、大屏实现关键技巧汇总

关键技巧与对应痛点消除对照表<\/th>
①统一 Token 表<\/strong> 一次定义，多处引用；避免颜色硬编码导致维护成本高。<\/ td>
②UI 与 Three 共用 ThemeProvider<\/ strong><\/ td>
③Three 材质实时响应 Theme 改变<\/ strong><\/ td>
④ECharts 用 useMemo+key 强制重建<\/ strong><\/ td>
⑤UI 与底图解耦<\/ strong><\/ td>
⑥贴图缓存按风格分 key<\/ strong><\/ td>
⑦双 UV 模式 <\/ strong><\/ td>

十一、目录结构速查

src/pages/Demo6/
├── index.tsx # ThemeProvider入口
├── demo.tsx # 页面布局
├── stores/
│   └── index.ts # Zustand 状态管理
├── mes/
│   ├── types.ts # DashboardTheme 类型定义
│   ├── index.ts # 所有套主题配置
│   └── styled.d.ts # styled-components 类型
├── config/
│   └── mapStyles.ts # 底图库定义及可用性检查
├── hooks/
│   └── useDashboardTheme.ts
├── panel/
│   ├── meSwitcher.tsx # 左上角切换控件
│   ├── header.tsx
│   └── chart*.tsx # 各类 ECharts 图表
└── map/
├── index.tsx # R3F Canvas 主入口
├── base.tsx # 四级地图框架+下钻逻辑
├── city.tsx # 单城市挤出+交互
├── background.tsx
├── lights .tsx
└── scene .tsx
​
​
​
​ 

​

​​ ​​ ​​ ​​

​​

​​​

​ ​ ​ ​ ​

‍‍‍‍‍‍‍‍‍

‌‌

‏

‌

...

.....

…

…，

—

——

–

- - - - -

- -

- - — – –

— — –

— —

– —

— –

。

---