gavin/lupin-demo

Fork 0

Files

douboer@gmail.com 6a7120f685 update at 2026-01-28 16:48:40

2026-01-28 16:48:40 +08:00

16 KiB

Raw Blame History

罗盘组件详细设计文档

1. 概述

本组件实现了一个可配置的圆盘罗盘可视化系统，支持将圆盘分为多个同心圆环和扇区，并在每个区域精确放置文字或图形。

2. 数学模型

2.1 坐标系统

角度约定：0° 位于正北（上方），顺时针方向为正
SVG 坐标系：
- x 轴：向右为正
- y 轴：向下为正
- 原点：画布中心

2.2 参数定义

角度参数

n：总扇区数（pie 数量）
angle[i]：第 i 个分度线的角度，i ∈ [0...n]
wide(i) = angle[i] - angle[i-1]：第 i 块扇区的角度宽度

半径参数

m：总圆环数
radius(j)：第 j 个圆环的半径，j ∈ [0...m]
height(j) = radius(j) - radius(j-1)：第 j 层圆环的高度

区域定义

layer(j)：第 j 层，由圆环 j 和圆环 j-1 之间形成
pie(i)：第 i 个扇区，由分度线 i-1 和分度线 i 之间形成
sector(j,i)：第 j 层第 i 个扇区的区域

2.3 形心计算公式

对于圆环扇形区域 sector(j,i)，其形心位置计算如下：

输入参数

rInner = radius(j-1)：内半径
rOuter = radius(j)：外半径
aStart = angle[i-1]：起始角度（度）
aEnd = angle[i]：结束角度（度）

计算步骤

角度归一化

a₁ = normalize(aStart)  // 转换到 [0, 360)
a₂ = normalize(aEnd)
Δ = a₂ - a₁  // 若 < 0，则加 360

中心角度

aMid = a₁ + Δ/2  // 扇区中心角度

形心半径（面积加权质心）

radialFactor = (2/3) × (r₂³ - r₁³) / (r₂² - r₁²)
sinc(x) = sin(x) / x  // x ≠ 0 时
ρ = radialFactor × sinc(Δ/2)

其中：

r₁ = rInner
r₂ = rOuter
Δ 为弧度制

极坐标转笛卡尔坐标

cx = ρ × sin(aMid)
cy = -ρ × cos(aMid)  // 注意：y 坐标取负以适应 SVG 坐标系

输出结果

(cx, cy)：形心的笛卡尔坐标
ρ：形心的极坐标半径
aMid：形心的极坐标角度

2.4 特殊情况处理

纯扇形（rInner = 0）
- 公式仍然适用，内圆退化为点
跨越 0° 的扇区
- 例如：aStart = 315°, aEnd = 45°
- 通过归一化自动处理：Δ = 45 - 315 + 360 = 90°
退化情况
- rInner ≥ rOuter：返回 (0, 0)
- Δ = 0：返回 (0, 0)

3. 核心算法实现

3.1 极坐标转换

function polarToXY(aDeg: number, r: number): {x: number, y: number} {
  const a = (aDeg * Math.PI) / 180;
  return { 
    x: r * Math.sin(a), 
    y: -r * Math.cos(a)  // y 坐标取负
  };
}

3.2 角度归一化

function normalizeDeg(deg: number): number {
  const d = deg % 360;
  return d < 0 ? d + 360 : d;
}

3.3 形心计算

function annularSectorCentroid(params: {
  rInner: number,
  rOuter: number,
  aStartDeg: number,
  aEndDeg: number
}): CentroidResult {
  const { rInner, rOuter, aStartDeg, aEndDeg } = params;

  // 1. 角度归一化
  const a1 = normalizeDeg(aStartDeg);
  const a2 = normalizeDeg(aEndDeg);
  let deltaDeg = a2 - a1;
  if (deltaDeg < 0) deltaDeg += 360;

  // 2. 中心角度
  const aMidDeg = normalizeDeg(a1 + deltaDeg / 2);
  const aMidRad = (aMidDeg * Math.PI) / 180;

  // 3. 边界检查
  if (rOuter <= rInner || deltaDeg === 0) {
    return { cx: 0, cy: 0, rho: 0, aMidDeg, aMidRad, deltaDeg };
  }

  // 4. 形心半径计算
  const delta = (deltaDeg * Math.PI) / 180;
  const radialFactor = (2 / 3) * 
    ((rOuter ** 3 - rInner ** 3) / (rOuter ** 2 - rInner ** 2));
  const half = delta / 2;
  const sinc = half === 0 ? 1 : Math.sin(half) / half;
  const rho = radialFactor * sinc;

  // 5. 坐标转换
  const p = polarToXY(aMidDeg, rho);
  return { cx: p.x, cy: p.y, rho, aMidDeg, aMidRad, deltaDeg };
}

4. 扇区路径生成

4.1 SVG 路径绘制

圆环扇形使用 SVG 的 <path> 元素绘制，包含以下步骤：

移动到外弧起点
绘制外弧（arc to）
连线到内弧终点
绘制内弧（arc to）
闭合路径

function annularSectorPath(
  rInner: number, 
  rOuter: number, 
  aStartDeg: number, 
  aEndDeg: number
): string {
  // 计算关键点
  const p1 = polarToXY(aStart, rOuter);  // 外弧起点
  const p2 = polarToXY(aEnd, rOuter);    // 外弧终点
  const p3 = polarToXY(aEnd, rInner);    // 内弧终点
  const p4 = polarToXY(aStart, rInner);  // 内弧起点

  // 确定 large-arc-flag
  const largeArc = delta > 180 ? 1 : 0;

  // 生成路径
  return [
    `M ${p1.x} ${p1.y}`,                                      // 起点
    `A ${rOuter} ${rOuter} 0 ${largeArc} 1 ${p2.x} ${p2.y}`, // 外弧
    `L ${p3.x} ${p3.y}`,                                      // 连线
    `A ${rInner} ${rInner} 0 ${largeArc} 0 ${p4.x} ${p4.y}`, // 内弧
    "Z"                                                        // 闭合
  ].join(" ");
}

4.2 特殊情况：纯扇形

当 rInner ≈ 0 时，内弧退化为圆心点：

if (rInner <= 0.000001) {
  return [
    `M ${p1.x} ${p1.y}`,
    `A ${rOuter} ${rOuter} 0 ${largeArc} 1 ${p2.x} ${p2.y}`,
    `L 0 0`,  // 连线到圆心
    "Z"
  ].join(" ");
}

5. 文字排列算法

5.1 文字路径生成

文字沿圆弧排列，使用 SVG 的 <textPath> 功能。路径使用形心半径：

function generateTextPath(
  rInner: number,
  rOuter: number,
  aStartDeg: number,
  aEndDeg: number,
  reverse: boolean
): string {
  // 使用形心半径作为文字路径
  const centroid = annularSectorCentroid({
    rInner, rOuter, aStartDeg, aEndDeg
  });
  const rMid = centroid.rho;  // 形心半径

  const p1 = polarToXY(aStart, rMid);
  const p2 = polarToXY(aEnd, rMid);
  const largeArc = delta > 180 ? 1 : 0;

  if (reverse) {
    // 反向路径（左半圆）
    return `M ${p2.x} ${p2.y} A ${rMid} ${rMid} 0 ${largeArc} 0 ${p1.x} ${p1.y}`;
  } else {
    // 正向路径（右半圆）
    return `M ${p1.x} ${p1.y} A ${rMid} ${rMid} 0 ${largeArc} 1 ${p2.x} ${p2.y}`;
  }
}

5.2 文字方向判断

为保持文字"头朝外"，需要判断是否使用反向路径：

// 左半圆（90° ~ 270°）需要反向路径
const needReverse = aMidDeg > 90 && aMidDeg < 270;

原理：

右半圆（0°~90°, 270°~360°）：正向路径，文字自然朝外
左半圆（90°~270°）：反向路径，避免文字倒置

5.3 文字长度适配

根据层数自动调整文字长度：

// 第 j 层显示 (j+1) × 2 个字
const textLength = (layerIndex + 1) * 2;
const label = '测'.repeat(textLength);

示例：

第1层：2个字
第2层：4个字
第3层：6个字

6. 颜色生成策略

当前实现以主题色板为核心：colorRef 优先解析为主题色名，未命中时退回原值。

扇区填色优先级：

扇区级 colorRef
层级规律填色（layer.colorRef + num/interval/patternOffset）
全局 background

刻度环颜色：

degreeRing.colorRef 存在时，渲染环形背景填充（作为刻度环背景）。
tickColor / ringColor 显式提供则优先使用；未提供时根据背景计算对比色。
opacity 同时作用于环形背景和内外圆环描边。

7. 组件架构

7.1 模块划分

src/
├── types.ts              # TypeScript 类型定义
├── utils.ts              # 纯函数工具集
├── constants.ts          # 配置常量
├── composables/
│   └── useLuopan.ts     # 组合函数（业务逻辑）
├── Luopan.vue           # 主组件
├── utils.test.ts        # 单元测试
└── index.ts             # 入口文件

7.2 数据流

配置数据 (Example)
    ↓
useLuopan (计算扇区数据)
    ↓
Sector[] (包含形心、路径、颜色等)
    ↓
Luopan.vue (渲染 SVG)

7.3 关键类型定义

// 配置
interface Example {
  name: string;
  angles: number[];    // 角度分割点 [0, 30, 60, ..., 360]
  radii: number[];     // 圆环半径 [60, 120, 180]
}

// 扇区数据
interface Sector {
  key: string;
  layerIndex: number;
  pieIndex: number;
  rInner: number;
  rOuter: number;
  aStart: number;
  aEnd: number;
  aMidDeg: number;
  aMidRad: number;
  cx: number;          // 形心 x
  cy: number;          // 形心 y
  fill: string;
  label: string;
  path: string;        // 扇区路径
  textPath: string;    // 文字路径
  textPathId: string;
  needReverse: boolean;
}

8. 使用示例

8.1 基本使用

<template>
  <Luopan :size="520" />
</template>

<script setup>
import { Luopan } from './src';
</script>

8.2 自定义配置

import { useLuopan } from './src';
import { ref } from 'vue';

const customExample = ref({
  name: '自定义罗盘',
  angles: [0, 45, 90, 135, 180, 225, 270, 315, 360],
  radii: [80, 160, 240]
});

const { sectors } = useLuopan(customExample);

8.3 访问工具函数

import { 
  polarToXY, 
  annularSectorCentroid,
  generateSectorColor 
} from './src';

// 计算特定区域的形心
const centroid = annularSectorCentroid({
  rInner: 50,
  rOuter: 100,
  aStartDeg: 0,
  aEndDeg: 30
});

console.log(`形心位置: (${centroid.cx}, ${centroid.cy})`);

9. 测试

9.1 单元测试覆盖

✅ 极坐标转换（4个方向）
✅ 角度归一化（负数、大于360）
✅ 形心计算（纯扇形、圆环、跨0°）
✅ 路径生成（正常、退化情况）
✅ 颜色生成（色相、亮度）

9.2 运行测试

npm run test          # 运行测试
npm run test:ui       # 测试 UI
npm run test:coverage # 覆盖率报告

10. 性能优化

10.1 计算优化

使用 Vue 的 computed 缓存计算结果
避免重复计算：形心、路径等一次生成
三角函数结果复用

10.2 渲染优化

使用 key 属性优化列表渲染
SVG 路径字符串预生成，避免模板内计算
辅助线可选显示，减少 DOM 节点

11. 扩展性

11.1 支持的扩展

✅ 自定义角度分割
✅ 自定义圆环半径
✅ 自定义颜色方案
✅ 自定义文字内容
🔲 图标/图片放置（预留 <foreignObject>）
🔲 交互事件（点击、悬停）
🔲 动画效果

11.2 API 设计原则

纯函数优先，便于测试
类型安全，完整的 TypeScript 支持
组合式 API，灵活复用
渐进式增强，保持简单使用

12. 文字布局与自适应

12.1 文字布局配置常量

所有文字布局相关的魔法数字已集中在 TEXT_LAYOUT_CONFIG 中管理：

export const TEXT_LAYOUT_CONFIG = {
  /** 字符间距系数：1.2 表示字符实际占用高度 = fontSize × 1.2 */
  CHAR_SPACING_RATIO: 1.2,
  
  /** 径向留白比例：0.8 表示文字占用 80%，上下各留 10% */
  RADIAL_PADDING_RATIO: 0.8,
  
  /** 切向留白比例：0.85 表示文字占用 85%，左右各留 7.5% */
  TANGENT_PADDING_RATIO: 0.85,
  
  /** 小角度扇区字体缩放：防止弧线弯曲导致视觉溢出 */
  SMALL_ANGLE_SCALE: {
    TINY_THRESHOLD: 15,   // < 15° 应用 70% 缩放
    TINY_SCALE: 0.7,
    SMALL_THRESHOLD: 30,  // 15°-30° 应用 85% 缩放
    SMALL_SCALE: 0.85,
  },
  
  /** 字体大小限制 */
  FONT_SIZE: {
    MIN: 3,   // 最小 3px
    MAX: 24,  // 最大 24px
  },
  
  /** 竖排文字字符数范围 */
  VERTICAL_TEXT: {
    MIN_CHARS: 1,
    MAX_CHARS: 4,
  },
}

12.2 字体大小自适应算法

横排文字（沿弧线）

字体大小同时受径向高度和弧长双重约束：

// 1. 径向高度约束
maxByHeight = radialHeight × RADIAL_PADDING_RATIO

// 2. 弧长宽度约束
arcLength = rMid × deltaDeg × π/180
availableArcLength = arcLength × TANGENT_PADDING_RATIO
maxByWidth = availableArcLength / (textLength × 1.1)

// 3. 取较小值
calculatedSize = min(maxByHeight, maxByWidth)

// 4. 小角度额外缩放
if (deltaDeg < 15°) calculatedSize × 0.7
else if (deltaDeg < 30°) calculatedSize × 0.85

关键点：

1.1 系数包含字符宽度(1.0) + 字符间距(0.1)
小角度缩放是因为弧线弯曲使文字在视觉上"更胖"

竖排文字（沿径向）

竖排文字沿径向排列，受不同约束：

// 1. 径向高度约束（主要）
availableHeight = radialHeight × RADIAL_PADDING_RATIO
maxByHeight = availableHeight / (textLength × CHAR_SPACING_RATIO)

// 2. 最内侧字符的弧长约束（防止最里面的字溢出）
estimatedFontSize = radialHeight × 0.5
innerMostRadius = rInner + estimatedFontSize / 2
innerArcLength = innerMostRadius × deltaDeg × π/180
availableArcLength = innerArcLength × TANGENT_PADDING_RATIO
maxByWidth = availableArcLength  // 单个字符宽度

// 3. 取较小值
calculatedSize = min(maxByHeight, maxByWidth)