一、技术前言

在移动摄影创作领域，一台手机早已不只是拍摄工具，更是从取景构图到素材采集、从暗房调色到元数据管理的完整创作中枢。从街头纪实的人像跟拍，到微距静物的精准对焦，从图库素材的一键下载溯源，到 WebP 动画帧参数的读写校验——每一个创作环节都需要精确的能力调度、清晰的状态反馈和可靠的文件链路。传统摄影类应用往往面临三大痛点：取景时人物出画导致构图崩塌、素材下载来源不可追溯导致版权风险、图片元数据只读不可写导致后期参数丢失。

HarmonyOS ArkUI 框架以其声明式 UI 范式为这些问题提供了系统级的解决方案。ArkUI 基于 TypeScript 扩展的 ArkTS 语言，通过 @Component 装饰器封装可复用组件，通过 @State、@Observed 等状态管理装饰器实现数据驱动渲染，通过 @Builder 方法将复杂的 UI 结构拆分为可组合的构建块。XComponent 组件提供了 Surface 级别的图形渲染能力，可直接对接 Camera Kit 的预览输出流；Web 组件内置了完整的浏览器引擎，支持通过 WebDownloadDelegate 代理拦截网页内的下载行为。这种架构天然适合摄影场景中"预览-采集-处理-校验"紧耦合的创作流程。

本平台深度融合了 HarmonyOS 6.1.1 的三大前沿特性。Camera Kit 提供了 VideoSession 的 AUTO_FRAMING（影随人动）能力链——通过 isControlCenterSupported 判断控制中心可用性、getSupportedEffectTypes 枚举本机声明的效果类型、enableControlCenter(true) 请求系统接管构图，三步实现运动跟拍时人物主体始终居中；同时 PhotoSession 的手动对焦三接口 isFocusDistanceSupported、setFocusDistance、getFocusDistance 实现从微距静物到街景纵深的精确焦距控制，并通过写后读回比对验证生效。ImageKit 实现了 WebP 元数据的类型化读写链路——通过 readImageMetadataByType 以 WEBP_METADATA 类型读取画布尺寸、帧延迟、循环次数五字段，再以字面量构造 WebPMetadata 挂载到 ImageMetadata 调用 writeImageMetadata 写回，最后重建 ImageSource 回读校验，确保写入值与读回值一致。ArkWeb 实现了下载双 URL 溯源——通过 WebDownloadDelegate 的四个回调（onBeforeDownload / onDownloadUpdated / onDownloadFailed / onDownloadFinish）全程跟踪下载生命周期，在完成回调中调用 6.1.1 新增的 getOriginalUrl() 和 getReferrerUrl() 分别获取文件直链来源与触发下载的引用页面，为素材版权追溯提供双链路证据。

二、整体架构流程图

整体架构以 Page1257 为根组件，采用 Stack 容器实现页面层叠：底层是 Column 纵向布局的头部 Banner + 内容区 + 底部 Tab 栏，顶层是全屏弹窗遮罩。内容区通过 currentTab 状态索引在 7 个 @Builder 方法间切换，每个 Tab 拥有完全独立的布局结构。其中相机 Tab 和网页 Tab 因需要 XComponent 预览流和 Web 组件独占有界高度，不进入主滚动容器，而是直接以 layoutWeight(1) 占满剩余空间；其余五个 Tab 统一包裹在 Scroll 容器内，支持弹性回弹滚动。三大特性（Camera Kit 影随人动、手动对焦、ImageKit 元数据读写、ArkWeb 双 URL 溯源）分别挂载在相机、对焦、工坊+元数据、网页四个 Tab 上，但它们的状态变量统一声明在组件顶层，实现跨 Tab 数据共享与联动。

三、色彩体系设计

3.1 ColorPalette 接口定义

平台采用深色暗房主题，模拟传统暗房红光熄灭后的低光环境，通过 ColorPalette 接口集中声明全部颜色字段：

interface ColorPalette {
  bg: string;      // 页面背景（暗房黑）
  card: string;    // 卡片底色（深灰绿）
  title: string;   // 主标题（冷白）
  sub: string;     // 副标题（灰绿）
  text3: string;   // 三级弱文本（暗灰绿）
  cyan: string;    // 银盐青（主色）
  cyanD: string;   // 银盐青深色
  amber: string;   // 暗房琥珀（辅助暖色）
  blue: string;    // 信息蓝（原始URL）
  red: string;     // 警示红（失败/删除）
  line: string;    // 分割线
  tabOn: string;   // Tab选中色
  mask: string;    // 弹窗遮罩
}

3.2 COLORS 常量逐色分析

const COLORS: ColorPalette = {
  bg: '#101314',      // 极深暗房黑，模拟全黑显影环境
  card: '#1A1F21',    // 卡片底色，比背景略亮一档
  dark: '#232A2D',    // 次级容器底色（统计格/滑杆轨道）
  title: '#EAF2F2',   // 冷白标题，高对比度保证暗光可读
  sub: '#A8BCBC',     // 灰绿副标题，层次柔和过渡
  text3: '#6E8484',   // 暗灰绿弱文本，辅助信息不抢视觉
  cyan: '#3FBFB0',    // 银盐青主色，摄影数据的视觉锚点
  cyanD: '#2A9688',   // 深青渐变起点，头部Banner过渡色
  amber: '#E8A54B',   // 暗房琥珀暖色，对焦参数与循环次数
  blue: '#4E9BE3',    // 信息蓝，原始URL与本月出片
  red: '#E05E5E',     // 警示红，失败状态与删除操作
  line: '#28302F',    // 分割线，低对比度不干扰内容
  tabOn: '#3FBFB0',   // Tab选中色与主色一致
  mask: 'rgba(0,0,0,0.6)' // 半透黑遮罩
};

色彩设计遵循"暗房工艺"语义原则：银盐青、暗房琥珀、信息蓝、警示红四色分别对应"创作数据/参数调节/溯源信息/危险操作"四种语义状态。银盐青的灵感来自传统黑白胶片显影液中银离子的青绿色泽，暗房琥珀则呼应暗房安全灯的琥珀色光，两者构成冷暖对比的视觉张力。头部 Banner 的 linearGradient 从 cyanD 经 cyan 再回到 cyanD，模拟银盐显影液的色调流动，底部 7 Tab 栏选中态使用 cyan 高亮，未选中态使用 text3 暗灰绿弱化。作品卡片封面条按索引在青/琥珀/蓝三色间轮换渐变，使双列瀑布流在视觉上产生节奏感而非单调重复。

值得注意的是，ColorPalette 接口中刻意未声明 dark 字段，但 COLORS 常量却额外定义了 dark: '#232A2D'。这种"接口窄、实现宽"的设计是一种务实的工程折衷：接口仅约束与 UI 语义强相关的颜色字段，而 dark 作为次级容器底色（统计格背景、滑杆轨道、按钮未选中态底色）属于实现细节，不需要在接口层面强制约束。在实际渲染中，dark 被大量用于需要比 card 更深一档的场景，例如对焦记录行的行底色、效果枚举表的标签底色、快捷站点的未选中态底色，形成了"bg → card → dark"三级递进的深色层次。弹窗遮罩色 mask 使用 rgba(0,0,0,0.6) 而非十六进制，是因为半透明遮罩需要 alpha 通道控制，而 ArkUI 的 backgroundColor 属性同时支持 hex 和 rgba 两种格式，rgba 在遮罩场景下更为直观。

四、Tab 元数据与常量体系

4.1 底部导航 Tab 定义

const TAB_LIST: TabMeta[] = [
  { icon: '🖼️', label: '作品' },
  { icon: '📷', label: '相机' },
  { icon: '🎯', label: '对焦' },
  { icon: '🌐', label: '网页' },
  { icon: '🧪', label: '工坊' },
  { icon: '🧬', label: '元数据' },
  { icon: '👤', label: '我的' }
];

底部导航采用单排 7 项布局，每个 Tab 以 emoji 图标加中文标签构成。这 7 个 Tab 覆盖了摄影创作的完整工作流：作品管理、取景拍摄、焦距控制、素材采集、样图生成、元数据工坊、个人主页。Tab 切换由 switchTab 方法统一管理，当离开相机 Tab 时自动释放相机会话，防止 cameraInput 被后台占用导致下次进入时创建失败。

4.2 常量数据群

平台将所有静态演示数据以接口加常量数组的模式集中声明，形成了层次清晰的常量体系：

相机效果枚举 EFFECT_INFOS 展示 ControlCenterEffectType 的三种效果类型：BEAUTY 美颜（type=0）、PORTRAIT 人像（type=1）、AUTO_FRAMING 影随人动（type=2，6.1.1 新增）。这三者在相机 Tab 的枚举表中以卡片形式排列，当本机已声明 AUTO_FRAMING 时自动追加"已声明"标签。

对焦预设档位 FOCUS_PRESETS 定义三档手动对焦预设：微距（distance=0.1，静物纹理与水珠）、近距（distance=0.5，人像特写与眼神光）、远距（distance=0.9，街景纵深与剪影）。点击预设卡可直接将滑杆值设为对应距离。

快捷站点 QUICK_SITES 收录六个摄影社区与图库站点：图虫、500px、Pexels、Unsplash、Flickr、蜂鸟网，点击即加载到 Web 组件。当前加载的站点以银盐青高亮区分。

暗房纹理 TEXTURES 定义五种像素算法映射：颗粒（对角斜纹）、渐晕（同心环）、划痕（竖带）、光斑（棋盘）、锐化（横带），每种纹理对应不同的像素着色公式，在工坊 Tab 中生成不同风格的 WebP 样图。

出片统计 MONTH_NAME 和 MONTH_SHOTS 提供近 6 个月的出片量数据（86/102/128/96/145/168 张），MONTH_MAX 设为 180 作为柱状图满高基准。

器材清单 GEAR_ROWS 列出六件器材：Sony A7M4 机身、FE 85mm f/1.4 GM 人像定焦、FE 16-35mm f/2.8 GM 广角变焦、大疆 RS4 Mini 稳定器、神牛 V860III 闪光灯、PGYTECH 35L 摄影包，每件器材以左侧色条区分类型（机身青/镜头琥珀/配件蓝）。

五、工具函数群

平台在常量体系之后定义了七个辅助函数，它们是纯函数无副作用，负责将状态值映射为 UI 可直接渲染的颜色或文案：

hexToRgba(hex: string): number 是最底层的颜色转换工具。ArkUI 的 image.createPixelMap 要求 RGBA_8888 格式的缓冲区按 R、G、B、A 四字节序排列，而设计稿中的颜色以 #RRGGBB 字符串表示。该函数将 hex 字符串拆解为 R、G、B 三个分量，再拼装为 0xFF000000 | (b << 16) | (g << 8) | r 的整数形式——注意字节序是 BGRA 而非 RGBA，因为小端序系统中 Uint32Array 的字节排列恰好是反序的。Alpha 通道固定为 0xFF（255，完全不透明）。

fmtField(v: number, unit: string): string 是元数据字段格式化函数。WebP 元数据的五个字段在 undefined 时统一用 -1 占位，该函数将 -1 渲染为"未提供"，将有效值渲染为 ${v}${unit}。这保证了"未提供"（undefined）与"0"（如 loopCount=0 表示不限循环）的严格区分——后者是合法的元数据值，不应被误判为缺失。

framingStateColor(s: string): string 将影随人动的状态文案映射为颜色：已启用映射银盐青、能力缺失（不支持/未声明）映射暗房琥珀、失败类（含"失败"“被拒”“未就绪”）映射警示红、其余映射暗灰绿。这使能力链的每一步结果都能以颜色直观传达。

distanceLabel(v: number): string 将 0.0~1.0 的对焦距离值映射为景别文案：小于 0.3 为微距静物、0.3~0.7 为近距人像、0.7 以上为远距街景，帮助摄影师理解数值对应的实际拍摄场景。

dlStateColor(s: string): string 将下载状态映射为颜色：完成映射银盐青、失败映射警示红、空闲映射暗灰绿、进行中映射信息蓝。

sessionLabel(mode: string): string 将会话模式映射为中文说明：video 映射"VideoSession · 影随人动宿主"、photo 映射"PhotoSession · 手动对焦宿主"、idle 映射"idle · 未启动会话"，明确两种会话各自承载的特性。

focusOkColor(ok: string): string 将对焦校验结论映射为颜色：已生效映射银盐青、偏差映射暗房琥珀、失败映射警示红。

六、数据模型层

平台采用 @Observed 装饰器为五个核心实体类赋予可观察性，使数据变更能自动触发绑定视图的刷新：

@Observed export class WorkItem {
  title: string;     // 作品主题名
  camera: string;    // 拍摄器材
  param: string;     // 曝光参数（焦段/光圈/快门/感光度）
  likes: number;     // 收藏数
}

WorkItem 是作品管理的主实体，包含主题名、器材、曝光参数和收藏数四个字段。WORK_LIST 常量预置了 8 条作品数据（雾锁外滩、弄堂晨光、夜轨流光等），每条都配有真实的器材型号与曝光参数（如"85mm f/1.4 1/500s ISO200"），渲染时以等宽字体显示参数行，营造摄影参数表的视觉质感。新增作品通过 unshift 置顶列表，删除通过 splice 移除，编辑仅更新收藏数字段。

@Observed export class FocusRecord {
  time: string;      // 操作时刻（HH:mm:ss）
  distance: number;  // 设置的对焦距离 [0.0,1.0]
  readback: number;  // 读回的对焦距离（失败时为-1）
  ok: string;        // 已生效/读回偏差/失败(错误码)
}

FocusRecord 是手动对焦的记录实体，捕获每次 setFocusDistance 设置值与 getFocusDistance 读回值的配对，并计算校验结论。构造函数自动生成 HH:mm:ss 格式的时间戳。aboutToAppear 时预置了三条种子记录（0.9 已生效、0.5 已生效、0.12 读回偏差），让对焦时间线在首次进入时不为空。记录通过 unshift 置顶，超过 20 条时 pop 尾部，防列表无限增长。

@Observed export class DownloadRecord {
  fileName: string;     // 建议文件名
  fileSize: string;     // 文件大小
  finishTime: string;   // 完成时间
  originalUrl: string;  // getOriginalUrl()结果：下载项原始URL
  referrerUrl: string;  // getReferrerUrl()结果：引用页URL
}

DownloadRecord 是下载溯源的核心实体，其 originalUrl 和 referrerUrl 两个字段直接对应 6.1.1 新增的 getOriginalUrl() 和 getReferrerUrl() 两个接口返回值。DOWNLOAD_LIST 预置了 5 条种子记录，每条都包含真实的 CDN 直链与社区页面引用 URL，演示双 URL 溯源的数据结构。

@Observed export class WebpMetaSnapshot {
  canvasWidth: number;         // 画布宽（px），-1=未提供
  canvasHeight: number;        // 画布高（px），-1=未提供
  delayTime: number;           // 钳制后帧延迟（ms），-1=未提供
  unclampedDelayTime: number;  // 未钳制帧延迟（ms），-1=未提供
  loopCount: number;           // 循环次数，-1=未提供（0=不限）
}

WebpMetaSnapshot 是 WebP 元数据五字段的快照实体，同时服务于"读取结果"和"回读校验"两处展示。五个字段分别对应 WebPMetadata 接口的 canvasWidth、canvasHeight、delayTime、unclampedDelayTime、loopCount，undefined 统一以 -1 占位，渲染时通过 fmtField 转为"未提供"。

@Observed export class MetaOpLog {
  op: string;      // 操作类型
  detail: string;  // 结果描述（含错误码）
  time: string;    // 操作时刻
}

MetaOpLog 是元数据操作日志实体，记录生成、读取、写入、回读四类操作的结果描述。每条日志通过 unshift 置顶，在元数据 Tab 底部以固定高度滚动列表展示，形成可追溯的操作时间线。

七、组件主体与状态管理

7.1 状态变量全景

Page1257 组件声明了逾 30 个 @State 状态变量，按功能域分为五大群组：

Tab 与弹窗状态群：currentTab（当前 Tab 索引）、addModal/editModal/delModal（三弹窗开关）、editIdx/delIdx（操作目标索引）、breath（呼吸动画布尔值）。其中 breath 每秒翻转一次，驱动呼吸圆点、柱状图微动等周期性视觉反馈。

作品数据与表单群：workList（作品列表）、formTitle/formCamera/formParam/formLikes（新增表单四字段）、editLikes（编辑收藏数暂存）。

Camera 成员群：previewController（XComponent 控制器）、cameraInput/previewOutput/videoSession/photoSession（相机管线四对象）、surfaceReady（Surface 就绪标志）、sessionMode（idle/video/photo 三态）、framingState/framingSupported（影随人动状态与能力标志）、focusSupported/focusDistance/focusRecords（对焦能力/当前距离/记录列表）、permState（权限状态）。

WebP 成员群：texIdx（纹理索引）、webpQuality（编码质量）、pixelMap（像素图预览）、webpPath（沙箱文件路径）、genState（生成状态）、metaSnapshot/verifySnapshot（读取与回读快照）、writeDelay/writeLoop（写入参数）、opLogs（操作日志）。

ArkWeb 成员群：webController/downloadDelegate（Web 控制器与下载代理）、urlInput/webUrl（地址栏输入值与实际加载值，双状态分离）、dlName/dlPercent/dlState（下载文件名/进度/状态）、downloadRecords（下载记录列表）。

这种将所有状态变量集中在组件顶层声明的设计，是 ArkUI 声明式范式的典型实践。与命令式 UI 框架不同，ArkUI 的 @State 装饰器会自动追踪变量的变更并触发依赖该变量的 UI 子树重渲染。当摄影师在对焦 Tab 调整滑杆时，focusDistance 的变更会同时刷新滑杆数值显示、景别文案、三档预设的选中态——这三个 UI 节点分属不同的 @Builder 方法，但只要它们引用了同一个 @State 变量，ArkUI 的依赖追踪机制就能精确地只更新这三处而非整棵组件树。@Observed 装饰器则将这种能力扩展到自定义类实例的属性级别，使 WorkItem.likes 的变更能直接反映到作品卡片上，无需手动调用刷新方法。

7.2 生命周期管理

aboutToAppear() {
  this.setupDownloadDelegate();
  this.focusRecords.unshift(new FocusRecord(0.9, 0.9, '已生效'));
  this.focusRecords.unshift(new FocusRecord(0.5, 0.5, '已生效'));
  this.focusRecords.unshift(new FocusRecord(0.1, 0.12, '读回偏差'));
  this.opLogs.unshift(new MetaOpLog('初始化', 'WebP 元数据工坊就绪，请先在「工坊」生成样图'));
  this.timer = setInterval(() => {
    this.breath = !this.breath;
  }, 1000);
}

aboutToAppear 承担四项初始化职责：注册下载代理（绑定四回调到 webController）、播种对焦记录（三条种子数据）、写入初始化日志、启动呼吸动画定时器（每秒翻转 breath 布尔值）。aboutToDisappear 则负责清理定时器与释放相机资源，防止后台占用摄像头。

7.3 Tab 切换与会话互斥

switchTab(idx: number) {
  if (this.currentTab === 1 && idx !== 1) {
    this.releaseSession();
  }
  this.currentTab = idx;
}

switchTab 的核心逻辑是会话互斥：当从相机 Tab（索引 1）切换到其他 Tab 时，必须先调用 releaseSession 释放相机管线。这是因为 Camera Kit 的 cameraInput 同一时间只能绑定一个 session，若不释放就离开，下次进入时创建新 session 会因资源占用而失败。

八、Camera Kit 方法群：影随人动与手动对焦

8.1 权限申请

async requestCameraPermission(): Promise<boolean> {
  const atManager = abilityAccessCtrl.createAtManager();
  const result = await atManager.requestPermissionsFromUser(ctx, ['ohos.permission.CAMERA']);
  const granted = result.authResults.length > 0 && result.authResults[0] === 0;
  this.permState = granted ? '已授权' : '权限被拒';
  return granted;
}

相机权限属于 user_grant 级别，必须通过 requestPermissionsFromUser 发起动态申请。该方法返回 authResults 数组，索引 0 的值为 0 表示已授权。权限状态实时同步到 permState，在相机 Tab 的授权卡上以颜色区分（已授权银盐青/被拒暗房琥珀）。

8.2 影随人动能力链

startVideoMode 方法构建 VideoSession 管线：获取 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 = '控制中心不支持';
    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.framingState = '影随人动已启用';
}

queryFraming 是影随人动的三步能力链：第一步 isControlCenterSupported 同步判断本机是否支持控制中心（部分低端设备无此硬件能力）；第二步 getSupportedEffectTypes 枚举本机声明的效果类型列表，用 includes(AUTO_FRAMING) 检查影随人动是否在其中；第三步 enableControlCenter(true) 请求系统接管构图，此后预览画面会自动跟随人物主体平移缩放，保持人物居中。三步任一失败都会设置对应的状态文案，在相机 Tab 的能力链卡片上以颜色区分。

8.3 手动对焦三接口

switchToPhotoMode 方法构建 PhotoSession 管线，流程与 VideoSession 类似但场景模式为 NORMAL_PHOTO。会话启动后立即调用 queryFocusSupport 查询手动对焦能力：

queryFocusSupport() {
  this.focusSupported = this.photoSession.isFocusDistanceSupported();
}

isFocusDistanceSupported 是同步方法，仅 PhotoSession（ManualFocus 能力宿主）才有。查询结果决定对焦 Tab 的"设置焦距"与"读回校验"按钮是否可用（enabled 绑定）。

applyFocus() {
  this.photoSession.setFocusDistance(this.focusDistance);   // 设置
  const readBack = this.photoSession.getFocusDistance();    // 读回
  const ok = Math.abs(readBack - this.focusDistance) < 0.01 ? '已生效' : '读回偏差';
  this.focusRecords.unshift(new FocusRecord(this.focusDistance, readBack, ok));
}

applyFocus 是手动对焦的核心验证方法：先调用 setFocusDistance 写入距离值（0.0 最近 ~ 1.0 最远），再调用 getFocusDistance 立即读回，以差值小于 0.01 为阈值判断是否"已生效"。这一写一读的配对验证，使摄影师能确认焦距设置真正下发了硬件而非被静默拒绝。每次操作生成一条 FocusRecord 置顶记录列表，超过 20 条时尾部弹出。

8.4 会话释放五步链

async releaseSession() {
  const session = this.videoSession ?? this.photoSession;
  // 先置空引用防重入
  this.videoSession = undefined;
  this.photoSession = undefined;
  this.previewOutput = undefined;
  this.cameraInput = undefined;
  // 再按序释放：session.off → stop → release → preview.release → input.close
  if (session) { session.off('error'); await session.stop(); await session.release(); }
  if (preview) { await preview.release(); }
  if (input) { await input.close(); }
  this.sessionMode = 'idle';
}

releaseSession 采用"先置空引用、后按序释放"的策略防止重入。释放顺序为：先注销 session 的 error 监听（off('error')），再 stop 会话，再 release 会话，然后释放 PreviewOutput，最后关闭 CameraInput。这五步链路在模式切换、离开相机 Tab、aboutToDisappear 三种场景下统一调用，确保相机资源不泄漏。

九、ImageKit WebP 方法群：编码落盘与元数据读写

9.1 暗房纹理像素算法

texPixelAt(texIdx: number, row: number, col: number): number {
  const palette = [COLORS.cyan, COLORS.amber, COLORS.blue, COLORS.cyanD, COLORS.red, COLORS.sub];
  if (texIdx === 0) return hexToRgba(palette[(row + col) % palette.length]);      // 颗粒
  if (texIdx === 1) { /* 渐晕：同心环 dist(r,c)/7 */ }
  if (texIdx === 2) return hexToRgba(palette[Math.floor(col / 7) % palette.length]); // 划痕
  if (texIdx === 3) { /* 光斑：棋盘 (⌊r/8⌋+⌊c/8⌋)%N */ }
  return hexToRgba(palette[Math.floor(row / 6) % palette.length]);                   // 锐化
}

texPixelAt 是五种暗房纹理的像素级实现。它接收纹理索引和行列坐标，返回该像素的 0xFFBBGGRR 颜色值。五种算法分别模拟传统暗房工艺的视觉特征：颗粒纹理用对角斜纹 (row+col)%N 模拟胶片银盐颗粒的随机分布；渐晕纹理用同心环 dist(r,c)/7 模拟镜头边缘亮度衰减；划痕纹理用竖带 ⌊col/7⌋%N 模拟底片划痕；光斑纹理用棋盘 ⌊r/8⌋+⌊c/8⌋%N 模拟镜头光斑；锐化纹理用横带 ⌊row/6⌋%N 模拟锐化条纹。调色板由六种主题色组成，每种纹理从中循环取色。

9.2 WebP 编码落盘

genWebpFile 方法完成从像素画到沙箱文件的全链路：第一步以 texPixelAt 逐像素填充 RGBA_8888 缓冲区（96×96 共 9216 像素，每像素 4 字节，总计 36864 字节），通过 image.createPixelMap 创建 PixelMap；第二步用 image.createImagePacker 将 PixelMap 编码为 WebP 字节流，质量参数由滑杆控制（60~100）；第三步以 READ_WRITE | CREATE | TRUNC 模式打开沙箱文件 filesDir/photo_metadata.webp 并写入字节流。这里特别使用 READ_WRITE 模式打开，是因为后续元数据写回接口 writeImageMetadata 要求文件以可写方式打开。生成成功后清空旧快照（metaSnapshot 和 verifySnapshot 置 undefined），并在操作日志中记录纹理名称与质量参数。

9.3 类型化读取

async readMeta() {
  const file = fileIo.openSync(this.webpPath, fileIo.OpenMode.READ_WRITE);
  const source = image.createImageSource(file.fd);
  const types: image.MetadataType[] = [image.MetadataType.WEBP_METADATA];
  const meta = await source.readImageMetadataByType(types, 0);
  const webp = meta.webPMetadata;
  this.metaSnapshot = new WebpMetaSnapshot(
    webp?.canvasWidth ?? -1, webp?.canvasHeight ?? -1,
    webp?.delayTime ?? -1, webp?.unclampedDelayTime ?? -1,
    webp?.loopCount ?? -1);
}

readMeta 使用 readImageMetadataByType 以 WEBP_METADATA 类型读取元数据。第二个参数 index=0 表示帧索引，静态 WebP 恒传 0（多帧动画 WebP 才需指定帧号）。返回的 ImageMetadata 对象的 webPMetadata 属性包含五个可选字段，全部以 ?? -1 做空值兜底，确保 undefined 转为 -1 占位。读取结果存入 metaSnapshot，在元数据 Tab 的五字段卡中展示。

9.4 写回与回读校验

async writeMeta() {
  const webpMeta: image.WebPMetadata = {
    canvasWidth: CANVAS_SIZE,
    canvasHeight: CANVAS_SIZE,
    delayTime: this.writeDelay,
    unclampedDelayTime: this.writeDelay,
    loopCount: this.writeLoop
  };
  const meta: image.ImageMetadata = { webPMetadata: webpMeta };
  await source.writeImageMetadata(meta);
  await this.verifyRead();  // 写入后立即回读校验
}

writeMeta 以字面量构造 WebPMetadata 对象（画布宽高固定为 96，帧延迟与循环次数由控制台选择），挂载到 ImageMetadata 后调用 writeImageMetadata 写回文件。写入成功后立即调用 verifyRead 进行回读校验。

verifyRead 的关键在于重建 ImageSource：同一个 ImageSource 实例可能因解码缓存而返回旧值，因此回读时重新 createImageSource 再调用 readImageMetadataByType。校验逻辑将回读的 delayTime 和 loopCount 与写入值严格比对，一致则日志记录"已生效"，不一致则记录差异详情。回读快照存入 verifySnapshot，在元数据 Tab 中以高亮底色（COLORS.dark）与读取结果卡区分展示。

十、ArkWeb 方法群：下载代理与双 URL 溯源

10.1 下载代理四回调

setupDownloadDelegate() {
  this.downloadDelegate.onBeforeDownload((item) => {
    item.start(dir + '/' + item.getSuggestedFileName());  // 必须调用start提供沙箱路径
  });
  this.downloadDelegate.onDownloadUpdated((item) => {
    this.dlPercent = item.getPercentComplete();           // 刷新进度
  });
  this.downloadDelegate.onDownloadFailed((item) => {
    this.dlState = '下载失败 · ' + item.getGuid();        // 失败时记录GUID
  });
  this.downloadDelegate.onDownloadFinish((item) => {
    const originalUrl = item.getOriginalUrl();    // ★ 原始URL（文件直链来源）
    const referrerUrl = item.getReferrerUrl();    // ★ 引用页URL（触发下载的页面）
    this.downloadRecords.unshift(new DownloadRecord(...));
  });
  this.webController.setDownloadDelegate(this.downloadDelegate);
}

setupDownloadDelegate 注册了下载生命周期的四个回调。onBeforeDownload 在下载开始前触发，此时必须调用 item.start(沙箱路径) 提供文件保存路径，否则任务永远停留在 PENDING 状态无法开始。onDownloadUpdated 在下载进行中周期性触发，通过 getPercentComplete 获取进度百分比刷新进度条。onDownloadFailed 在下载失败时触发，记录任务的 GUID 便于排查。onDownloadFinish 在下载完成时触发，这里调用 6.1.1 新增的 getOriginalUrl() 和 getReferrerUrl() 获取双 URL，连同文件名、大小、时间构造 DownloadRecord 置顶记录列表。

四个回调注册完毕后，通过 webController.setDownloadDelegate 将代理绑定到控制器，此后网页内触发的下载才会进入上述回调链路。绑定操作以 try-catch 包裹，消除控制器未就绪时的抛错告警。

10.2 地址栏与主动下载

loadUrl() {
  let url = this.urlInput.trim();
  if (!url.startsWith('https://') && !url.startsWith('http://')) {
    url = 'https://' + url;  // 无协议前缀时自动补https://
  }
  this.urlInput = url;
  this.webUrl = url;
}

loadUrl 实现地址栏的协议校验：用户输入的网址若不以 https:// 或 http:// 开头，自动补 https:// 前缀。urlInput 和 webUrl 双状态分离的设计使输入过程中不会触发 Web 组件反复加载，只有点击"前往"按钮时才将 urlInput 同步到 webUrl 驱动加载。

triggerDownload 方法支持应用侧主动发起下载，无需用户在网页内点击下载链接。它通过 webController.startDownload(url) 直接发起，以 try-catch 包裹捕获 BusinessError，失败时将错误码写入下载状态文案。网页 Tab 底部提供了两个预设下载按钮（夜景 LUT 包、银盐青预设），点击即触发对应 URL 的下载。

十一、头部详解

@Builder
headerMain() {
  Column({ space: 12 }) {
    // 渐变 Banner：品牌 + 三特性胶囊 + 呼吸圆点
    Column({ space: 8 }) {
      Row() {
        Text('📸 镜头笔记').fontSize(18).fontColor(COLORS.bg).fontWeight(FontWeight.Bold)
        Blank()
        Row({ space: 5 }) {
          Circle({ width: 6, height: 6 }).fill(this.breath ? COLORS.bg : COLORS.cyanD)
          Text(this.breath ? '暗房显影中' : '定影完成').fontSize(9).fontColor(COLORS.bg)
        }
      }
      Text('影随人动跟拍 · WebP 元数据工坊 · 下载双 URL 溯源').fontSize(11)
      Row({ space: 8 }) {
        Text(`作品 ${this.workList.length} 张`)
        Text(`收藏 ${(this.totalLikes() / 10000).toFixed(2)}w`)
        Text(`本月出片 ${MONTH_SHOTS[5]} 张`)
      }
    }.linearGradient({ angle: 120, colors: [[COLORS.cyanD, 0], [COLORS.cyan, 0.6], [COLORS.cyanD, 1]] })
    // 搜索条 + 新增作品按钮
    Row({ space: 8 }) {
      Row({ space: 6 }) { Text('🔍'); Text('搜作品 / 粘贴素材链接') }
        .onClick(() => { this.switchTab(3); })
      Text('+ 新增作品').onClick(() => { this.addModal = true; })
    }
  }
}

头部由渐变 Banner 和搜索条两部分组成。Banner 采用 120 度角的 linearGradient，从 cyanD（深青）经 cyan（银盐青）再回到 cyanD，模拟银盐显影液的色调流动。Banner 内部分三层：顶层是品牌名"镜头笔记"与呼吸圆点状态胶囊——圆点颜色随 breath 布尔值在 COLORS.bg（暗房黑）和 COLORS.cyanD（深青）间切换，文案在"暗房显影中"和"定影完成"间交替，以 1 秒周期模拟暗房工艺的呼吸节奏；中层是三特性标语行；底层是三枚创作数据胶囊（作品数、收藏数以万为单位保留两位小数、本月出片量），均以 COLORS.card 深灰绿为底、COLORS.bg 暗房黑为字。

搜索条点击后跳转到网页 Tab（索引 3），暗示其用途是粘贴素材链接进行下载溯源。"新增作品"按钮以银盐青为底、暗房黑为字，点击后清空表单四字段并打开 addModal 弹窗。

十二、各 Tab 布局分析

12.1 作品 Tab：统计三卡 + 双列瀑布 + 柱状图

作品 Tab 以三小卡统计开篇——作品总数（银盐青）、收藏总数（暗房琥珀）、本月出片（信息蓝），三色对应三种数据维度。主体是 Flex({ wrap: FlexWrap.Wrap }) 双列瀑布流，每张作品卡宽度 48.5%，包含：顶部渐变封面条（52px 高，按索引在三色渐变间轮换替代缩略图）、主题名（加粗冷白）、器材（灰绿副标题）、曝光参数（等宽字体暗灰绿）、收藏数与编辑/删除入口。封面条的渐变方向为 135 度对角，从透明深色过渡到主题色，营造暗房底片显影的视觉隐喻。

编辑按钮点击后记录当前索引到 editIdx、暂存收藏数到 editLikes，打开编辑弹窗；删除按钮点击后记录索引到 delIdx，打开删除确认弹窗。底部是月度出片量柱状图卡片。

12.2 相机 Tab：授权卡 + 模式切换 + 预览 + 能力链

相机 Tab 是独占高度的 Tab（不进 Scroll 容器），从上到下依次为：授权状态卡（CAMERA 权限申请按钮 + Surface 就绪状态）、模式切换行（影随人动与手动对焦互斥切换，选中态填充色、未选中态描边色）、XComponent 预览本体（layoutWeight(1) 占满中间区域）、固定高度 268px 的 Scroll 区域（影随人动能力链状态卡 + 效果类型枚举表）。

XComponent 以 SURFACE 类型创建，onLoad 回调中将 surfaceReady 置 true，此后相机管线才能获取 SurfaceId 创建 PreviewOutput。能力链卡片展示三步查询的结果文案与颜色，并以等宽字体显示接口调用链路 isControlCenterSupported → getSupportedEffectTypes → enableControlCenter(true)。效果类型枚举表列出 BEAUTY/PORTRAIT/AUTO_FRAMING 三种效果，当 AUTO_FRAMING 已声明时追加"已声明"标签。

12.3 对焦 Tab：能力查询 + 预设 + 滑杆 + 时间线

对焦 Tab 以能力查询卡开篇，展示 isFocusDistanceSupported 的结果与当前会话模式。若未启动拍照会话，卡片提供"去相机 Tab 切换"按钮（暗房琥珀底色）跳转到相机 Tab。主体是三档对焦预设卡（微距/近距/远距，选中态银盐青填充），点击即设置 focusDistance。预设卡下方是焦距滑杆（min=0, max=1, step=0.01），滑杆下方实时显示 distanceLabel 映射的景别文案。"设置焦距"与"读回校验"两个按钮均绑定 applyFocus，但仅在 sessionMode === 'photo' && focusSupported 时启用。底部是对焦记录时间线，以 150px 固定高度 Scroll 展示，每条记录显示时间、设置值、箭头、读回值、校验结论胶囊。

12.4 网页 Tab：地址栏 + 快捷站点 + Web + 下载卡

网页 Tab 同样独占高度，因 Web 组件需 layoutWeight(1) 撑满中间区域。顶部是地址栏（TextInput + 前往按钮），下方是六个快捷站点的横向滚动条（当前站点银盐青高亮，点击即同步 urlInput 与 webUrl）。中间是 Web 组件本体，当网页内用户点击素材下载链接时，下载请求自动进入 WebDownloadDelegate 的四回调链路。底部是下载控制卡与最近下载横滑卡。

下载控制卡展示当前下载状态文案（颜色通过 dlStateColor 函数映射——完成银盐青、失败警示红、进行中信息蓝、空闲暗灰绿），并提供两个主动下载按钮（夜景 LUT 包、银盐青预设），点击调用 triggerDownload 以 webController.startDownload(url) 发起。recentDownloads 方法从 downloadRecords 中取前 4 条，每条卡片宽 150px，以文件图标、文件名（省略号截断）、大小与时间两行布局呈现，横向滚动浏览。

12.5 工坊 Tab：纹理五选一 + 参数 + 生成 + 预览

工坊 Tab 是 WebP 样图的生成工坊，为元数据读写准备真实文件。顶部是暗房纹理五选一卡片（Flex 换行布局，每卡 31.5% 宽，选中态银盐青填充），展示纹理名称与算法公式。五种纹理各有不同的像素生成策略：颗粒纹理以 (row+col)%N 对角斜纹模拟胶片银盐颗粒分布；渐晕纹理以像素到画布中心的欧几里得距离分环，模拟暗房渐晕效应；划痕纹理以 ⌊col/7⌋%N 竖带模拟底片划痕；光斑纹理以棋盘格分布模拟镜头眩光；锐化纹理以 ⌊row/6⌋%N 横带模拟锐化条纹。下方是编码参数卡（画布尺寸固定 96×96，质量滑杆 60~100 步进 5，默认 90）。生成按钮点击后调用 genWebpFile，状态文案实时更新（生成中/已生成/失败）。预览区以 150×150 的 Image 组件渲染 pixelMap（未生成时显示占位图标与"尚未生成"文案），右侧展示当前纹理的工艺说明与算法描述。底部是沙箱文件状态卡，仅在 webpPath 非空时显示，展示文件路径与"READ_WRITE 模式落盘"的说明——这一模式选择是精心设计的，因为元数据写回接口 writeImageMetadata 要求文件以可写方式打开，生成时已按此模式落盘，避免了后续写入时重新打开文件的额外开销。

12.6 元数据 Tab：五字段卡 + 写入控制台 + 回读 + 日志

元数据 Tab 是 WebP 元数据的读写校验中心。顶部标题行右侧是"读取"按钮，点击调用 readMeta。读取结果以五字段卡展示（canvasWidth/canvasHeight/delayTime/unclampedDelayTime/loopCount），未读取时显示占位提示。五字段卡由 metaCard Builder 方法参数化构建，接收标题文本、快照对象、高亮标志三个参数——读取结果使用 COLORS.card 常规底色，回读校验使用 COLORS.dark 深色底以视觉区分。loopCount 字段在值为 0 时渲染"不限（0 次）“，值为 -1 时渲染"未提供”，严格区分"未提供"与"不限次数"两种语义。中部是写入控制台：帧延迟三档预设（120/200/500ms，银盐青选中）+ 循环次数四档预设（0 不限/1/3/5 次，暗房琥珀选中）+ "写入并回读校验"按钮。写入成功后底部出现高亮底色的回读校验卡，与读取结果卡形成视觉对比。最底部是操作日志流（140px 固定高度 Scroll），展示生成/读取/写入/回读四类操作的记录，每条日志以操作类型胶囊、结果详情（含错误码）、时间三段式布局呈现。

12.7 我的 Tab：渐变大卡 + 器材清单 + 特性栈

我的 Tab 以摄影师渐变大卡开篇（135 度 linearGradient 从深青到银盐青），内含摄影师名"银盐客 · Chen"、认证标语、三枚数据胶囊（出片数/收藏数/影龄）。中部是器材清单列表，每行以左侧 3px 色条区分类型（机身青/镜头琥珀/配件蓝），展示型号与用途说明。底部是特性栈速览，以三行展示本应用的技术栈：Camera Kit（影随人动 + 手动对焦）、Image Kit（WebP 元数据读写 + 回读校验）、ArkWeb（onDownloadFinish 双 URL 溯源）。

十三、图表卡片：月度出片柱状图

@Builder
chartCard() {
  Column({ space: 10 }) {
    Row() {
      Text('📊 月度出片量').fontSize(13).fontColor(COLORS.title).fontWeight(FontWeight.Bold)
      Blank()
      Text('近 6 个月 · 单位张').fontSize(9).fontColor(COLORS.text3)
    }
    Row({ space: 10 }) {
      ForEach(MONTH_SHOTS, (val: number, idx: number) => {
        Column({ space: 5 }) {
          Text(val.toString()).fontSize(8).fontColor(COLORS.sub)
          Column().width('100%')
            .height((val / MONTH_MAX) * 88 + (this.breath ? 4 : 0))
            .linearGradient({ angle: 180, colors: [[COLORS.cyan, 0], [COLORS.cyanD, 1]] })
          Text(MONTH_NAME[idx]).fontSize(8).fontColor(COLORS.text3)
        }.layoutWeight(1).alignItems(HorizontalAlign.Center)
      })
    }.alignItems(VerticalAlign.Bottom)
  }
}

柱状图采用传统的 Column + ForEach 方案实现，不依赖第三方图表库。每根柱子的高度由 (val / MONTH_MAX) * 88 计算——以 180 张为满高基准映射到 88px 最大高度。柱体使用 180 度 linearGradient（从银盐青到深青）实现自上而下的色调渐变。呼吸动画的融入颇为精巧：柱高在基准值基础上叠加 this.breath ? 4 : 0，使六根柱子每秒同步微动 4px，模拟暗房显影液的液面波动。柱顶标注数值（灰绿），柱底标注月份（暗灰绿），整行以 VerticalAlign.Bottom 底对齐保证柱底齐平。

十四、底部 Tab 栏

@Builder
tabBar() {
  Row() {
    ForEach(TAB_LIST, (t: TabMeta, idx: number) => {
      Column({ space: 3 }) {
        Text(t.icon).fontSize(16).opacity(this.currentTab === idx ? 1 : 0.65)
        Text(t.label).fontSize(8)
          .fontColor(this.currentTab === idx ? COLORS.tabOn : COLORS.text3)
          .fontWeight(this.currentTab === idx ? FontWeight.Bold : FontWeight.Normal)
      }.layoutWeight(1).onClick(() => { this.switchTab(idx); })
    })
  }.backgroundColor(COLORS.card).border({ width: { top: 1 }, color: COLORS.line })
}

底部 Tab 栏以单排 Row + ForEach 渲染 7 个 Tab 项，每项 layoutWeight(1) 等宽分布。选中态的图标 opacity 为 1、标签颜色为银盐青且加粗；未选中态的图标 opacity 降至 0.65、标签颜色为暗灰绿且常规字重。点击调用 switchTab，该方法在离开相机 Tab 时自动释放会话。Tab 栏背景为卡片深灰绿，顶部 1px 分割线以 COLORS.line 低对比度色呈现，不干扰内容区视觉。

十五、弹窗系统

平台实现了三个全屏弹窗，统一采用 Stack + modalOverlay 遮罩 + 居中面板的架构：

@Builder
modalOverlay(onClose: () => void) {
  Stack() {
    Column().width('100%').height('100%').backgroundColor(COLORS.mask)
  }.alignContent(Alignment.Center).onClick(() => onClose())
}

modalOverlay 是弹窗的公共遮罩层，以 rgba(0,0,0,0.6) 半透黑覆盖全屏，点击遮罩区域触发 onClose 回调关闭弹窗。三个弹窗面板均在遮罩之上以 80% 或 74% 宽度居中显示。

新增作品弹窗 panelAdd 包含四个表单字段：主题名（TextInput）、器材（TextInput）、曝光参数（TextInput）、初始收藏数（Slider 0~3000 step 10）。空输入时 saveWork 方法给予默认值（“未命名作品”/“手机直出”/“auto f/1.8 1/120s”），保证数据完整性。保存通过 unshift 置顶作品列表。

编辑收藏数弹窗 panelEdit 仅包含一个收藏数滑杆（0~3000 step 10，暗房琥珀色），顶部显示当前作品的标题与器材。updateWork 方法直接更新 workList[editIdx].likes 字段。

删除确认弹窗 panelDel 以垃圾桶图标和删除标题构成，显示待删除作品的标题与参数。delWork 方法通过 splice(delIdx, 1) 移除对应条目，删除按钮以警示红为底色强化危险操作的视觉警告。

三个弹窗的弹出与关闭均由布尔状态变量驱动（addModal/editModal/delModal），这是 ArkUI 中实现弹窗的轻量级方案——无需引入 CustomDialogController 或 bindSheet 等重型组件，仅凭 if (this.addModal) 条件渲染即可实现弹窗的出现与消失动画。弹窗面板宽度因场景而异：新增弹窗 80%（表单字段多，需更宽空间）、编辑弹窗 80%（与新增保持一致）、删除弹窗 74%（内容少，更紧凑居中）。所有弹窗的面板均以 COLORS.card 深灰绿为底、borderRadius(14) 圆角，与卡片体系保持视觉统一。表单输入框统一使用 COLORS.dark 深色底以区分于面板底色，滑杆的 blockColor 与 selectedColor 根据场景选择银盐青（新增）或暗房琥珀（编辑），在色彩层面暗示操作的语义差异。

十六、功能模块对比表

功能模块	宿主 Tab	核心 API	关键状态变量	数据流向
影随人动	相机	isControlCenterSupported → getSupportedEffectTypes → enableControlCenter	framingState / framingSupported / sessionMode	VideoSession 管线 → 能力链三步 → 状态文案映射颜色
手动对焦	对焦	isFocusDistanceSupported → setFocusDistance → getFocusDistance	focusSupported / focusDistance / focusRecords	PhotoSession 管线 → 能力查询 → 设置读回比对 → 时间线记录
WebP 编码	工坊	createPixelMap → packToData → openSync/writeSync	texIdx / webpQuality / pixelMap / webpPath	像素算法 → PixelMap → ImagePacker → 沙箱落盘
元数据读取	元数据	createImageSource → readImageMetadataByType	metaSnapshot / opLogs	openSync → ImageSource → 类型化读取 → 五字段快照
元数据写回	元数据	writeImageMetadata → 重建 ImageSource 回读	writeDelay / writeLoop / verifySnapshot	字面量构造 → 写回 → 重建 Source → 比对校验
下载溯源	网页	onBeforeDownload → onDownloadFinish → getOriginalUrl/getReferrerUrl	dlState / dlPercent / downloadRecords	Delegate 四回调 → 完成 → 双 URL 提取 → 记录置顶
作品管理	作品	unshift / splice / 索引更新	workList / formTitle / editIdx / delIdx	表单输入 → 新增/编辑/删除 → 列表刷新
呼吸动画	全局	setInterval → breath 翻转	breath / timer	1 秒周期 → 布尔翻转 → 圆点/柱状图微动

十七、总结与展望

本文深度剖析了一个基于 HarmonyOS ArkUI 的摄影创作平台，其核心价值在于将 Camera Kit、ImageKit、ArkWeb 三大系统能力以"特性挂载 Tab、状态顶层共享"的架构有机融合。影随人动能力链通过三步同步查询实现运动跟拍的自动构图；手动对焦三接口通过写后读回比对实现焦距设置的可靠验证；WebP 元数据通过类型化读写与重建 ImageSource 回读校验实现帧参数的可信写入；下载双 URL 溯源通过完成回调中的两个新接口为素材版权提供直链与引用页的双链路证据。

在工程实现层面，平台展现了若干值得借鉴的实践模式：cameraInput 的会话互斥通过 switchTab 中的条件释放实现，避免了资源占用导致的创建失败；WebP 文件以 READ_WRITE 模式落盘，提前为元数据写回接口准备可写文件句柄；回读校验通过重建 ImageSource 绕过解码缓存，确保读到的是写入后的最新值；urlInput 与 webUrl 双状态分离，避免了输入过程中的反复加载。色彩体系以银盐青与暗房琥珀的冷暖对比为基调，呼应了传统暗房工艺的视觉语言。

展望未来，该平台可在以下方向继续演进：一是引入 AI 辅助构图，将影随人动的能力从"人物居中"扩展到"三分法/黄金比例"等构图法则的智能推荐；二是支持 WebP 动画多帧元数据的逐帧编辑，当前仅处理了静态 WebP 的 index=0 帧；三是将下载溯源记录上链存证，为素材版权提供不可篡改的时间戳证据；四是接入分布式相机能力，实现多设备协同的多角度同拍。随着 HarmonyOS 的持续演进，ArkUI 声明式范式与系统能力的深度耦合将为移动摄影创作带来更多可能性。

附录：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 应用的功能开发。

---