一、技术前言

在表达力教育与职场软技能训练领域，演讲口才是连接思想与听众的核心桥梁。从开场三分钟破冰到金字塔表达逻辑，从情绪感染力点燃到语速节奏控制，每一项训练都需要精准的能力评估、实时的影像反馈和结构化的复盘追踪。传统口才训练应用往往面临三大痛点：练习时取景构图失控导致画面空洞、AI 字幕语言方向单一导致跨语种训练断裂、表达力评估维度扁平导致学员无法感知短板。

HarmonyOS ArkUI 框架以其声明式 UI 范式为这些问题提供了系统级的解决方案。ArkUI 基于 TypeScript 扩展的 ArkTS 语言，通过 @Component 装饰器封装可复用组件，通过 @State、@Observed 等状态管理装饰器实现数据驱动渲染，通过 @Builder 方法将复杂的 UI 结构拆分为可组合的构建块。@Entry 装饰的根组件作为页面入口，配合 build() 方法中的声明式 DSL（Stack、Column、Row、Scroll、List 等容器）实现从数据到视图的单向流转。ForEach 的键值回调机制保证了列表项的高效复用与精准更新，而 @Observed 装饰的数据模型类则实现了字段级的细粒度响应式追踪。这种架构天然适合口才训练场景中"取景-字幕-评估-复盘"紧耦合的需求。

本平台深度融合了 HarmonyOS 6.1.1 的四大前沿特性。Camera Kit 提供了 VideoSession 的 AUTO_FRAMING（影随人动）能力链——通过 isControlCenterSupported、getSupportedEffectTypes、enableControlCenter 三步实现演讲取景时人员始终居中构图；同时 PhotoSession 的手动对焦三接口 isFocusDistanceSupported、setFocusDistance、getFocusDistance 实现铭牌近拍到全场舞台的精确对焦控制。Speech Kit 的 AICaptionComponent 实现了 AI 字幕定制链路——通过 sourceLanguage、targetLanguage、fontSize、fontColor 四个新增字段实现字幕语言方向、字号档位、字体颜色的全维度自定义，配合 AICaptionController.writeAudio 写入 PCM 音频流驱动实时转写。Canvas 绘制了表达力五维雷达图——通过 CanvasRenderingContext2D 的多边形路径、渐变填充、数据点标注实现台风/逻辑/感染力/语速/眼神五维能力的可视化评估。XComponent 的 SURFACE 类型为相机预览提供了原生 Surface 通道，onLoad 回调驱动 Surface 就绪标记联动会话生命周期。

二、整体架构流程图

整体架构以根组件为核心，采用 Stack 容器实现页面层叠：底层是 Column 纵向布局的头部横幅 + 内容区滚动容器 + 底部 Tab 栏，顶层是全屏弹窗遮罩。内容区通过 currentTab 状态索引在 6 个 @Builder 方法间分支切换，每个 Tab 拥有完全独立的布局结构。四大特性（Camera Kit 影随人动、手动对焦、Speech Kit AI 字幕、Canvas 雷达图）分别挂载在相机、对焦、字幕、舞台四个 Tab 上，但它们的状态变量统一声明在组件顶层，实现跨 Tab 数据共享。弹窗系统通过 addModal、editModal、delModal 三个布尔状态控制显隐，遮罩层点击即关闭，形成轻量的模态交互闭环。

三、色彩体系设计

3.1 ColorPalette 接口定义

平台采用深色舞台紫主题，模拟聚光灯下的深夜舞台氛围，通过 ColorPalette 接口集中声明全部颜色字段：

interface ColorPalette {
  bg: string;      // 全局背景（深夜舞台）
  card: string;    // 卡片底色
  title: string;   // 主标题
  sub: string;     // 副标题
  text3: string;   // 弱化文字
  purple: string;  // 舞台紫主色
  purpleD: string; // 舞台紫深色
  gold: string;    // 聚光金
  blue: string;    // 信息蓝
  red: string;     // 警示红
  green: string;   // 通过绿
  line: string;    // 分割线
  tabOn: string;   // 底部 Tab 选中色
  mask: string;    // 弹窗遮罩
}

3.2 COLORS 常量逐色分析

const COLORS: ColorPalette = {
  bg: '#171226',      // 极深舞台紫黑，模拟无聚光灯时的剧场暗场
  card: '#221B38',    // 卡片底色，比背景略亮一档
  dark: '#2C2347',    // 次级容器底色（统计格 / 进度条底 / 效果枚举行）
  title: '#F2EDFA',   // 暖白标题，高对比度保证舞台暗光可读
  sub: '#C0B4DC',     // 紫灰副标题，层次柔和过渡
  text3: '#857AA8',   // 暗紫弱文本，辅助信息不抢视觉焦点
  purple: '#8B5CF6',  // 舞台紫主色，按钮与雷达图数据多边形
  purpleD: '#6D3FD6', // 深紫渐变起点，头部横幅到背景的过渡
  gold: '#F5C04E',    // 聚光金，等级徽章与选中态视觉锚点
  blue: '#4EA3E3',    // 信息蓝，读回值与翻译方向标识
  green: '#4EC98A',   // 通过绿，已生效与已授权状态
  red: '#E85B6E',     // 警示红，失败与删除操作
  line: '#35294F',    // 分割线，低对比度不干扰内容
  tabOn: '#F5C04E',   // Tab 选中色与聚光金一致
  mask: 'rgba(0,0,0,0.6)' // 半透黑遮罩
};

色彩设计遵循"舞台聚光"原则：紫金蓝绿红五色分别对应"主品牌/焦点强调/信息参考/通过确认/危险警告"五种语义状态。舞台紫 #8B5CF6 作为主色贯穿按钮、雷达图填充、横幅渐变；聚光金 #F5C04E 作为视觉焦点用于等级徽章、评分数值、Tab 选中态，使用户在深色环境下凭金色即可快速定位关键信息。头部横幅的 linearGradient 从 purple 到 purpleD 实现舞台紫的纵深过渡，底部 6 Tab 栏选中态使用 gold 高亮，未选中态使用 text3 暗紫弱化，形成聚光灯打在当前 Tab 上的视觉效果。

四、Tab 元数据与常量定义

4.1 底部导航 Tab 定义

底部导航采用 6 Tab 单排结构，每个 Tab 由图标 emoji 与中文标签组成：

const TAB_LIST: TabMeta[] = [
  { icon: '🎤', label: '舞台' },
  { icon: '📷', label: '相机' },
  { icon: '🎯', label: '对焦' },
  { icon: '🗣', label: '字幕' },
  { icon: '📊', label: '复盘' },
  { icon: '👤', label: '我的' }
];

6 个 Tab 按演讲训练流程排列：舞台展示课程与能力评估，相机提供影随人动取景，对焦实现精确构图，字幕辅助跨语种训练，复盘追踪练习记录，我的展示学员成就。这种编排让学员从"选课-取景-对焦-字幕-复盘-个人"形成完整的训练闭环。

4.2 Camera Kit 效果枚举与对焦预设

ControlCenterEffectType 效果枚举演示了 Camera Kit 控制中心支持的三种效果类型：

const EFFECT_INFOS: EffectInfo[] = [
  { type: 0, name: 'BEAUTY', desc: '美颜 · since 20' },
  { type: 1, name: 'PORTRAIT', desc: '人像 · since 20' },
  { type: 2, name: 'AUTO_FRAMING', desc: '影随人动 · 6.1.1 新增' }
];

其中 AUTO_FRAMING（值为 2）是 HarmonyOS 6.1.1 新增的影随人动能力，通过 enableControlCenter(true) 请求系统接管构图，使演讲者在画面中始终居中。对焦预设则映射了三种演讲景别：

const FOCUS_PRESETS: FocusPreset[] = [
  { label: '近拍', distance: 0.1, scene: '0.1 · 铭牌演讲稿' },
  { label: '中距', distance: 0.5, scene: '0.5 · 半身演讲' },
  { label: '远距', distance: 0.9, scene: '0.9 · 全场舞台' }
];

三档预设从 0.1（镜头最近可对焦距离）到 0.9（接近最远），覆盖铭牌演讲稿特写、半身演讲构图、全场舞台收纳三种典型场景，点击即设焦并自动读回验证。

4.3 Speech Kit 语言与字号选项

AI 字幕的语言方向设计遵循"源语言决定目标语言可选域"的联动规则。源语言取值 ['zh', 'en']，当源语言为中文时目标语言锁定 'zh'（无翻译方向可选），当源语言为英文时目标语言可选中文、英文或中英双语：

const TGT_LANGS_EN: LangOption[] = [
  { code: 'zh', name: '中文' },
  { code: 'en', name: '英文' },
  { code: 'zh-en', name: '中英双语' }
];

字幕字号取 AICaptionFontSize 枚举四档而非裸数字，保证类型安全：

const SIZE_OPTIONS: SizeOption[] = [
  { size: AICaptionFontSize.SMALL, name: '小号' },
  { size: AICaptionFontSize.NORMAL, name: '标准' },
  { size: AICaptionFontSize.BIG, name: '大号' },
  { size: AICaptionFontSize.LARGE, name: '超大' }
];

字体颜色提供五色预设卡，fontColor 为 ResourceColor 类型，'#RRGGBB' 格式即可生效：

const CAPTION_FONT_COLORS: string[] = ['#FFFFFF', '#FFE9B0', '#9CE8B5', '#9CD0FF', '#FFB3C1'];

4.4 雷达图与柱状图数据

表达力五维雷达图覆盖台风、逻辑、感染力、语速、眼神五个维度，数值为 0~1 的归一化值：

const RADAR_LABELS: string[] = ['台风', '逻辑', '感染力', '语速', '眼神'];
const RADAR_VALUES: number[] = [0.82, 0.74, 0.66, 0.88, 0.58];

近 6 个月练习时长柱状图数据以分钟为单位，月度索引与名称分离存储便于 ForEach 遍历：

const MONTH_IDX: number[] = [0, 1, 2, 3, 4, 5];
const MONTH_NAME: string[] = ['03', '04', '05', '06', '07', '08'];
const PRACTICE_VAL: number[] = [42, 55, 61, 58, 73, 84];

五、工具函数体系

平台在组件外部定义了一组纯函数工具，用于状态文案到颜色的映射转换，保持 @Builder 方法内部逻辑简洁。

5.1 影随人动状态颜色映射

function framingStateColor(state: string): string {
  if (state === '影随人动已启用') { return COLORS.green; }
  if (state === '已交还手动构图') { return COLORS.blue; }
  if (state.indexOf('失败') >= 0 || state.indexOf('被拒') >= 0 || state.indexOf('不支持') >= 0) { return COLORS.red; }
  if (state === '未查询') { return COLORS.text3; }
  return COLORS.gold;
}

该函数将影随人动能力链各阶段的文案映射为语义颜色：启用态绿色、交还态蓝色、失败态红色、未查询态暗紫、其余过渡态金色。注意这里有个逻辑细节——失败检测使用 indexOf('失败') >= 0，但当 state 为正常过渡态时，由于不含"失败"“被拒”"不支持"等关键词，会落到末尾返回 COLORS.gold，这与设计意图一致。

5.2 对焦距离景别映射

function distanceLabel(d: number): string {
  if (d < 0.3) { return '近拍景别 · 铭牌演讲稿特写'; }
  if (d < 0.7) { return '中距景别 · 半身演讲构图'; }
  return '远距景别 · 全场舞台收纳';
}

以 0.3 和 0.7 为分界点，将对焦距离 0.0~1.0 的连续区间划分为三档景别文案，为 Slider 调节提供实时景别提示。读回校验结果颜色映射则更简洁：

function readOkColor(ok: string): string {
  if (ok === '已生效') { return COLORS.green; }
  if (ok === '偏差') { return COLORS.gold; }
  return COLORS.red;
}

5.3 等级与评分颜色映射

function levelColor(level: string): string {
  if (level === '入门') { return COLORS.green; }
  if (level === '进阶') { return COLORS.blue; }
  if (level === '大师') { return COLORS.gold; }
  return COLORS.purple;
}

function scoreColor(score: number): string {
  if (score >= 90) { return COLORS.gold; }
  if (score >= 75) { return COLORS.green; }
  if (score >= 60) { return COLORS.blue; }
  return COLORS.red;
}

课程等级三档（入门绿/进阶蓝/大师金）与练习评分四档（90+金/75+绿/60+蓝/60-红）形成统一的颜色语义体系，让学员在浏览课程清单和复盘记录时凭颜色即可判断难度与表现。

5.4 字号枚举与语言码展示

function sizeLabel(size: AICaptionFontSize): string {
  if (size === AICaptionFontSize.SMALL) { return 'AICaptionFontSize.SMALL'; }
  if (size === AICaptionFontSize.BIG) { return 'AICaptionFontSize.BIG'; }
  if (size === AICaptionFontSize.LARGE) { return 'AICaptionFontSize.LARGE'; }
  return 'AICaptionFontSize.NORMAL';
}

function langName(code: string): string {
  if (code === 'en') { return '英文'; }
  if (code === 'zh-en') { return '中英双语'; }
  return '中文';
}

sizeLabel 避免直接打印枚举数字值，输出完整的枚举常量名便于调试；langName 将语言码 'zh'/'en'/'zh-en' 转换为中文展示名。

5.5 时间与统计汇总

function nowTime(): string {
  const d = new Date();
  const pad = (v: number): string => {
    if (v < 10) { return '0' + v; }
    return '' + v;
  };
  return pad(d.getHours()) + ':' + pad(d.getMinutes()) + ':' + pad(d.getSeconds());
}

function totalMinutes(list: PracticeItem[]): number {
  let sum = 0;
  for (const p of list) { sum += p.duration; }
  return sum;
}

function avgScore(list: PracticeItem[]): number {
  if (list.length === 0) { return 0; }
  let sum = 0;
  for (const p of list) { sum += p.score; }
  return Math.round(sum / list.length);
}

nowTime 生成 HH:mm:ss 格式时间戳用于对焦记录时间线，内部用闭包 pad 函数补零。totalMinutes 与 avgScore 是练习记录的统计汇总函数，分别为复盘 Tab 的累计时长卡和平均评分卡提供数据源。

六、数据模型层

平台使用 @Observed 装饰器定义了四个响应式数据模型类，配合 Mock 数据初始化，实现数据与视图的自动同步。@Observed 装饰器的作用机制在于：被装饰的类实例在赋值给 @State 变量后，其字段级变更会被 ArkUI 框架的观察者系统追踪。当代码对实例的某个属性赋新值时（如 target.score = 95），框架自动触发依赖该属性的 UI 组件重新渲染，无需手动调用刷新方法。这与 @State 的引用级响应（整个变量重新赋值才触发更新）形成互补——@State 适合控制 Tab 切换、弹窗显隐等布尔/索引状态，@Observed 适合驱动列表项内字段级动态更新（如编辑练习记录后仅刷新对应卡片而非整个列表）。

6.1 课程模型 LessonItem

@Observed export class LessonItem {
  icon: string;      // 课程图标
  name: string;      // 课程名称
  level: string;     // 难度等级（入门/进阶/大师）
  duration: string;  // 课程时长
  rate: string;      // 课程评分
  constructor(icon: string, name: string, level: string, duration: string, rate: string) {
    this.icon = icon;
    this.name = name;
    this.level = level;
    this.duration = duration;
    this.rate = rate;
  }
}

LessonItem 被舞台 Tab 的横滑大卡和课程清单行共用。Mock 数据包含 8 门课程，覆盖入门到大师全难度梯度，评分从 4.6 到 5.0。@Observed 装饰使该类的字段级变更能被 ArkUI 框架追踪，当课程数据更新时视图自动刷新。

6.2 对焦记录模型 FocusRecord

@Observed export class FocusRecord {
  time: string;      // 操作时间
  distance: number;  // 设定对焦距离
  readback: number;  // getFocusDistance 读回值
  ok: string;        // 校验结果（已生效/偏差/失败）
  constructor(time: string, distance: number, readback: number, ok: string) { ... }
}

对焦记录模型记录每次手动对焦操作的时间、设定值、读回值和校验结果。初始化数据包含三条记录，分别对应中距、近拍、远距三种景别，其中近拍 0.10 设定值读回 0.11 标记为"偏差"，直观展示了镜头最近可对焦距离的物理限制。

6.3 字幕场景模型 CaptionScene

@Observed export class CaptionScene {
  scene: string;  // 场景名
  desc: string;   // 场景说明
  src: string;    // 推荐源语言
  tgt: string;    // 推荐目标语言
  constructor(scene: string, desc: string, src: string, tgt: string) { ... }
}

字幕场景模型封装了五种典型演讲训练场景的推荐语言组合，点击场景卡即一键应用推荐的源语言与目标语言配置。例如"双语答辩模拟"场景推荐英文源、中英双语目标，"中文即兴播报"场景推荐中文源、中文目标（原文直显不翻译）。

6.4 练习记录模型 PracticeItem

@Observed export class PracticeItem {
  date: string;     // 练习日期
  topic: string;    // 练习主题
  duration: number; // 练习时长（分钟）
  score: number;    // AI 评分（0~100）
  constructor(date: string, topic: string, duration: number, score: number) { ... }
}

练习记录模型是复盘 Tab 和弹窗系统的核心实体。Mock 数据包含 8 条记录，日期从 08-10 到 08-28，评分从 64 到 95，覆盖了从"眼神交流巡航术"（64 分）到"TBD 式大师结构"（95 分）的完整表现光谱。该模型同时被统计三卡、进度条清单、新增/编辑/删除弹窗共享。

七、组件主体与生命周期

7.1 状态变量分层声明

根组件 @Entry @Component struct Page1255 内部的状态变量按职责分为五大组：

Tab 与弹窗状态组——currentTab 控制内容区分支切换，addModal/editModal/delModal 三个布尔值控制弹窗显隐，editIdx/delIdx 记录操作目标下标，breath 布尔值驱动呼吸动画与雷达图微波动。timer 为普通成员变量（非 @State）持有定时器 ID。

业务数据组——lessonList、practiceList、sceneList 三个 @State 数组绑定 Mock 数据，@Observed 装饰的模型类实例变更自动触发列表项刷新。

弹窗表单临时状态组——formDate、formTopic、formDuration、formScore 四个字符串字段作为新增/编辑弹窗的表单暂存区，clearForm 统一清空。

Camera Kit 成员组——previewController 为 XComponentController 实例驱动 Surface 预览，cameraInput/previewOutput/videoSession/photoSession 四个可选型私有成员分别持有相机输入、预览输出、影随人动宿主会话、手动对焦宿主会话。注意 videoSession 与 photoSession 不能同时存活——影随人动走 VideoSession 的 ControlCenter 通道，手动对焦走 PhotoSession 的 ManualFocus 通道，模式切换时须先释放前一会话。surfaceReady、sessionMode、cameraGranted 等 @State 变量驱动 UI 状态同步。

Speech Kit 成员组——captionController 为 AICaptionController 实例，captionShown 双向绑定 AICaptionComponent 的 isShown 属性，srcLang/tgtLang/captionSize/captionColor 四个状态分别对应 6.1.1 新增的四字段，captionReady/captionErrMsg/captionFed 追踪字幕服务的就绪态、错误信息与已写入音频块数。

7.2 生命周期与呼吸动画

aboutToAppear() {
  this.timer = setInterval(() => {
    this.breath = !this.breath;
    this.drawRadar();
  }, 1000);
}

aboutToDisappear() {
  clearInterval(this.timer);
  this.releaseSession();
}

aboutToAppear 启动一个每秒触发的定时器，翻转 breath 布尔值并重绘雷达图。breath 的翻转产生两重视觉效果：头部横幅麦克风的透明度在 1 与 0.55 间脉动，雷达图数据值在 ±0.03 范围内微波动，营造"AI 复盘进行中"的呼吸感。aboutToDisappear 清除定时器并释放相机会话，防止后台占用摄像头硬件资源。

7.3 AICaptionOptions 组装与语言联动

buildCaptionOptions(): AICaptionOptions {
  const opts: AICaptionOptions = {
    initialOpacity: 1,
    sourceLanguage: this.srcLang,
    targetLanguage: this.tgtLang,
    fontSize: this.captionSize,
    fontColor: this.captionColor,
    onPrepared: () => { this.captionReady = true; this.captionErrMsg = ''; },
    onError: (error: BusinessError) => {
      this.captionErrMsg = '字幕服务异常 ' + error.code + '：' + error.message;
    }
  };
  return opts;
}

buildCaptionOptions 将四个 @State 变量组装为 AICaptionOptions 对象，每次状态变更都会重新构建选项并传入 AICaptionComponent。onPrepared 回调标记字幕服务就绪，onError 回调捕获异常码并拼接错误文案。

语言联动逻辑通过 switchSourceLang 实现：

switchSourceLang(code: string) {
  this.srcLang = code;
  if (code === 'zh') {
    this.tgtLang = 'zh';
  } else {
    this.tgtLang = 'zh-en';
  }
}

切换源语言时，中文源锁定目标语言为 'zh'（无翻译方向），英文源默认切换为中英双语，用户可再手动选择纯中文或纯英文。applyScene 方法在场景卡点击时调用 switchSourceLang 并按场景推荐覆盖目标语言。

7.4 演示音频流写入

feedAudioStream() {
  const block = new Uint8Array(640);
  for (let i = 0; i < 640; i += 2) {
    const t = (i / 2) / 16000;
    const v = Math.round(Math.sin(2 * Math.PI * 440 * t) * 6000);
    block[i] = v & 0xFF;
    block[i + 1] = (v >> 8) & 0xFF;
  }
  try {
    const audioData: AudioData = { data: block };
    this.captionController.writeAudio(audioData);
    this.captionFed++;
  } catch (e) {
    this.captionErrMsg = '音频写入失败：' + (e as BusinessError).message;
  }
}

feedAudioStream 生成 640 字节的 PCM 音频块（16kHz 采样率、16bit 位深、单声道，约 20ms 时长），内容为 440Hz 正弦波。通过 captionController.writeAudio 写入字幕组件驱动转写演示，每次写入后 captionFed 自增。低位在前（v & 0xFF）、高位在后（(v >> 8) & 0xFF）的小端序写入符合 PCM 标准格式。

八、Camera Kit 双模式会话管理

8.1 相机权限动态申请

async requestCameraPermission(): Promise<boolean> {
  const atManager = abilityAccessCtrl.createAtManager();
  const ctx = this.getUIContext().getHostContext();
  if (ctx === undefined) { this.cameraGranted = false; return false; }
  const result = await atManager.requestPermissionsFromUser(ctx, ['ohos.permission.CAMERA']);
  const granted = result.authResults.length > 0 && result.authResults[0] === 0;
  this.cameraGranted = granted;
  return granted;
}

相机权限为 user_grant 级别，需运行时动态申请。通过 abilityAccessCtrl.createAtManager() 创建权限管理器，调用 requestPermissionsFromUser 弹出系统授权弹窗，authResults[0] === 0 判定已授权。上下文缺失时安全降级返回 false。

8.2 影随人动模式 VideoSession 构建

startVideoMode 方法构建影随人动的完整会话链路。执行流程为：检查 Surface 就绪 → 释放可能存活的 PhotoSession → 申请相机权限 → 获取 CameraManager → 遍历相机列表定位后摄 → 查询 NORMAL_VIDEO 场景的预览 Profile → 创建 CameraInput 并 open → 创建 PreviewOutput 绑定 XComponent SurfaceId → 创建 VideoSession → beginConfig/addInput/addOutput/commitConfig → 调用 queryFraming 走能力链 → start 启动会话。

queryFraming(session: camera.VideoSession) {
  if (!session.isControlCenterSupported()) {
    this.framingState = '控制中心不支持';
    this.framingSupported = false;
    return;
  }
  const effects = session.getSupportedEffectTypes();
  this.framingSupported = effects.includes(camera.ControlCenterEffectType.AUTO_FRAMING);
  if (!this.framingSupported) {
    this.framingState = 'AUTO_FRAMING 未声明';
    return;
  }
  session.enableControlCenter(true);
  this.framingOn = true;
  this.framingState = '影随人动已启用';
}

queryFraming 是影随人动能力链的核心三步：第一步 isControlCenterSupported() 同步查询控制中心是否可用；第二步 getSupportedEffectTypes() 获取支持的效果类型数组，用 includes(AUTO_FRAMING) 判定影随人动是否声明；第三步 enableControlCenter(true) 请求系统接管构图。三步任一失败都会设置对应的 framingState 文案，UI 层通过 framingStateColor 映射为语义颜色展示。

toggleFraming 方法在 VideoSession 存活时调用 enableControlCenter(isOn) 切换接管态，启用时文案为"影随人动已启用"，关闭时文案为"已交还手动构图"。

8.3 手动对焦模式 PhotoSession 构建

switchToPhotoMode 方法构建手动对焦的会话链路，与影随人动模式结构对称但使用 NORMAL_PHOTO 场景。关键差异在于会话启动后调用 queryFocusSupport 而非 queryFraming：

queryFocusSupport() {
  if (this.photoSession === undefined) { this.focusSupported = false; return; }
  this.focusSupported = this.photoSession.isFocusDistanceSupported();
}

isFocusDistanceSupported() 是 PhotoSession 的同步方法，返回当前设备是否支持手动对焦距离调节。Slider 连续调节通过 setFocusLive 实时调用 setFocusDistance，读回验证通过 readBackFocus 调用 getFocusDistance 并与设定值对比，偏差小于 0.01 判定"已生效"：

readBackFocus() {
  const back = this.photoSession.getFocusDistance();
  this.focusReadback = back;
  this.focusResult = Math.abs(back - this.focusDistance) < 0.01 ? '已生效' : '偏差';
  this.focusRecords.unshift(new FocusRecord(nowTime(), this.focusDistance, back, this.focusResult));
  if (this.focusRecords.length > 20) { this.focusRecords.pop(); }
}

每次读回验证都会向 focusRecords 数组 unshift 置顶一条记录，超过 20 条时 pop 尾部，形成滚动时间线。applyFocus 方法组合"设置 + 读回"两步，供预设档位和按钮入口调用。

8.4 会话释放

async releaseSession() {
  const session = this.videoSession ?? this.photoSession;
  const preview = this.previewOutput;
  const input = this.cameraInput;
  this.videoSession = undefined;
  this.photoSession = undefined;
  this.previewOutput = undefined;
  this.cameraInput = undefined;
  this.framingOn = false;
  if (session !== undefined) {
    session.off('error');
    await session.stop();
    await session.release();
  }
  if (preview !== undefined) { await preview.release(); }
  if (input !== undefined) { await input.close(); }
  this.sessionMode = 'idle';
}

releaseSession 是模式切换和组件销毁的统一出口。先用空合并操作符 ?? 取当前存活的会话引用，然后将四个成员变量置空（防止异步释放过程中被其他方法误用），再依次 off('error') 解绑监听、stop() 停止会话、release() 释放会话、释放预览输出、关闭相机输入，最后将 sessionMode 归位为 'idle'。try-catch 包裹确保单步失败不阻断后续释放。

九、Canvas 表达力五维雷达图

drawRadar 方法通过 CanvasRenderingContext2D 绘制表达力五维雷达图，是该平台 Canvas 特性的核心实现。绘制过程分为五个阶段：

背景多边形（3 层）——以中心点 (115, 115) 为圆心，半径 68，从内到外绘制三层等比例缩小的五边形网格。每层多边形通过遍历五个维度角度（-π/2 + (i/n) * 2π）计算顶点坐标，moveTo + lineTo 连线后 closePath + stroke 描边，描边色为 COLORS.line 暗紫分割线。

轴线——从圆心到最外层多边形顶点绘制五条放射轴线，视觉上将雷达图划分为五个扇区。

数据多边形——breath 联动产生 ±0.03 的数据微波动（wob = this.breath ? 0.03 : -0.03），叠加到 RADAR_VALUES 后钳制在 [0.1, 1] 区间。数据多边形先以 globalAlpha = 0.3 半透明填充舞台紫，再恢复 globalAlpha = 1 以线宽 2 描边，形成"填充 + 描边"的双层效果。

数据点——在每个维度顶点绘制半径 4 的金色圆点，arc(x, y, 4, 0, 2π) + fill，作为数据多边形的顶点强调。

标签——在半径 r + 14 的外圈位置，以 10px sans-serif 字体居中对齐绘制五个维度标签（台风/逻辑/感染力/语速/眼神），textAlign = 'center' 配合 y + 3 微调垂直居中。

整个雷达图在 aboutToAppear 的定时器中每秒重绘一次，breath 翻转驱动数据值微波动，形成"AI 复盘进行中"的动态呼吸效果。Canvas 通过 Canvas(this.radar_ctx) 组件挂载，.onReady 回调确保上下文就绪后首次绘制。值得注意的是，radar_ctx 声明为 private 而非 @State——因为 Canvas 的重绘是通过直接调用 drawRadar 方法操作上下文完成的，不需要框架追踪上下文引用的变化。如果将 radar_ctx 声明为 @State，反而会在每次重绘时触发不必要的组件级 diff，造成性能浪费。clearRect(0, 0, 240, 240) 在每帧绘制前清空画布，避免多帧叠加产生残影。数据值的 wob 波动经过 Math.max(0.1) 和 Math.min(1) 双向钳制，确保波动不会超出雷达图的有效半径范围。

十、头部舞台横幅详解

@Builder headerStage() {
  Column({ space: 10 }) {
    Row() {
      Column({ space: 2 }) {
        Text('声量学院').fontSize(18).fontColor(COLORS.title).fontWeight(FontWeight.Bold)
        Text('聚光灯下的表达力训练场').fontSize(10).fontColor(COLORS.text3)
      }.alignItems(HorizontalAlign.START)
      Blank()
      Row({ space: 6 }) {
        Text('🎤').fontSize(14)
        Text('Lv.6 舞台新星').fontSize(10).fontColor(COLORS.gold)
      }.padding({ left: 10, right: 10, top: 5, bottom: 5 })
      .backgroundColor(COLORS.dark).borderRadius(14)
    }.width('100%')
    Row({ space: 12 }) {
      Column({ space: 4 }) {
        Text('今日简报').fontSize(10).fontColor(COLORS.gold).fontWeight(FontWeight.Bold)
        Text('已完成 1 次跟练 · 表达力 +2.4').fontSize(12).fontColor(COLORS.title)
        Text('连续训练 21 天，保持舞台手感').fontSize(9).fontColor(COLORS.sub)
      }.alignItems(HorizontalAlign.START).layoutWeight(1)
      Column() {
        Text('🎙').fontSize(26).opacity(this.breath ? 1 : 0.55)
      }.padding(8)
    }.width('100%').padding(14).borderRadius(14)
    .linearGradient({ angle: 135, colors: [[COLORS.purple, 0.0], [COLORS.purpleD, 1.0]] })
  }.width('100%').padding({ left: 12, right: 12, top: 10, bottom: 10 }).backgroundColor(COLORS.bg)
}

头部横幅分为上下两行。上行左侧是品牌名"声量学院"加副标题"聚光灯下的表达力训练场"，右侧是等级徽章胶囊（圆角 14、深紫底、金色文字"Lv.6 舞台新星"）。下行是今日简报渐变横幅，135 度角从舞台紫渐变到深舞台紫，左侧三行简报文案（金色标题 + 暖白内容 + 紫灰辅助），右侧麦克风 emoji 的透明度随 breath 在 1 与 0.55 间脉动，形成聚光灯下麦克风的呼吸光效。

十一、各 Tab 内容区分析

11.1 Tab0 舞台：课程展示与能力评估

舞台 Tab 由四个区块纵向堆叠：每日金句卡、精选课程横滑大卡、表达力五维雷达图、课程清单行。

每日金句卡以灯泡 emoji 引导，展示固定金句"好的演讲不是背诵，而是把思想放进听众的口袋"，maxLines(2) + textOverflow(Ellipsis) 保证长文本优雅截断。

横滑课程大卡通过 Scroll().scrollable(ScrollDirection.Horizontal) 实现横向滚动，ForEach 遍历 lessonList 渲染 lessonBigCard。每张大卡宽 132，包含课程图标（30px emoji）、课程名、等级标签（levelColor 映射颜色）+ 时长、星级评分 + 操作按钮。首张卡片按钮文案为"热练中"（金底深字），其余为"跟练"（深紫底紫灰字），通过 idx === 0 条件分支实现视觉区分。

雷达图卡内嵌 Canvas 组件并展示"AI 复盘中 ●/○"的呼吸状态指示，breath 为真时金色实心圆、为假时暗紫空心圆。

课程清单行使用 List + ListItem 结构，每行包含图标、课程名、等级 + 时长、评分、播放箭头，通过 layoutWeight(1) 让课程名列自适应宽度。

11.2 Tab1 相机：影随人动能力链全景

相机 Tab 包含五个区块：授权状态卡、XComponent 预览 + 模式切换、会话三态状态卡、效果枚举卡、能力链三步状态卡。

授权状态卡展示 cameraGranted 的授权态文案（绿色"已授权"或暗紫"未授权"），按钮文案动态切换（“申请相机权限”/“重新申请权限”），点击调用 requestCameraPermission。

XComponent 预览区以 XComponentType.SURFACE 类型创建预览组件，onLoad 回调将 surfaceReady 置真。下方两个按钮"开启影随人动"和"停止跟拍"分别调用 startVideoMode 和 releaseSession，按钮 enabled 状态联动 surfaceReady 与 sessionMode 防止误操作。

会话三态状态卡以三列等宽布局展示会话模式（IDLE/VIDEO/PHOTO）、AUTO_FRAMING 声明态（已声明/未声明）、构图接管态（系统接管/手动），每列用 monospace 字体强调技术感。

效果枚举卡遍历 EFFECT_INFOS 展示三种效果类型，AUTO_FRAMING（type=2）行额外显示"本机已声明"或"待查询"的设备适配状态。底部 Toggle 开关联动 toggleFraming 实现影随人动的动态开关。

能力链三步状态卡通过 chainRow Builder 方法渲染三行能力链步骤，每行以 ●（绿色通过）或 ○（暗紫待验证）图标 + 等宽字体方法签名 + 右侧"通过/待验证"文案，直观展示 isControlCenterSupported → getSupportedEffectTypes().includes(AUTO_FRAMING) → enableControlCenter(true) 三步的执行状态。

11.3 Tab2 对焦：手动对焦三接口实战

对焦 Tab 包含五个区块：能力查询卡、三档景别预设、对焦距离滑杆、读回验证卡、对焦记录时间线。

能力查询卡展示 isFocusDistanceSupported 的返回值，按钮"启动拍照会话"调用 switchToPhotoMode（已启动时按钮禁用并变为深紫色），"重新查询能力"调用 queryFocusSupport。

三档景别预设以三列等宽卡片展示近拍/中距/远距，当前选中的档位（Math.abs(focusDistance - preset.distance) < 0.02）以金色文字 + 深紫底高亮，点击调用 applyFocus 设焦并读回验证。

对焦距离滑杆使用 Slider 组件，范围 0~1 步进 0.01，onChange 实时更新 focusDistance 并调用 setFocusLive 连续设焦。滑杆下方显示 distanceLabel 景别文案和范围说明。

读回验证卡以三列等宽展示设定值、读回值、校验结果，设定值暖白、读回值信息蓝、校验结果按 readOkColor 映射颜色。两个按钮"设置并读回"和"仅读回校验"均需 sessionMode === 'photo' && focusSupported 才启用。

对焦记录时间线以 150 高度的 Scroll 容器展示 focusRecords 数组，每行包含时间（暗紫等宽）、设定值（暖白等宽）、箭头、读回值（信息蓝等宽）、校验结果（按 readOkColor 映射），unshift 置顶保证最新记录可见。

11.4 Tab3 字幕：AI 字幕四字段定制

字幕 Tab 包含五个区块：AICaptionComponent 实时预览、语言设置联动、字号颜色外观设置、字幕场景卡、演示音频写入。

实时预览区以 AICaptionComponent 组件为核心，传入 isShown、controller、options（由 buildCaptionOptions 动态构建）。就绪态文案"已就绪"绿色、"初始化中"暗紫。按钮文案随 captionShown 切换（“开启字幕”/“隐藏字幕”），右侧显示已写入音频块数。错误信息以红色文本条件渲染。

语言设置区源语言为中文/英文两个胶囊选项，选中态金底深字、未选中态深紫底紫灰字。中文源时显示金色锁定提示"targetLanguage 仅支持 zh"，英文源时展开目标语言三选项（中文/英文/中英双语）。

外观设置区字号四档胶囊（选中态紫底深字）与颜色五色卡（选中态金色边框 2px、未选中态暗紫边框 1px）横向排列，右侧显示当前色值的等宽字体十六进制值。

字幕场景卡以 List + ListItem 结构展示五种场景，每行包含话筒 emoji、场景名、场景说明、推荐语言方向（信息蓝），点击调用 applyScene 一键应用。底部按钮"写入演示音频"调用 feedAudioStream 写入 640 字节 PCM 块。

11.5 Tab4 复盘：统计三卡与练习记录

复盘 Tab 包含统计三卡和练习记录进度条清单两个区块。

统计三卡以三列等宽展示累计练习次数（金色）、累计时长分钟（紫色）、平均评分（绿色），数字使用 20px 等宽字体加粗，下方 9px 暗紫标签。数据由 totalMinutes 和 avgScore 工具函数实时计算。

练习记录清单以 List + ListItem 结构展示每条 PracticeItem。每条记录是一个 Column 卡片：首行展示日期（等宽暗紫）、主题（暖白）、时长（紫灰）、评分（按 scoreColor 映射颜色加粗）；中间是 Progress 线性进度条，value 为评分、total 为 100、颜色按 scoreColor 映射；尾行展示"AI 点评"标签和编辑/删除操作按钮，编辑调用 openEdit 打开编辑弹窗，删除设置 delIdx 并打开删除确认弹窗。顶部"新增记录"按钮调用 clearForm 后打开新增弹窗。

11.5 Tab5 我的：学员成就与月度图表

我的 Tab 包含学员渐变大卡、勋章清单行、月度柱状图三个区块。

学员渐变大卡以 135 度舞台紫渐变为背景，上行左侧是 56x56 圆形深紫底的麦克风 emoji 头像，右侧是学员名"星野 · 声量学院学员"和等级副标题。下行三列等宽展示表达力指数 86、累计分钟 124、已获勋章 8，列间以 1px 高度的暗紫分割线隔开。

勋章清单行以横向 Scroll 展示 6 枚勋章，已解锁的勋章 emoji 不透明度 1、文字暖白；未解锁的不透明度 0.35、文字暗紫。顶部显示"已解锁 3 / 6"的进度文案。

月度柱状图通过 chartCard Builder 渲染，6 根柱子以 ForEach 遍历 MONTH_IDX，柱高为 16 + PRACTICE_VAL[mi] * (breath ? 0.72 : 0.66)——breath 翻转使系数在 0.72 与 0.66 间切换，产生柱高呼吸微动。偶数月柱紫色、奇数月柱深紫色，顶部圆角 4，底部对齐 VerticalAlign.Bottom。柱子上方显示数值、下方显示月份。

十二、构建方法与布局骨架

根组件的 build 方法是整个页面的布局骨架，采用 Stack 容器实现层叠结构：

build() {
  Stack() {
    Column() {
      this.headerStage()
      Divider().strokeWidth(1).color(COLORS.line)
      Scroll() {
        Column() {
          if (this.currentTab === 0) { this.tabStage() }
          else if (this.currentTab === 1) { this.tabCamera() }
          else if (this.currentTab === 2) { this.tabFocus() }
          else if (this.currentTab === 3) { this.tabCaption() }
          else if (this.currentTab === 4) { this.tabReview() }
          else { this.tabMine() }
        }.width('100%').padding({ left: 12, right: 12, top: 10, bottom: 12 })
      }.layoutWeight(1).scrollBar(BarState.Off).align(Alignment.Top)
      this.tabBar()
    }.width('100%').height('100%')
    if (this.addModal) { this.panelAdd(() => { this.addModal = false; }) }
    if (this.editModal) { this.panelEdit(() => { this.editModal = false; }) }
    if (this.delModal) { this.panelDel(() => { this.delModal = false; }) }
  }.alignContent(Alignment.Center).backgroundColor(COLORS.bg).height('100%')
}

Stack 的底层是 Column 纵向三段式：头部横幅 headerStage、Divider 分割线、Scroll 内容区、tabBar 底部导航。内容区通过 if-else if-else 链根据 currentTab 索引在六个 Builder 方法间分支渲染，每个 Tab 拥有完全独立的布局结构，互不干扰。Scroll 设置 layoutWeight(1) 占据头部与底部之间的全部剩余空间，scrollBar(BarState.Off) 隐藏滚动条保持视觉整洁，align(Alignment.Top) 让内容从顶部开始排列。Stack 的顶层是三个弹窗的条件渲染，每个弹窗接收一个 onClose 闭包回调，遮罩点击即触发关闭。alignContent(Alignment.Center) 使弹窗内容卡片在 Stack 中垂直水平居中。这种"内容区 + 浮层弹窗"的 Stack 层叠模式是 ArkUI 实现模态交互的惯用范式，相比 bindSheet 等系统弹窗组件，自定义 Stack 弹窗拥有更高的样式自由度，可以完全融入应用的主题色彩体系。

十三、底部 Tab 栏与弹窗系统

13.1 底部 Tab 栏

@Builder tabBar() {
  Row() {
    ForEach(TAB_LIST, (tab: TabMeta, idx: number) => {
      Column({ space: 3 }) {
        Text(tab.icon).fontSize(18).opacity(this.currentTab === idx ? 1 : 0.6)
        Text(tab.label).fontSize(9)
          .fontColor(this.currentTab === idx ? COLORS.tabOn : COLORS.text3)
          .fontWeight(this.currentTab === idx ? FontWeight.Bold : FontWeight.Normal)
      }.layoutWeight(1).alignItems(HorizontalAlign.Center)
      .padding({ top: 6, bottom: 6 })
      .onClick(() => { this.currentTab = idx; })
    }, (tab: TabMeta, idx: number) => `tab-${tab.label}-${idx}`)
  }.width('100%').backgroundColor(COLORS.card).border({ width: { top: 1 }, color: COLORS.line })
}

底部 Tab 栏以 Row 等宽排列 6 个 Tab，选中态 emoji 不透明度 1、标签聚光金加粗；未选中态 emoji 不透明度 0.6、标签暗紫常规。border 仅设置 top: 1 的暗紫分割线，与卡片底色形成层次。点击设置 currentTab 索引触发内容区分支切换。

13.2 弹窗遮罩与模态系统

弹窗系统由 modalOverlay 通用遮罩层和三个业务弹窗（panelAdd/panelEdit/panelDel）组成。modalOverlay 是全屏半透黑 Column，点击触发 onClose 回调关闭弹窗。

新增弹窗包含四个 TextInput（日期/主题/时长/评分）和取消/保存按钮，保存调用 confirmAdd（含空值兜底：日期默认 08-29、主题默认"自由练习"、时长默认 15、评分默认 70）。

编辑弹窗结构与新增对称，但 openEdit 时预填当前记录数据，保存调用 confirmEdit 进行 @Observed 字段级更新（空值不覆盖原值）。

删除弹窗展示确认文案（含被删记录的主题名），"再想想"取消、"确认删除"调用 confirmDel 执行 splice 删除。

三个弹窗均以 Stack 层叠遮罩与内容卡片，内容卡片宽 86%、圆角 14、卡片底色，居中对齐。build 方法中通过三个 if 条件渲染控制显隐，遮罩点击即关闭，形成轻量模态交互。

十四、功能模块对比表

功能模块	宿主会话/组件	核心 API	状态变量	数据模型	视觉特征
影随人动	VideoSession	isControlCenterSupported / getSupportedEffectTypes / enableControlCenter	framingState / framingSupported / framingOn	EffectInfo 枚举	三步能力链状态卡 + Toggle 开关
手动对焦	PhotoSession	isFocusDistanceSupported / setFocusDistance / getFocusDistance	focusSupported / focusDistance / focusReadback / focusResult	FocusRecord 时间线	三档预设 + Slider + 读回三列卡
AI 字幕	AICaptionComponent	sourceLanguage / targetLanguage / fontSize / fontColor / writeAudio	srcLang / tgtLang / captionSize / captionColor / captionFed	CaptionScene 场景	预览区 + 语言胶囊 + 字号颜色卡
雷达图	Canvas	CanvasRenderingContext2D / arc / fill / stroke	breath / radar_ctx	RADAR_VALUES 五维	三层背景多边形 + 呼吸微动
课程展示	ForEach + Scroll	lessonBigCard / lessonRows	lessonList	LessonItem	横滑大卡 + 清单行
练习复盘	List + Progress	totalMinutes / avgScore / scoreColor	practiceList / formXxx	PracticeItem	统计三卡 + 进度条清单
弹窗系统	Stack + modalOverlay	confirmAdd / confirmEdit / confirmDel	addModal / editModal / delModal	—	遮罩点击关闭 + 表单暂存

深化解析：从代码结构到业务闭环

布局方式与数据流

演讲训练页面把课程选择、画面采集、手动对焦、字幕反馈和训练复盘连成闭环。课程定义练习目标，相机保证构图，对焦保证画面清晰，字幕与指标帮助用户发现表达问题。逐段分析要区分课程数据、一次练习状态与统计结果，并说明舞台紫和聚光金如何建立主次层级。

页面根结构通常由头部、内容区和底部 Tab 栏组成。头部负责展示当前业务状态，内容区根据索引选择不同的 @Builder，底部导航负责修改索引。这样的结构把“当前显示什么”收敛为一个明确状态：用户点击 Tab 后先更新索引，ArkUI 再重新计算相关分支。各个 Builder 虽然共享主题色和页面级数据，却可以采用完全不同的布局方式；高密度列表适合纵向 Scroll，概览数据适合横向统计卡或双列 Flex，实时预览类组件需要独占有界高度，历史事件则适合时间轴或固定行高 List。

数据模型层承担界面与业务之间的契约。使用 @Observed 的实体保存可编辑字段，页面级 @State 数组负责驱动 ForEach。新增时创建新实体并插入数组，编辑时修改目标实体，删除时移除对应项。为了让列表差分稳定，key 应来自不会改变的唯一标识，不宜使用标题等可编辑字段。统计数字、完成比例和分类数量属于派生信息，可以从数组即时计算，避免同时维护两份状态后出现卡片已经更新、图表仍显示旧值的情况。

弹窗表单使用独立缓存是必要的。打开新增弹窗时清空缓存，打开编辑弹窗时复制目标字段，用户确认后才写回正式模型。这样点击取消不会污染列表数据。若直接把 TextInput 双向绑定到列表实体，用户尚未保存时卡片就可能跟着变化，破坏“确认提交”的交互语义。删除弹窗还需要保存目标索引或唯一标识，并在确认时再次校验目标存在，避免列表变化后误删其他项。

核心代码与状态驱动机制

@State 的价值不是简单替代普通变量，而是建立状态与界面之间的依赖关系。当前 Tab、筛选条件、动画开关、弹窗显隐、下载进度或能力状态发生变化时，只有读取这些变量的组件需要刷新。代码段中连续的修饰器调用分别控制尺寸、间距、背景、字体和事件，它们共同构成声明式描述；阅读时应从容器方向、子项分布、状态绑定和交互回调四个层面理解，而不是逐个孤立翻译属性名称。

ForEach 负责把数组映射为重复 UI。回调中的 item 提供业务字段，index 适合显示顺序，但不适合作为长期身份。列表发生新增或删除时，稳定 key 可以让框架复用未变化节点，减少重建。若直接修改对象属性后界面没有按预期刷新，可在保持实体身份的前提下替换数组引用；但不应为了刷新把所有元素都重新构造，否则会增加无意义渲染并丢失局部状态。

条件渲染体现了页面状态机。空闲时展示引导，准备中展示进度，成功时展示结果，失败时展示原因和重试入口。相比一个布尔值，四态文案更能覆盖异步能力。系统接口调用前先检查权限、设备支持和会话状态，调用后再读取结果校验。异常处理除了记录错误码，还要把可理解的反馈写入响应式状态，让用户知道失败发生在哪一步。

动画效果与颜色使用策略

呼吸动画通常由定时器周期翻转 breath，再把该状态映射为透明度、柱高或圆点半径的小幅变化。它适合表达“正在运行”或让统计图保持生命感，但幅度应克制，不能改变核心数据含义。柱状图的基础高度仍由真实数值计算，动画只能在很小范围内偏移；进度环的角度仍由完成比例决定，不能为了视觉效果显示超过真实进度的结果。页面离开时必须清理定时器，避免后台继续刷新。

颜色常量应按语义使用。主色承担选中态和主要操作，辅助色突出数据或次级动作，绿色表达完成与可用，橙色表达进行中或需要注意，红色只用于失败、逾期和删除等高风险场景。弱文本与分割线降低视觉权重，遮罩色用于聚焦弹窗。颜色不能成为唯一的状态信息，还要配合文字、图标或进度值，保证色觉差异用户也能理解。

渐变更适合头部大卡、核心指标或柱状图，不宜在每个小元素上重复使用。深色主题要检查正文与卡片背景的对比度，浅色主题则要避免辅助文字过淡。选中和未选中 Tab 除颜色差异外，还可以通过字重、图标透明度或底部指示器区分。这样既保持主题统一，又能建立清晰的信息层级。

各 Tab 之间的交互联动

各 Tab 不应只共享一个导航索引，还应围绕业务对象建立必要联动。列表页新增或编辑数据后，头部计数、图表和个人统计要同步更新；网页或地图产生的结果应写入记录模型，供下载、日志或我的页面继续展示；通知、字幕、相机等系统能力的状态应在头部胶囊或对应 Tab 中保持一致。跨 Tab 跳转时先更新必要参数，再修改当前索引，可以避免目标页面读取到旧条件。

切换离开重型组件时需要处理资源边界。相机输入、地图监听、字幕控制器、Web 下载代理和定时器都不能只创建不释放。可以在统一的 switchTab 方法中判断来源与目标，离开能力页时解除监听或停止会话；页面销毁时再执行兜底释放。释放方法应允许重复调用，并对每个资源独立判空，确保一次异常不会阻止后续清理。

交互反馈要覆盖成功与失败。按钮点击后先进入处理中状态并防止重复提交；成功后更新模型、关闭弹窗并显示结果；失败后保留用户输入，展示错误原因和重试入口。权限拒绝、能力不支持、网络失败、文件不存在和输入非法都属于正常业务分支。通过状态卡或行内提示展示这些分支，比只在控制台打印更符合完整产品体验。

边界场景与验证思路

空列表时应显示占位说明和新增入口，不能只留下空白。长标题需要限制行数并使用省略号，数字字段需要限定上下界，文本提交前要去除首尾空格。筛选后无结果应保留清除条件的入口。删除最后一项后，当前选择索引要回退到有效范围。异步搜索连续触发时，应防止较早请求晚返回后覆盖新结果。

验证数据链路时，可以依次检查新增、编辑、删除和筛选：新增后列表条数、统计数字和图表是否同时变化；编辑取消后正式数据是否保持不变；删除后 ForEach key 是否稳定；切换 Tab 再返回时必要数据是否仍在。验证系统能力时分别模拟支持、拒绝和异常，确认界面都有明确状态。验证动画时检查页面离开后是否停止，低性能设备上是否仍保持流畅。

视觉验收需要检查不同屏幕宽度、系统字体放大、深浅背景对比和长文本换行。表格中的布局方式、模型、字段数、核心操作、动画、状态颜色、数据量和特殊组件应与正文一致。Mermaid 图则需要对应真实的数据流和能力链路，节点文字加引号以避免中文或特殊字符导致解析失败。

组件化设计的进一步理解

参数化 Builder 适合抽取重复的统计格、状态行、标签和按钮组。参数只传入渲染所需数据和事件，不让子构建器直接依赖过多页面变量，可以降低耦合。业务复杂后，可把模型与系统能力封装为独立控制器，页面只负责组合 UI 和响应状态。这样既保留声明式代码的直观性，也能让权限、错误码翻译和资源释放得到集中管理。

当前单页面集中展示完整源码，便于博文逐段讲解。若演进为正式项目，可以按领域拆分组件：导航和页面框架位于容器层，列表、图表和弹窗位于展示层，数据读写和 Kit 接入位于服务层。组件之间通过参数、回调、@Link 或 @ObjectLink 传递状态，不使用全局变量代替清晰的数据流。

性能优化首先来自减少不必要刷新。派生数据不要重复存储，动画状态不要进入列表 key，长列表使用稳定标识，Canvas 只在数据或尺寸变化时重绘。其次是控制资源生命周期，页面不可见时停止高成本任务。最后才是微调阴影、渐变和绘制细节。这样的优先级能保证页面在功能增加后仍然可维护。

通过以上补充，可以看到 ArkUI 的声明式模式并非只让布局语法更简洁，它更重要的价值是把数据变化、界面刷新和交互反馈连接为可追踪链路。理解每个代码段读取什么状态、写入什么状态、影响哪些组件，才能真正掌握文章中多个 Tab、图表、弹窗和系统能力协同工作的原理。

十五、总结与展望

本平台以"声量学院"为产品概念，将演讲口才训练的全流程——从课程选择、取景构图、精确对焦、跨语种字幕辅助到能力评估与练习复盘——整合在单一 ArkUI 页面中。技术层面，平台深度实践了 HarmonyOS 6.1.1 的四大前沿特性：Camera Kit 的 AUTO_FRAMING 影随人动三步能力链通过 VideoSession 的 ControlCenter 通道实现演讲者自动居中构图；手动对焦三接口通过 PhotoSession 的 ManualFocus 通道实现从铭牌特写到全场舞台的精确焦距控制；Speech Kit 的 AICaptionComponent 通过四个新增字段实现字幕语言方向、字号档位、字体颜色的全维度定制；Canvas 通过 CanvasRenderingContext2D 绘制表达力五维雷达图并联动呼吸动画。

架构层面，平台采用了"状态顶层声明 + Builder 分支渲染 + 纯函数工具"的三层分层模式：所有 @State 变量集中在组件顶层实现跨 Tab 共享，6 个 @Builder 方法按 Tab 职责拆分保持 build 方法精简，工具函数与数据模型类在组件外部定义保持纯函数可测试性。Camera Kit 的双模式会话管理（VideoSession 与 PhotoSession 互斥存活）通过 releaseSession 统一出口保证硬件资源不泄漏，aboutToDisappear 生命周期钩子兜底释放防止后台占用。@Observed 装饰的数据模型类实现了字段级响应式追踪，ForEach 的键值回调保证了列表项的高效复用。

色彩体系以舞台紫 #8B5CF6 为主色、聚光金 #F5C04E 为焦点色，构建了"深夜舞台暗场 + 聚光灯高亮"的视觉隐喻。紫金蓝绿红五色语义体系贯穿等级徽章、评分进度条、能力链状态、读回校验结果等所有信息密度场景，使学员在深色环境下凭颜色即可快速定位关键信息。呼吸动画通过 breath 布尔值的秒级翻转，联动头部麦克风透明度、雷达图数据微波动、柱状图柱高微动三处视觉元素，营造"AI 复盘进行中"的生命感。

展望未来，平台可在以下方向持续演进：其一，将 Mock 数据替换为持久化存储，通过分布式数据管理实现练习记录的跨设备同步与云端备份；其二，将 feedAudioStream 的正弦波演示音频替换为真实麦克风采集的 PCM 流，实现演讲内容的实时 AI 转写与语速分析；其三，将雷达图五维数据从静态常量升级为基于练习记录的动态计算，让能力评估随训练进度实时演化；其四，引入 Camera Kit 的人脸检测能力，在影随人动基础上叠加眼神追踪维度，使"眼神交流巡航术"课程获得真实数据支撑；其五，利用 ArkUI 的 AnimateTo 显式动画替代 setInterval 呼吸方案，实现更流畅的 60fps 过渡曲线。随着 HarmonyOS 特性的持续丰富，演讲口才训练平台将从"展示型"走向"感知型"，最终成为学员口袋里的随身演讲教练。

附录：DevEco Studio 创建新项目与查看 SDK 版本

本章节演示如何使用 DevEco Studio 创建一个 HarmonyOS 新项目，并查看当前 IDE 已安装的 SDK 版本，适合作为其他技术博文的补充操作指南。

---

一、创建新项目

1.1 进入欢迎界面

启动 DevEco Studio 后，首先看到的是欢迎界面。左侧导航栏默认选中 “项目”，右侧提供三个主要入口：

• 新建项目：从头创建新项目
• 打开项目：打开本地已有项目
• 克隆仓库：从 Git 等版本控制拉取代码

点击 “新建项目” 按钮，进入项目创建向导。

1.2 选择项目模板

在弹出的"新建项目"对话框中，左侧分类标签提供了两种项目类型：

类型	说明
应用（Application）	开发标准的 HarmonyOS 应用，具备完整的 Ability 生命周期
元服务（Atomic Service）	开发轻量级的原子化服务，无需安装即可使用

选择 “应用” 标签后，右侧展示多种模板。对于大多数场景，推荐选择 “Empty Ability” —— 这是一个最基础的入门模板，仅包含 Hello World 功能，适合从零开始构建应用。

1.3 配置项目信息

点击 “下一步” 后，进入项目配置界面，需要填写以下核心参数：

配置项	示例值	说明
项目名称（Project name）	rollboat	应用的项目名称，建议使用英文命名
包名（Bundle name）	com.rollboat.myapplication	应用唯一标识，采用反向域名格式
保存路径（Save location）	D:\CodeFactory\rollboat	项目本地存储路径，避免使用中文和空格
兼容 SDK（Compatible SDK）	6.1.1(24)	目标 HarmonyOS API 版本，点击"查看参考"可了解各版本差异
模块名称（Module name）	entry	主模块名称，默认 entry 为应用入口模块
设备类型（Device types）	☑ Phone	勾选目标设备：Phone / Tablet / 2in1 / Car / Wearable / TV

右侧预览区会实时展示当前模板的默认效果 —— 一个居中显示的 “Hello World” 文本。

1.4 完成创建

确认配置无误后，点击右下角 “完成” 按钮，IDE 将自动执行以下操作：

1. 生成项目骨架（Stage 模型目录结构）
2. 执行 ohpm install 安装依赖
3. 运行 Hvigor 构建初始化（Build Init）

构建日志中显示 “退出代码为 0” 表示项目初始化成功。

1.5 项目结构概览

创建完成后，左侧项目面板展示的是标准的 Stage 模型 目录结构：

rollboat/
├── .hvigor/                   # Hvigor 构建工具缓存
├── .idea/                     # IDE 配置文件
├── AppScope/                  # 应用级全局配置
│   └── app.json5
├── entry/                     # 主模块（入口模块）
│   ├── src/main/ets/
│   │   ├── entryability/      # Ability 生命周期管理
│   │   │   └── EntryAbility.ets
│   │   └── pages/             # UI 页面
│   │       └── Index.ets      # 首页（默认 Hello World）
│   ├── src/main/resources/    # 资源文件
│   ├── module.json5           # 模块配置
│   └── build-profile.json5    # 构建配置
├── oh_modules/                # OHPM 依赖包
├── build-profile.json5        # 工程构建配置
├── hvigorfile.ts              # Hvigor 构建脚本
└── oh-package.json5           # 包管理配置

核心文件 Index.ets 的默认代码如下，采用 ArkTS 声明式 UI 语法：

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    RelativeContainer() {
      Text(this.message)
        .id('HelloWorld')
        .fontSize($r('app.float.page_text_font_size'))
        .fontWeight(FontWeight.Bold)
        .alignRules({
          center: { anchor: '__container__', align: VerticalAlign.Center },
          middle: { anchor: '__container__', align: HorizontalAlign.Center }
        })
        .onClick(() => {
          this.message = 'Welcome';
        })
    }
    .height('100%')
    .width('100%')
  }
}

关键语法	作用
@Entry	标记为页面入口，可用于路由跳转
@Component	声明为自定义组件
@State	状态变量，数据变更时自动触发 UI 刷新
RelativeContainer	相对布局容器，替代传统线性布局
.onClick()	点击事件，此处点击后文本变为 “Welcome”

打开右侧 Previewer（预览器），选择 Phone 设备，即可实时预览 Hello World 效果，无需连接真机或启动模拟器。

---

二、查看 SDK 版本

2.1 查看 HarmonyOS SDK

DevEco Studio 安装时已内置 HarmonyOS SDK，无需单独下载。通过以下路径查看：

文件 → 设置 → HarmonyOS SDK（或快捷键 Ctrl + Alt + S 搜索 “HarmonyOS SDK”）

在设置面板中，可以看到当前已安装的 SDK 版本信息：

名称	阶段	状态
HarmonyOS 6.1.1	Release	✅ 已安装

界面顶部提示：“HarmonyOS SDK 已经包含在 IDE，无需单独安装”，省去了手动配置 SDK 的繁琐步骤。

2.2 查看 ArkUI-X SDK（跨平台扩展）

如果项目需要将 ArkUI 框架扩展到多个 OS 平台（Android / iOS / OpenHarmony），还需要配置 ArkUI-X SDK。路径如下：

文件 → 设置 → 语言和框架 → ArkUI-X

在这里可以查看已安装和可选的 ArkUI-X SDK 版本：

版本	SDK 版本号	阶段	状态
API Version 24	6.1.1.100	Release	✅ 已安装
API Version 23	6.1.0.28	Beta1	未安装
API Version 22	6.0.2.112	Release	未安装

安装路径示例：D:\DevTools\ArkUI-X\sdk

说明：ArkUI-X 允许开发者使用一套 ArkTS 主代码，同时构建多平台应用。如果仅开发 HarmonyOS 原生应用，无需额外安装 ArkUI-X SDK。

---

三、小结

步骤	操作	关键点
创建项目	欢迎页 → 新建项目 → 选择 Empty Ability 模板 → 配置项目信息 → 完成	使用 Stage 模型 + ArkTS 语言
查看 SDK	设置 → HarmonyOS SDK	SDK 已内置，无需手动安装
跨平台扩展	设置 → ArkUI-X	根据需要安装对应 API 版本

至此，DevEco Studio 的项目创建与 SDK 环境确认全部完成，可以开始 HarmonyOS 应用的功能开发。

---