HarmonyOS Next实战：Canvas自绘圆形进度条与HSV取色盘打造智能灯泡控制界面

做智能家居控制页，亮度调节用横向的Slider总感觉不够直观，尤其当你面对的是一个“灯泡”时，大家更习惯像拧旋钮一样去操作。这节HarmonyOS Next的实操课，我们就来做一版更有质感的智能灯泡控制界面：用Canvas自绘圆形进度条调亮度，再配一个颜色选择器切换灯光颜色。整个界面全部基于ArkTS/ArkUI完成，不依赖第三方库，适合已经会写基础页面、想进阶自定义组件和绘制的同学参考。我会把圆形进度条、HSV取色盘、状态联动和调试踩坑都完整过一遍。

1. 需求拆解与界面布局设计

1.1 智能灯泡控制界面需要哪些交互元素

动手前先想清楚：一个智能灯泡的控制页，本质上就三件事——开关、亮度、颜色。高级一点还有色温和场景模式，但这一课我们先聚焦亮度和颜色。

拆成交互任务来看：

这个表格也基本决定了页面的信息架构。顶部放设备名和开关，中间是灯光预览和亮度圆环，底部是颜色选择区。不要把亮度滑块塞到颜色区的下面，智能家居App的交互习惯是：用户在哪个区域操作，视觉焦点就在哪个区域，中间的大圆环本身就是天然的视觉锚点。

还有一个容易忽略的点：灯泡的亮度变化不应该只改变圆环的进度，还要实时改变灯光预览的明暗。这就需要把“亮度”和“颜色”抽象成一个统一的状态对象，而不是散落成七八个@State变量，否则联调时会非常痛苦。

1.2 基于ArkUI的栅格布局规划

HarmonyOS Next的ArkUI布局核心是Flex和Stack。这一页我建议用Column做纵向排列，内部用Stack层层叠加。

页面结构大概是这样：

arkts复制build() {
  Column({ space: 24 }) {
    // 顶栏：设备信息 + 开关
    Row() { ... }

    // 中间：圆形进度条 + 灯光预览
    Stack() {
      CircleProgressBar({ progress: this.light.brightness })
      LightPreview({ color: this.light.color, brightness: this.light.brightness })
    }
    .width('100%')
    .height(320)

    // 下方：颜色选择器
    ColorPicker({ light: this.light })
  }
  .padding(16)
  .width('100%')
  .height('100%')
}

这里有几个细节：

1. 圆形进度条和灯光预览不要做成两个平行的子组件，而是用Stack叠起来。进度条是一个空心圆环，中间区域是空的，正好放“灯泡发光”的预览，这样亮度调节和颜色反馈的距离最近，操作视线不用来回跳。
2. 颜色选择器区域要控制高度，不要撑得太高。智能灯泡页面通常还会放“色温”“收藏颜色”这些扩展项，颜色区只占下三分之一比较合理。
3. 用Column时，子组件之间的间距用space参数比手动加margin更干净。但要留意，如果某个子组件需要使用layoutWeight(1)占满剩余空间，space依然生效，两边不会打架。

布局这块我强调一点：不要为了好看把圆环做得太小。圆形进度条一旦小于屏幕宽度的60%，手指拖拽时角度稍微一动，亮度就跳好几个百分点，很难精准控制。我一般会把圆环外径控制在260vp左右，内径留出150vp给灯光预览。

2. 圆形进度条实现：从组件到自绘Canvas

2.1 为什么不用现成Slider而要自己画

ArkUI里明明有Slider和Progress组件，为什么还要自己画圆形进度条？

因为产品形态不对。Slider是横向线性轨道，哪怕设置了SliderStyle也只是换皮肤，交互轨迹还是“从左往右”。而我们需要的是“绕着圆环拖拽”，这是两种维度的事。虽然也可以把横向Slider旋转90度或者弯成弧形，但性能和可控性都很差，而且圆弧上的进度渐变效果很难做。

Progress组件就更不用说了，它是展示型组件，不能交互。

自己用Canvas绘制圆环的好处有三个：

• 可以精确控制弧线的起始角度、结束角度和圆角；
• 可以在弧线上加渐变、阴影、辉光，做出来更有“灯光”质感；
• 手势和绘制逻辑完全掌握在手里，后续加色温环、情景模式环都是同一套底层代码。

代价是，你需要懂一点Canvas绘图和角度映射的数学。这个不算难，下面我一步步拆开。

2.2 Canvas绘制圆形进度条的数学基础

先明确三个基础概念：圆心、半径、线宽。

在ArkUI中，Canvas控件有宽和高，假设宽高都是260，那么圆心坐标就是(130, 130)。圆环半径指的是“圆弧中心线”的半径，取90。线宽取24，这样圆环的内边缘到圆心距离是90 - 12 = 78，外边缘到圆心距离是90 + 12 = 102。绘制时用的ctx.arc的坐标就是这个半径90。

绘制圆弧的基本API：

typescript复制this.context.beginPath();
this.context.strokeStyle = '#E8EDF2';
this.context.lineWidth = 24;
this.context.arc(130, 130, 90, 0, Math.PI * 2);
this.context.stroke();

这段代码画的是一个灰色底环。重点来了：进度弧线从哪里开始？按习惯，亮度圆环应该从12点钟方向开始，顺时针绕一圈。但Canvas的arc方法默认是从3点钟方向为0弧度，逆时针为负。所以我们要把起始角度设为-Math.PI / 2。

进度值到角度的换算公式：

typescript复制const startAngle = -Math.PI / 2;
const endAngle = startAngle + (this.progress / 100) * Math.PI * 2;

progress是0到100的数字。当progress = 100时，endAngle = -PI/2 + 2PI，刚好画满一个圆。

背景圆环和进度弧线分开画。进度弧线可以给渐变色，比如从#FFD194到#70E1F5，模拟灯光从暖到冷的变化。HarmonyOS Canvas支持createLinearGradient，但线性渐变是沿着直线方向的，用在圆弧上是从某个方向往另一个方向渐变，不是沿弧线。如果想做“圆弧上的渐变”，通用的做法是分段画弧，每几度换一个颜色，这是后话，这里先用整体渐变也能看。

2.3 手势拖拽控制进度值的交互实现

绘制是底座，真正让用户觉得“这圆环能用”的是拖拽交互。

在Canvas上绑定onTouch事件，核心逻辑是：把触摸点的坐标转换成相对圆心的角度，再把角度映射成进度。

typescript复制.onTouch((event: TouchEvent) => {
  if (event.type === TouchType.Down || event.type === TouchType.Move) {
    const touch = event.touches[0];
    const angle = this.calculateAngle(touch.x, touch.y);
    this.progress = Math.round((angle / 360) * 100);
    this.draw();
  }
})

calculateAngle的实现：

typescript复制private calculateAngle(touchX: number, touchY: number): number {
  const centerX = this.radius;
  const centerY = this.radius;
  // 计算触摸点相对于圆心的弧度
  const rad = Math.atan2(touchY - centerY, touchX - centerX);
  // 转角度，并让0度落在12点钟方向
  let deg = rad * 180 / Math.PI + 90;
  // 归一化到 0~360
  if (deg < 0) deg += 360;
  return deg;
}

为什么加90度？因为atan2返回的角度以3点钟方向为0度，逆时针为正。所以atan2(0, -r)得到的是90度（正上方），我们要让正上方变成0度，就需要减去90度，或者在计算后加90度再归一化，这里用的就是后一种。

这里有个体验细节：触摸点不一定刚好落在圆环上，手指可能滑到圆环内部。所以每次拿到触摸坐标后，要算一下触摸点到圆心的距离。如果距离落在圆环线宽附近，才更新进度；如果距离太靠近圆心，说明用户可能想操作中间的灯光预览，这时候不应该触发进度更新。

typescript复制const dist = Math.sqrt((touch.x - centerX) ** 2 + (touch.y - centerY) ** 2);
const minDist = this.radius - this.lineWidth / 2 - 20;
const maxDist = this.radius + this.lineWidth / 2 + 20;
if (dist < minDist || dist > maxDist) return;

这个20vp的容错空间很重要，手指不是点像素，有一定接触面积，给点余量体验会好很多。

绘制函数里别忘了每次重绘前先清空画布：

typescript复制private draw() {
  const ctx = this.context;
  ctx.clearRect(0, 0, this.radius * 2, this.radius * 2);
  // 画背景环
  // 画进度弧
}

滑动过程中，onTouch事件触发频率很高，一般不建议每触发一次就更新父组件的@State然后把整个页面重刷一遍。更好的做法是：滑动过程中只更新这个子组件内部的一个@State progress，同时调draw()；在TouchType.Up结束时，才把这个值同步给父组件的状态对象。这样既保证视觉流畅，也避免总控指令像倒豆子一样往外发。

3. 颜色选择器：预置色块与HSV取色盘的实现

3.1 预置色块与HSV取色盘的分工

颜色选择是智能灯泡的另一个重点。很多人一上来就想做复杂的色盘，我建议分两步：常用色块 + 精细取色。

预置色块解决的是“快”的问题。用户最常见的需求是“帮我调成暖黄色”“来一个粉色”，你在色盘上一点点找太慢了。所以我强烈建议在颜色区顶部放一排预置颜色，比如白光、暖黄、粉色、淡青、浅蓝、紫色。点击后直接切换，同时更新色盘上的选中位置。

色盘解决的是“准”的问题。用户想要一个介于蓝和紫之间的独特颜色，这时候就必须能任意取色。这里我们要做一个HSV取色盘。HSV比RGB更符合人对颜色的直觉：H是色相，S是饱和度，V是明度。调灯光时，用户对“色相”最敏感，然后是饱和度和亮度。

这一课我实现的色盘由一个色相圆环和一个饱和度/亮度方块组成。色相圆环负责选H，SV方块负责选S和V。这样交互路径清晰：先在环上转一圈定出主色，再在方块里点一下定浓淡。

3.2 用Canvas绘制色相渐变圆环

色相环的绘制原理比较简单：360个色相，绕圆环一周，每个角度对应一个颜色。我们可以用循环画360条极短的弧线，每条弧线用对应的hsl颜色画，视觉上就形成了一个连续渐变的圆环。

核心代码：

typescript复制for (let i = 0; i < 360; i++) {
  ctx.beginPath();
  ctx.strokeStyle = `hsl(${i}, 100%, 50%)`;
  ctx.lineWidth = 32;
  const startAngle = (i - 90) * Math.PI / 180;
  const endAngle = (i - 89) * Math.PI / 180;
  ctx.arc(centerX, centerY, ringRadius, startAngle, endAngle);
  ctx.stroke();
}

第2行用模板字符串生成hsl颜色，第6行每个颜色只画1度。为什么要用i - 89而不是i？因为每条弧线画的范围是[i-90, i-89]，刚好1度，360条拼满。

注意一个细节：循环画弧线时，相邻两条弧线之间容易出现细微的透明缝隙，这是抗锯齿导致的。解决方法是把线帽设为圆角：

typescript复制ctx.lineCap = 'LineCapStyle.Round';

或者每段多画0.2度，比如让endAngle = (i - 89.8) * Math.PI / 180，两端就会重叠，缝隙自然消失。我用的是后者，因为round线帽会让环的内外边缘凸出一点，破坏边界识别的精度。

色相环的触摸取色逻辑很简单，和圆形进度条几乎一样：拿触摸点算角度，映射到0~360的色相值。

typescript复制const rad = Math.atan2(touchY - centerY, touchX - centerX);
let hue = rad * 180 / Math.PI + 90;
if (hue < 0) hue += 360;

这样hue就是用户当前选中的色相。

3.3 饱和度与亮度选择区：两层线性渐变实现SV方块

色相定下来后，需要一块区域让用户调饱和度和明度。经典做法是画一个矩形SV方块：

• 背景色是当前色相、饱和度和明度都为100%的纯色；
• 水平方向从左到右叠加一层“白色到透明”的渐变，对应饱和度从左到右从0到100%；
• 垂直方向从下到上叠加一层“透明到黑色”的渐变，或者从上到下的黑色渐变，对应明度从上到100%到下到0%。

代码：

typescript复制const hsvColor = `hsl(${this.hue}, 100%, 50%)`;
ctx.fillStyle = hsvColor;
ctx.fillRect(0, 0, width, height);

// 横向：白到透明，控制饱和度
const gradientX = ctx.createLinearGradient(0, 0, width, 0);
gradientX.addColorStop(0, '#ffffff');
gradientX.addColorStop(1, 'rgba(255, 255, 255, 0)');
ctx.fillStyle = gradientX;
ctx.fillRect(0, 0, width, height);

// 纵向：透明到黑，控制明度
const gradientY = ctx.createLinearGradient(0, 0, 0, height);
gradientY.addColorStop(0, 'rgba(0, 0, 0, 0)');
gradientY.addColorStop(1, '#000000');
ctx.fillStyle = gradientY;
ctx.fillRect(0, 0, width, height);

这段代码不长，但很关键。解释一下原理：HSL颜色空间中，hsl(H, 100%, 50%)是当前色相最纯的颜色。叠加白色的渐变后，左边为白，即饱和度0%；右边为纯色，饱和度100%。再叠加黑色渐变，下面为黑，即明度0%；上面保持原色，明度100%。两个渐变叠加，就得到了整个S、V二维平面。

取色时，根据触摸点坐标比例：

typescript复制const ratioX = touchX / width;
const ratioY = touchY / height;
const saturation = ratioX * 100;
const value = (1 - ratioY) * 100;

然后用HSVtoRGB转成十六进制颜色。转换公式稍长，可以直接在网上找标准实现，或者用现成的ColorUtils。HarmonyOS有自己的Color工具类，但HSV转换建议自己封装一个纯函数，方便单测。

这一块我踩过一个小坑：SV方块的黑色渐变方向。如果习惯从上往下写rgba(0,0,0,1)到透明，那么方块的顶部是黑、底部是亮，这跟直觉相反。一定要想清楚：明度100%在上，明度0%在下，所以黑色透明渐变应该是从上透明到下黑色。

4. 灯光状态模型与联动逻辑

4.1 用@Observed类管理灯光状态

前面说了不要让状态散落成多个变量，这里给出具体方案。在ArkTS里可以用@Observed装饰一个数据类，让它的属性变化能被页面观测到。

typescript复制@Observed
class LightState {
  brightness: number = 100;
  hue: number = 200;
  saturation: number = 80;
  value: number = 90;

  get color(): string {
    return this.hsvToRgb(this.hue, this.saturation, this.value);
  }

  hsvToRgb(h: number, s: number, v: number): string {
    // 标准HSV转RGB实现，返回 #RRGGBB
  }
}

页面里这样用：

typescript复制@State light: LightState = new LightState();

然后把light传给子组件：

• 圆形进度条组件只需要读写brightness；
• 颜色选择器读写hue、saturation、value；
• 灯光预览组件读取color和brightness。

如果子组件需要双向修改LightState里的某个属性，可以用@ObjectLink light: LightState。这个装饰器会把子组件和对象的属性关联起来，属性一变，用到的地方自动刷新。

为什么用@Observed而不是多个@State？因为当亮度和颜色需要联动时，一个状态对象可以天然表达“同属于一台设备”的语义。比如后面接入多灯泡场景，一个房间多个灯，每个灯实例化一个LightState，代码结构完全复用。

4.2 亮度与颜色如何联动显示

亮度100%时，灯光预览显示color的原始颜色。亮度降到50%时，预览颜色应该整体变暗，但又不应该是纯粹的RGB乘0.5，那样会显得很假。

我通常用一个近似公式：

typescript复制function applyBrightness(color: string, brightness: number): string {
  // 先把color拆成r,g,b
  const factor = brightness / 100;
  const adjustedR = Math.round(r * factor + 255 * (1 - factor) * 0.05);
  const adjustedG = Math.round(g * factor + 255 * (1 - factor) * 0.05);
  const adjustedB = Math.round(b * factor + 255 * (1 - factor) * 0.05);
  return `rgb(${adjustedR}, ${adjustedG}, ${adjustedB})`;
}

后面加的5%白点是为了模拟灯珠的最低辉光。真实的LED灯泡在亮度调到1%时，也不是完全关灯，而是发出很微弱的光，如果直接乘到0，用户会以为灯泡坏了。

另外，当饱和度低于10%时，视觉上灯泡显示的就是白光（白或暖白），这时候再调色相没有意义。建议在UI上把色相环置灰，或者把灯光预览的色温联动逻辑打开。这一课先不提色温，但代码里最好预留一个分支：

typescript复制if (this.light.saturation < 10) {
  // 白光模式，色相环禁用或隐藏
}

4.3 模拟设备控制指令的生成

做App只是客户端，最终要把状态变成设备能识别的指令。真实项目里可能是BLE、WiFi、Zigbee等协议，但控制指令的结构大同小异。我们先定义一个接口：

typescript复制interface LightCommand {
  brightness: number;
  color: string;
  timestamp: number;
}

当状态变化后，生成指令并发送：

typescript复制private sendCommand() {
  const command: LightCommand = {
    brightness: this.light.brightness,
    color: this.light.color,
    timestamp: Date.now()
  };
  // 实际通过 socket / ble 发送
  console.log(`[Light] send ${JSON.stringify(command)}`);
}

这里提两个实战中的问题：

1. 指令节流。拖拽亮度时手抖一下，1秒可能触发几十次状态变化，如果每次都发设备指令，设备端会卡死。通常的做法是松手后发最终值，或者几百毫秒内合并最后一条指令。
2. 回查同步。设备可能因为本地旋钮被手动操作，导致App状态和实际状态不一致。App应该定时或在下一次连接时主动查询设备状态，然后反向刷新UI。

这部分属于从“Demo”到“产品”的进阶，本课先做到模拟指令，后续接入真实设备时，替换sendCommand内部实现即可。

5. 实际运行效果与调试经验

5.1 真机与模拟器上常见的渲染问题

我在模拟器上调试时发现，Canvas的圆弧绘制比真机更容易出现边缘模糊。原因是模拟器的GPU渲染和真机不一样，抗锯齿策略也不同。

最典型的问题是色相环每段弧线之间有细缝。在模拟器上看得特别明显，缩放截图后就是一根根短线段。解决方法前面提过，把每段弧线角度重叠0.2度，从根本上消除缝隙，比依赖lineCap更可靠。

另一个问题是ctx.clearRect的坐标和Canvas尺寸的关系。很多同学用Canvas(this.context)时，习惯把宽高写成260，但clearRect里也写ctx.clearRect(0, 0, 260, 260)。如果Canvas在布局中被拉伸，实际绘制坐标是按vp算的，可能会导致清屏范围对不上。稳妥做法是直接在onReady里读取Canvas的实际宽度和高度：

typescript复制.onReady(() => {
  this.componentWidth = this.context.width;
  this.componentHeight = this.context.height;
  this.draw();
})

这样不管组件怎么布局，绘制坐标都不会偏。

还有一个小坑：CanvasRenderingContext2D在不同API版本里，获取width和height的时机不一样。onReady触发时，部分模拟器上this.context.width可能还是0。这时候可以在onReady里加一个微任务延迟再取，或者用componentSize事件提前获取。

5.2 手势冲突与响应区域的几个坑

圆形进度条和色相环都用了onTouch，如果它们的父容器是一个Scroll组件，那么手指在圆环上横向滑动时，会被Scroll判定为页面滚动，导致圆环进度不动，页面却在左右滑。解决方案有三种：

1. 不把这两个组件放进Scroll里。智能灯泡页面内容不多，建议直接用Column撑满全屏，不滚动。
2. 如果确实需要滚动，可以在Scroll的onTouch里判断触摸点在哪个子组件区域，决定是否拦截。
3. 使用HitTestMode控制响应链。在子组件的onTouch回调里返回true表示消费事件，不让它冒泡到父组件。

我在项目里最常用的是第一种，简单直接。智能灯泡控制页就一屏内容，不需要滚动，硬加滚动反而会让手势变复杂。

另一个坑是圆形进度条的“中心空区”。如果用户想在中间的灯光预览区域做上下滑动调色温，结果事件被圆环的onTouch吞了。所以一定要在calculateAngle之前做距离判断。我建议把“圆环响应区”和“中心预览区”分开成两个组件，各自绑定事件，或者用Stack叠两层，圆环在下层，预览在上层并设置.hitTestBehavior( HitTestMode.Block)，这样点击预览时，事件不会穿透给圆环。

5.3 性能优化：Canvas重绘与状态更新策略

Canvas重绘其实不便宜，尤其是色相环360段弧线，每次绘制都要重建路径。如果用户在色相环上快速拖动，每一帧都全量重绘，CPU占用会明显上升。

我的优化策略是分层绘制：

• 色相环本身不会频繁变化，只在用户拖动色相环时才重绘，可以接受。
• SV方块需要跟随色相变化，每当色相改变，SV方块的背景色就变，所以要重绘。
• 圆形进度条只在亮度变化时重绘。

所以不要把三块东西画在同一个Canvas里，而是拆成三个独立Canvas组件。哪个变了，只重绘哪个。这个思路和拆组件是一样的：CircleProgressBar、HueRing、SaturationValueBox各自负责自己的绘制，互不干扰。

状态更新方面，我建议在拖拽过程中不要实时更新父组件的LightState，而是让子组件内部维护一个“过渡值”，松手后再提交。具体做法：

typescript复制.onTouch((event: TouchEvent) => {
  if (event.type === TouchType.Move) {
    this.tempProgress = this.calcProgress(touch.x, touch.y);
    this.draw();
  } else if (event.type === TouchType.Up) {
    this.tempProgress = this.calcProgress(touch.x, touch.y);
    this.onChange(this.tempProgress); // 提交给父组件
  }
})

这样拖拽时只有子组件自己在重绘，父组件和其他兄弟组件不会跟着刷。性能体验和指令频率都得到控制。我在实际调测中发现，这样一来页面帧率能稳定在60帧，而如果全程更新父组件，偶尔会掉到30帧左右。

最后一个建议：把绘制逻辑抽成纯函数。比如“根据进度画圆环”“根据HSV画SV方块”，不要在组件事件里写一堆绘制代码。这样后续做单元测试、迁移到其他平台都方便。HarmonyOS Next自己的Canvas API在不同版本间有一些调整，集中封装也好适配。

这节内容按这个思路做完，基本就能得到一个能跑的智能灯泡控制界面。碰到渲染或手势问题，先从事件冲突和Canvas重绘时机入手排查，大部分坑都能解决。后面如果要把模拟指令换成真实的蓝牙灯，只需要替换最后那一小段sendCommand的内容，界面层的圆形进度条和颜色选择器完全可以原样复用。