下载溯源最近技术点 ArkWeb 双 URL 接口落地办公模板资源平台：HarmonyOS ArkUI 全栈工程从 WebDownloadDelegate 到 Canvas 趋势折线图的实践解析
一、技术前言：当办公模板资源平台遇见 HarmonyOS ArkWeb 双 URL 溯源能力
HarmonyOS 的 ArkUI 框架是华为为全场景分布式设备打造的声明式 UI 开发范式，它以 ArkTS 语言为根基，在 TypeScript 类型安全之上引入了 @Entry、@Component、@State、@Builder、@Observed 等装饰器体系，让开发者用接近自然语言的方式描述界面结构与状态。与传统命令式 UI 编程不同，ArkUI 采用数据驱动渲染，当 @State 修饰的状态变量发生变更时，框架会自动精确刷新与该状态绑定的组件节点，无需手动调用 findViewById 或 setText。这种范式极大简化了复杂界面的状态管理，特别适合需要频繁局部刷新的办公模板资源类应用——用户在浏览模板榜单、触发下载、查看溯源信息时，界面需要在毫秒级完成多区域联动更新。
ArkWeb 是 HarmonyOS 提供的 Web 组件能力集合，它通过 Web 组件将完整的浏览器内核嵌入 ArkUI 界面，使开发者能在原生应用中加载网页、执行 JavaScript、处理网页事件，并通过 webview.WebviewController 控制器对网页进行编程级操作。在 HarmonyOS 6.1.1 版本中，ArkWeb 对 WebDownloadDelegate（下载代理）能力进行了重磅增强，下载完成回调 onDownloadFinish 中新增了 getOriginalUrl() 与 getReferrerUrl() 两个接口，分别用于获取下载项的"原始 URL 地址"与"引用页 URL 地址"。这两个接口的出现，让移动端下载行为的来源审计第一次具备了完整的双链路追溯能力，企业级办公模板平台可以借此记录"用户从哪个详情页、点击了哪个直链、下载了哪个文件"的完整证据链。
getOriginalUrl() 返回的是下载项本身的直链地址，例如 https://dl.mobanpu.cn/ppt/Q3Review_v3.2_20260825.pptx，它对应 CDN 上模板文件的真实存储路径，是文件在传输层的来源。而 getReferrerUrl() 返回的是触发这次下载的引用页地址，例如 https://www.mobanpu.cn/detail?id=3021&from=home_banner，它记录了用户在哪个页面、通过哪个入口点击了下载按钮。两者的区别在于：原始 URL 回答"下载了什么文件、文件从哪台服务器取"，引用页 URL 回答"用户从哪个页面、哪个入口点开的下载"。对于办公模板平台这类高频下载场景，双 URL 溯源能有效解决版权追溯、下载来源统计、模板推荐回流分析、恶意下载检测等核心业务问题。
WebDownloadDelegate 还提供了完整的下载生命周期回调体系，除了 onDownloadFinish 之外，还包括 onBeforeDownload（下载开始前）、onDownloadUpdated（下载进行中）、onDownloadFailed（下载失败）三个回调。onBeforeDownload 是一个关键回调，开发者必须在此调用 WebDownloadItem 的 start() 方法并提供沙箱目录路径，否则下载任务会一直停留在 PENDING 状态而无法真正开始。onDownloadUpdated 在下载过程中被周期性调用，通过 getPercentComplete() 可以获取实时进度百分比，用于驱动进度条等 UI 反馈。onDownloadFailed 在下载异常时触发，通过 getGuid() 可以获取任务唯一标识用于日志排查。这四个回调覆盖了下载的全生命周期，构成了一个完整的可观测下载流水线。
Canvas 绘图能力是 ArkUI 框架提供的另一项重要基础能力，它通过 Canvas 组件与 CanvasRenderingContext2D 上下文，为开发者提供了与 Web Canvas API 高度一致的 2D 绘图接口。开发者可以使用 moveTo、lineTo、arc、fill、stroke、createLinearGradient 等方法绘制自定义图表。本应用在模板 Tab 中用 Canvas 绘制了近 8 周模板下载量趋势折线图，通过 createLinearGradient 实现折线下方的渐变面积填充，通过 moveTo + lineTo 连续连线绘制主折线，通过 arc 绘制数据点圆点，并配合 fillText 标注数值与周标签。更巧妙的是，折线图通过 setInterval 驱动的呼吸动画实现联动重绘——每秒翻转 breath 布尔值后调用 drawLineChart() 重新绘制，使渐变透明度、线宽、数据点半径呈现"呼吸"般的动态效果，让静态图表拥有了生命力。
办公模板/效率资源是移动互联网内容消费的重要赛道，覆盖年终总结、项目方案、求职简历、合同范本、财务报表、营销策划、会议纪要等高频办公场景。用户的核心痛点是：模板来源杂、格式不一、质量参差、下载后找不到来源。将 ArkWeb 双 URL 溯源能力嵌入办公模板平台后，每一次下载都能形成"原始 URL + 引用页 URL + 文件名 + 大小 + 时间 + 用户备注"的完整记录，用户可在"下载"Tab 回溯任何一份模板的来源页面，避免"下载了但忘了从哪来"的尴尬。本应用名为"模板铺"，采用暖米白（#F8F6F2）+ 商务蓝（#2563EB）+ 活力橙（#F59E0B）的浅色三色主题，设计了模板、网页、下载、我的四个功能完全独立的 Tab 页面，每个 Tab 布局都经过差异化设计，是一个功能完备、注释详尽的工程级示例。
二、整体架构流程图
三、模块导入与 ArkWeb 依赖引入
3.1 导入语句
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
这两行导入语句是整个 ArkWeb 双 URL 溯源功能的基石。第一行从 @kit.ArkWeb 中导入了 webview 命名空间，它是 ArkWeb 组件体系的核心入口。webview 命名空间下包含了 WebviewController（Web 控制器，用于编程式控制网页加载、前进后退、主动下载等）、WebDownloadDelegate（下载代理，承载下载生命周期回调）、WebDownloadItem（下载项，承载一次下载任务的元数据与方法）三个核心类。本应用的下载溯源能力正是建立在这三个类的协作之上：WebviewController 负责绑定下载代理与主动发起下载，WebDownloadDelegate 负责承接下载过程的四个回调，WebDownloadItem 负责在回调中提供文件名、大小、进度、原始 URL、引用页 URL 等数据。
第二行从 @kit.BasicServicesKit 中导入了 BusinessError 类型。这是 HarmonyOS 统一的错误处理接口，包含 code（错误码）和 message（错误描述）两个字段。在 setDownloadDelegate 绑定代理、startDownload 主动发起下载等可能抛错的调用处，通过 try-catch 捕获 BusinessError 可以精确获取错误码与错误描述，避免应用因未处理异常而崩溃。例如，当下载代理在未就绪时被绑定，或下载 URL 不合法时，系统会抛出携带具体 code 的 BusinessError，开发者据此向用户展示友好提示，而不是让界面卡死或闪退。
值得注意的是，ArkWeb 的下载代理是"网页内触发下载"与"应用侧主动发起下载"两条路径的统一收口。无论是用户在 Web 组件加载的网页里点击了一个 <a href="xxx.pptx" download> 链接，还是应用代码调用 webController.startDownload(url) 主动发起下载，最终都会进入 WebDownloadDelegate 的四个回调。这种统一收口设计让下载审计逻辑只需在一处实现，就能覆盖所有下载来源，极大简化了溯源代码的维护成本。
四、颜色系统设计
4.1 颜色接口定义
/** 主题色板接口：集中声明页面所有颜色字段（暖米白+商务蓝+活力橙浅色系） */
interface ColorPalette {
bg: string; // 暖米白页面底色
card: string; // 纯白卡片底色
chip: string; // 浅米色 chip / 输入底色
title: string; // 深炭标题色
sub: string; // 中灰副文本
text3: string; // 浅灰弱文本
blue: string; // 商务蓝主色
blueD: string; // 深商务蓝
orange: string; // 活力橙强调色
red: string; // 风险红
green: string; // 增长绿
line: string; // 极浅分割线
tabOn: string; // Tab 选中色
mask: string; // 半透明遮罩
codeBg: string; // 深藏蓝代码预览底色
gradTop: string; // 折线图渐变顶部（呼吸亮）
gradTopDim: string; // 折线图渐变顶部（呼吸暗）
gradBottom: string; // 折线图渐变底部
}
ColorPalette 接口将页面用到的所有颜色字段集中声明为一个类型契约。这种设计的好处在于：当需要切换主题（例如从浅色暖米白切换到深色极夜）时，只需创建一个新的 ColorPalette 实现对象替换 COLORS 常量即可，无需在代码中逐一搜索替换散落的颜色值。接口中的字段涵盖了界面所需的全部色彩角色：bg 是页面背景色，card 是卡片背景色，chip 是标签芯片与输入框背景色，title/sub/text3 构成三级文字色阶，blue/blueD 是商务蓝主色及其深色变体，orange 是活力橙强调色，red/green 用于风险与增长场景，line 是分割线，tabOn 是底部 Tab 选中色，mask 是弹窗遮罩，codeBg 是代码预览深色底，gradTop/gradTopDim/gradBottom 是折线图渐变的三档透明度色。
特别值得注意是 gradTop 与 gradTopDim 这两个字段。它们对应折线图渐变面积填充的顶部色，gradTop 是呼吸亮态（rgba(37,99,235,0.34)，透明度 0.34），gradTopDim 是呼吸暗态（rgba(37,99,235,0.20)，透明度 0.20）。在 drawLineChart() 中，根据 breath 布尔值二选一使用，使折线图面积呈现每秒一次的"呼吸"明暗变化。这种将动画状态编码进颜色接口的设计，让呼吸动画的色彩参数也纳入了集中管理，便于后续调整动画节奏时只改一处常量。
4.2 浅色主题色板常量
/** 浅色主题色板常量（模板铺 · 暖米白 + 商务蓝 + 活力橙） */
const COLORS: ColorPalette = {
bg: '#F8F6F2',
card: '#FFFFFF',
chip: '#F0EBE0',
title: '#2B2926',
sub: '#6B6459',
text3: '#A39B8C',
blue: '#2563EB',
blueD: '#1D4ED8',
orange: '#F59E0B',
red: '#DC2626',
green: '#16A34A',
line: '#EAE4D8',
tabOn: '#2563EB',
mask: 'rgba(43,41,38,0.42)',
codeBg: '#16233F',
gradTop: 'rgba(37,99,235,0.34)',
gradTopDim: 'rgba(37,99,235,0.20)',
gradBottom: 'rgba(37,99,235,0.02)'
};
COLORS 常量是 ColorPalette 接口的浅色主题实现实例。暖米白 #F8F6F2 作为页面底色，不是纯白而是带轻微米色调，降低了大面积白底对眼睛的刺激，更符合长时间办公阅读的舒适度需求。纯白 #FFFFFF 用于卡片底色，与米白底色形成微弱但可感知的层次差，使卡片从背景中"浮起"。浅米色 #F0EBE0 用于 chip 与输入框，比卡片底色更暖更沉，形成"输入区"与"展示区"的视觉区隔。
商务蓝 #2563EB 与深商务蓝 #1D4ED8 构成品牌主色对，深商务蓝用于渐变起点，商务蓝用于渐变中段，使头部 Banner 与职场身份大卡呈现由深到浅的层次感。活力橙 #F59E0B 作为强调色，用于折线图末点高亮、下载记录的引用页 URL 文字色、橙色描边按钮等关键视觉锚点，与商务蓝形成冷暖对比。风险红 #DC2626 用于删除按钮与下降趋势，增长绿 #16A34A 用于上升趋势与环比正向数据。代码预览底色 #16233F 是深藏蓝，与页面浅色主题形成强对比，模拟代码编辑器的深色主题观感。遮罩 rgba(43,41,38,0.42) 采用与标题色 #2B2926 同色系的半透明，保证遮罩与主题色系一致性。
五、常量定义
5.1 底部导航 Tab 元数据
/** Tab 元数据接口：底部导航图标 + 标签 */
interface TabMeta {
icon: string;
label: string;
}
/** 底部导航 Tab 常量列表（4 Tab 单排） */
const TAB_LIST: TabMeta[] = [
{ icon: '📋', label: '模板' },
{ icon: '🌐', label: '网页' },
{ icon: '⬇', label: '下载' },
{ icon: '👤', label: '我的' }
];
TabMeta 接口定义了底部导航条目的数据结构，包含 icon（emoji 图标）与 label（文字标签）两个字段。将 Tab 元数据抽象为接口，使 Tab 配置与渲染逻辑解耦——新增或调整 Tab 只需修改 TAB_LIST 常量，无需改动 tabBar() Builder 的渲染代码。TAB_LIST 常量定义了四个 Tab：模板（精选合集 + 热门榜 + 折线图）、网页（ArkWeb 特性页）、下载（下载管理 + 双 URL 溯源）、我的（职场身份 + 功能清单）。四个 Tab 覆盖了办公模板平台"浏览—触达—下载—管理"的完整用户旅程。
使用 emoji 作为图标是一种轻量化的设计选择。相比使用 Image 组件加载图标资源，emoji 无需任何图片资源文件，跨平台显示一致（在 HarmonyOS 系统字体支持下），且支持任意颜色叠加（通过 fontColor）。📋 代表模板列表，🌐 代表网页浏览器，⬇ 代表下载方向，👤 代表个人中心，语义清晰直观。
5.2 头部场景 chips 与精选合集常量
/** 头部横滑场景 chips 文案（办公模板使用场景） */
const CATE_TAGS: string[] = ['全部', '年终总结', '项目方案', '求职简历', '合同范本', '财务报表', '营销策划', '会议纪要'];
/** 精选模板合集名（精选卡区副标题文案） */
const SERIES_NAME: string = '年终汇报全家桶';
CATE_TAGS 常量定义了头部横滑场景 chips 的文案数组，包含八个办公场景标签。这些场景覆盖了职场人士最常遇到的文档需求：年终总结对应季度/年度复盘汇报，项目方案对应立项与执行规划，求职简历对应社招校招投递，合同范本对应法务合规，财务报表对应预算与对账，营销策划对应活动与投放，会议纪要对应会后整理。"全部"作为第一个标签是默认选中项，表示不按场景过滤。
将场景文案抽离为常量而非硬编码在 Builder 函数内，便于后续接入真实接口——后端返回的场景列表可直接赋值给一个同类型变量，渲染逻辑无需改动。SERIES_NAME 常量定义了精选模板合集的名称"年终汇报全家桶"，"全家桶"一词借用了软件套装的命名惯例，暗示这套合集覆盖了年终汇报场景下的 PPT、Word、Excel 三大格式，是一站式解决方案。
5.3 快捷站点与折线图数据
/** 快捷站点常量（网页 Tab 横滑入口，办公协同类真实站点） */
const QUICK_SITES: string[] = [
'https://docs.qq.com',
'https://www.kdocs.cn',
'https://www.processon.com',
'https://shimo.im'
];
/** 折线图数据点接口（近 8 周下载趋势，周维度） */
interface LinePoint {
val: number; // 周下载量（万次）
label: string; // 周起始日期标签
}
/** 近 8 周模板下载量趋势 Mock 数据（周维度） */
const WEEK_TREND: LinePoint[] = [
{ val: 8.6, label: '07-07' },
{ val: 9.8, label: '07-14' },
{ val: 11.4, label: '07-21' },
{ val: 10.2, label: '07-28' },
{ val: 12.8, label: '08-04' },
{ val: 14.6, label: '08-11' },
{ val: 16.2, label: '08-18' },
{ val: 18.9, label: '08-25' }
];
/** 折线图纵轴最大值（万次） */
const TREND_MAX: number = 20;
QUICK_SITES 常量定义了网页 Tab 横滑入口的四个真实办公协同站点：腾讯文档（docs.qq.com）、金山文档（kdocs.cn）、ProcessOn 思维导图（processon.com）、石墨文档（shimo.im）。这四个站点都是职场高频使用的在线协同工具，用户在办公模板平台下载模板后，往往需要去这些站点二次编辑或分享。将它们作为快捷入口集成在网页 Tab，形成"下载模板—在线协同"的闭环工作流。
LinePoint 接口定义了折线图数据点结构，包含 val（周下载量，单位万次）与 label（周起始日期标签）两个字段。WEEK_TREND 常量是近 8 周模板下载量趋势的 Mock 数据，从 07-07 周的 8.6 万次起步，到 08-25 周达到 18.9 万次，整体呈上升趋势，中间 07-28 周有一个小回落（10.2 万次），模拟真实业务数据的波动性。TREND_MAX 常量定义纵轴最大值为 20 万次，略高于数据最大值 18.9，使折线最高点不会顶到图表上沿，留出视觉呼吸空间。
将折线图数据抽离为独立常量，便于后续替换为真实接口返回的趋势数据。drawLineChart() 方法通过遍历 WEEK_TREND 数组计算每个数据点的像素坐标，数据源与绘制逻辑完全解耦——只要替换 WEEK_TREND 为新的 LinePoint[] 数组，折线图会自动重新绘制对应形状，无需改动任何绘图代码。
六、辅助函数设计
6.1 趋势颜色与图标映射
/** 榜单趋势颜色映射：上升绿 / 下降红 / 持平弱化 */
function trendColor(t: string): string {
if (t === 'up') { return COLORS.green; }
if (t === 'down') { return COLORS.red; }
return COLORS.text3;
}
/** 榜单趋势图标文案：上升 / 下降 / 持平 */
function trendIcon(t: string): string {
if (t === 'up') { return '↑ 上升'; }
if (t === 'down') { return '↓ 下降'; }
return '— 持平';
}
trendColor 与 trendIcon 是一对配套的辅助函数，用于将榜单条目的趋势字符串（'up'/'down'/'flat'）映射为视觉表现。trendColor 返回对应的颜色值：上升用增长绿 #16A34A，下降用风险红 #DC2626，持平用浅灰弱文本色 #A39B8C。trendIcon 返回对应的图标文案：上升是 ↑ 上升，下降是 ↓ 下降，持平是 — 持平。
这两个函数的设计体现了"数据驱动 UI"的理念。趋势字符串 'up'/'down'/'flat' 是从后端数据模型直接来的原始字段，通过辅助函数映射为颜色和文案，使渲染代码无需写一堆 if-else 分支。在 rankCard() Builder 中调用方式是 trendColor(t.trend) 与 trendIcon(t.trend)，代码极其简洁。如果未来要新增"暴涨" surge 等新趋势类型，只需修改这两个辅助函数，所有榜单条目的渲染会自动更新。
6.2 格式颜色映射
/** 格式标签颜色映射：PPT 商务蓝 / Word 活力橙 / Excel 增长绿 */
function fmtColor(fmt: string): string {
if (fmt === 'PPT') { return COLORS.blue; }
if (fmt === 'Word') { return COLORS.orange; }
return COLORS.green;
}
fmtColor 函数将模板格式字符串映射为颜色值：PPT 用商务蓝（#2563EB），Word 用活力橙（#F59E0B），Excel 用增长绿（#16A34A）。这种格式-颜色固定映射的设计，使用户在浏览榜单时能通过颜色快速识别模板格式——蓝色一眼识别 PPT，橙色一眼识别 Word，绿色一眼识别 Excel，降低了认知负担。
函数的 fallback 逻辑是 return COLORS.green，即当传入的格式字符串既不是 PPT 也不是 Word 时，默认返回增长绿。这是一种防御性编程策略，应对未来可能新增的 PDF、WPS 等格式时，至少有一个合理的默认颜色，不会因为 undefined 而导致渲染异常。如果业务上需要为 PDF 设置专属颜色，只需在函数内新增一个 if (fmt === 'PDF') { return COLORS.xxx; } 分支。
6.3 站点 URL 转展示域名
/** 站点 URL 转展示域名（去掉协议前缀，地址栏/快捷站点卡用） */
function siteHost(url: string): string {
const head = 'https://';
if (url.startsWith(head)) {
return url.slice(head.length);
}
return url;
}
siteHost 函数将完整的 URL（如 https://docs.qq.com）转换为展示用的域名（如 docs.qq.com），去掉 https:// 协议前缀。这个函数用于网页 Tab 的快捷站点卡片，使卡片上显示的是简洁的域名而非冗长的完整 URL，提升了信息可读性。
函数实现简洁：先判断 URL 是否以 https:// 开头，是则用 slice 去掉前 8 个字符（https:// 的长度），否则原样返回。注意此函数只处理 https:// 前缀，不处理 http://，因为 QUICK_SITES 常量中所有站点都是 https:// 协议。如果未来要兼容 http:// 前缀，可以扩展判断逻辑。这种聚焦当前业务范围的实现方式，避免了过度设计，保持了代码的简洁性。
七、数据模型设计
7.1 精选模板合集条目
/** 精选模板合集条目（模板 Tab 精选卡：模板名 + 格式 PPT/Word/Excel + 适用场景） */
@Observed export class SeriesItem {
icon: string; // 格式徽标 emoji
name: string; // 模板名
fmt: string; // 格式与规模（如 PPT · 26 页）
scene: string; // 适用场景
constructor(icon: string, name: string, fmt: string, scene: string) {
this.icon = icon;
this.name = name;
this.fmt = fmt;
this.scene = scene;
}
}
/** 精选模板 Mock 数据（3 条，覆盖 PPT / Word / Excel 三大格式） */
const SERIES_LIST: Array<SeriesItem> = [
new SeriesItem('📊', 'Q3 复盘汇报蓝图', 'PPT · 26 页', '季度复盘 / 高管汇报'),
new SeriesItem('📈', '互联网大厂简历模板', 'Word · 2 页', '社招投递 / 内推专场'),
new SeriesItem('🧮', '全年预算管控表', 'Excel · 9 张表', '年度预算 / 财务对齐')
];
SeriesItem 是精选模板合集条目的数据模型类，使用 @Observed 装饰器修饰。@Observed 是 ArkUI 的可观察数据装饰器，它使类的实例属性在被 @State 修饰的数组中发生变更时，能够被框架精确追踪并触发对应 ForEach 项的局部刷新。与直接使用 interface 不同，@Observed class 配合构造函数，使数据创建更规范，也支持后续在实例上修改属性后触发响应式刷新。
SeriesItem 包含四个字段：icon（格式徽标 emoji，如 📊 代表 PPT 图表）、name（模板名，如"Q3 复盘汇报蓝图"）、fmt（格式与规模，如"PPT · 26 页"，同时包含格式与页数信息）、scene（适用场景，如"季度复盘 / 高管汇报"，用斜杠分隔多个场景）。SERIES_LIST Mock 数据包含三条，分别覆盖 PPT、Word、Excel 三大格式，体现精选合集的格式多样性。
7.2 热门模板榜单条目
/** 热门模板榜单条目（模板 Tab 大编号热榜） */
@Observed export class TplItem {
rank: string; // 名次字符串
name: string; // 模板名
author: string; // 出品方
fmt: string; // 格式标签：PPT / Word / Excel
heat: string; // 本周下载量文本
trend: string; // 趋势：'up' / 'down' / 'flat'
constructor(rank: string, name: string, author: string, fmt: string, heat: string, trend: string) {
this.rank = rank;
this.name = name;
this.author = author;
this.fmt = fmt;
this.heat = heat;
this.trend = trend;
}
}
/** 热门模板榜 Mock 数据（8 条，含格式 / 下载量 / 趋势） */
const TPL_LIST: Array<TplItem> = [
new TplItem('1', 'Q3 复盘汇报蓝图', '效率研究所', 'PPT', '42.1万', 'up'),
new TplItem('2', '商务风并购尽调报告', '华章文库', 'Word', '38.6万', 'up'),
new TplItem('3', '互联网大厂简历模板', '简历工场', 'Word', '35.9万', 'flat'),
new TplItem('4', '全年预算管控表', '财智表格社', 'Excel', '29.4万', 'down'),
new TplItem('5', '年会活动策划全案', '会务星球', 'PPT', '26.7万', 'up'),
new TplItem('6', '劳动合同范本 2026 版', '法务帮', 'Word', '22.8万', 'down'),
new TplItem('7', '融资商业计划书', '蓝海资本库', 'PPT', '19.5万', 'up'),
new TplItem('8', '部门周报自动化看板', '数据驾驶舱', 'Excel', '16.2万', 'flat')
];
TplItem 是热门模板榜单条目的数据模型类，同样使用 @Observed 装饰器。包含六个字段：rank（名次字符串，如 '1'）、name（模板名）、author（出品方，如"效率研究所"）、fmt（格式标签，用于 fmtColor 函数映射颜色）、heat（本周下载量文本，如"42.1万"）、trend（趋势字符串，用于 trendColor/trendIcon 函数映射）。
TPL_LIST Mock 数据包含八条，覆盖了 Q3 复盘、并购尽调、简历、预算、年会策划、劳动合同、融资 BP、周报看板等八大典型办公场景。趋势分布上，up（上升）4 条、down（下降）2 条、flat（持平）2 条，模拟真实榜单的动态变化。第一名"Q3 复盘汇报蓝图"下载量 42.1 万、上升趋势，与精选合集第一条形成呼应，暗示这是当前最热门的模板。
7.3 下载记录条目（双 URL 溯源核心数据载体）
/** 下载记录条目（下载 Tab 双 URL 溯源卡：ArkWeb 6.1.1 特性数据载体） */
@Observed export class DownloadRecord {
fileName: string; // 文件名
fileSize: string; // 大小文本
finishTime: string; // 完成时间
originalUrl: string; // ★ getOriginalUrl() 结果：下载项原始 URL
referrerUrl: string; // ★ getReferrerUrl() 结果：引用页 URL
note: string; // 用户备注（可编辑）
constructor(fileName: string, fileSize: string, finishTime: string,
originalUrl: string, referrerUrl: string, note: string) {
this.fileName = fileName;
this.fileSize = fileSize;
this.finishTime = finishTime;
this.originalUrl = originalUrl;
this.referrerUrl = referrerUrl;
this.note = note;
}
}
/** 历史下载记录 Mock 数据（6 条，pptx/docx/xlsx 文件 + 资源站直链 + 详情页引用页） */
const DOWNLOAD_RECORDS: Array<DownloadRecord> = [
new DownloadRecord('Q3复盘汇报蓝图_v3.2.pptx', '12.8 MB', '今天 09:42',
'https://dl.mobanpu.cn/ppt/Q3Review_v3.2_20260825.pptx',
'https://www.mobanpu.cn/detail?id=3021&from=home_banner', '年终汇报用'),
new DownloadRecord('商务尽调报告_v1.8.docx', '0.9 MB', '今天 08:15',
'https://cdn.huazhang.cn/doc/DueDiligence_v1.8.docx',
'https://www.huazhang.cn/rank/top?tab=word', '董事会评审'),
new DownloadRecord('全年预算管控表_v5.0.xlsx', '2.4 MB', '昨天 21:36',
'https://mirror.caizhi.cn/xls/Budget2026_v5.0.xlsx',
'https://www.caizhi.cn/tpl/648/detail', '财务对齐'),
new DownloadRecord('大厂简历模板_A4_v2.3.docx', '0.6 MB', '昨天 19:04',
'https://dl.jianlichang.cn/resume/Resume_A4_v2.3.docx',
'https://jianlichang.cn/search?q=简历模板', '社招投递'),
new DownloadRecord('年会策划全案_v4.1.pptx', '18.6 MB', '昨天 12:48',
'https://pkg.huiwuxing.cn/annual/AnnualParty_v4.1.pptx',
'https://www.huiwuxing.cn/promo/free2026', '限时免费'),
new DownloadRecord('部门周报看板_v2.0.xlsx', '1.2 MB', '08-23 10:22',
'https://down.shujukong.cn/xls/WeeklyBoard_v2.0.xlsx',
'https://so.shujukong.cn/search?q=周报模板', '搜索下载')
];
DownloadRecord 是本应用最核心的数据模型，它是 ArkWeb 6.1.1 双 URL 溯源特性的数据载体。包含六个字段：fileName（文件名）、fileSize（大小文本）、finishTime（完成时间）、originalUrl（原始 URL，对应 getOriginalUrl() 结果）、referrerUrl（引用页 URL，对应 getReferrerUrl() 结果）、note（用户备注，可编辑）。
originalUrl 与 referrerUrl 这两个字段是双 URL 溯源的灵魂。从 Mock 数据可以清晰看到两者的区别：以第一条为例，originalUrl 是 https://dl.mobanpu.cn/ppt/Q3Review_v3.2_20260825.pptx，这是模板文件在 CDN 上的直链，对应文件传输来源；referrerUrl 是 https://www.mobanpu.cn/detail?id=3021&from=home_banner，这是用户点击下载时所在的详情页，还携带了 from=home_banner 参数表明用户是从首页 Banner 进入的。两者结合，完整还原了"用户从首页 Banner 进入详情页 3021，下载了 Q3Review_v3.2 这份 PPT"的完整行为链。
DOWNLOAD_RECORDS Mock 数据包含六条，覆盖 pptx/docx/xlsx 三种格式，分别来自模板铺、华章文库、财智表格社、简历工场、会务星球、数据空等六个不同的模板资源站，引用页涵盖了详情页、榜单页、模板页、搜索页、活动页、搜索页等多种入口类型。这种多样化的 Mock 数据，充分展示了双 URL 溯源在不同场景下的记录形态。note 字段是用户自定义备注，如"年终汇报用"、“董事会评审”、"限时免费"等，使每条记录都带有用户的业务上下文，便于后续按业务用途检索。
7.4 我的页功能清单条目
/** 我的页功能清单条目 */
@Observed export class UserStat {
icon: string; // 功能图标
label: string; // 功能名
value: string; // 状态/数值文本
arrow: boolean; // 是否显示右箭头
constructor(icon: string, label: string, value: string, arrow: boolean) {
this.icon = icon;
this.label = label;
this.value = value;
this.arrow = arrow;
}
}
/** 我的页功能清单 Mock 数据（8 行） */
const STAT_LIST: Array<UserStat> = [
new UserStat('⬇', '累计下载', '186 套模板', true),
new UserStat('🔗', '来源审计', '双 URL 溯源已开启', true),
new UserStat('📁', '下载目录', '/data/storage/files', true),
new UserStat('⭐', '收藏模板', '64 套已归档', true),
new UserStat('🕘', '下载历史', '近 30 天 38 条', true),
new UserStat('🔄', '格式偏好', 'PPT 优先提示', true),
new UserStat('🛡', '模板安全校验', '已拦截 2 个风险文件', true),
new UserStat('⚙', '下载偏好设置', '仅 Wi-Fi 下载', true)
];
UserStat 是我的页功能清单条目的数据模型类，包含四个字段：icon（功能图标 emoji）、label（功能名）、value（状态或数值文本）、arrow（是否显示右箭头）。arrow 字段的设计预留了灵活性——虽然当前所有条目都为 true，但未来某些纯展示型功能（如"累计下载"）可以设为 false 不显示箭头，表示该行不可点击进入二级页。
STAT_LIST Mock 数据包含八行，覆盖了累计下载、来源审计、下载目录、收藏模板、下载历史、格式偏好、模板安全校验、下载偏好设置等八项功能。其中第二行"来源审计"的 value 是"双 URL 溯源已开启"，直接呼应了本应用的核心特性，使用户在"我的"页能直观确认溯源能力已生效。第七行"模板安全校验"的 value 是"已拦截 2 个风险文件"，体现了平台的安全能力。这些功能清单项构成了一个完整的个人中心信息架构。
八、组件主体：状态管理
8.1 主组件声明与基础状态
/** 1125 模板铺 · 办公模板资源平台主页面 */
@Entry
@Component
struct Page1125 {
/** 当前选中 Tab 索引 */
@State currentTab: number = 0;
/** 呼吸动画开关（每秒翻转，联动折线图与胶囊） */
@State breath: boolean = false;
/** 呼吸动画定时器句柄 */
@State timer: number = -1;
/** 头部场景 chips 选中索引 */
@State cateIdx: number = 0;
/** 新建下载任务弹窗开关 */
@State addModal: boolean = false;
/** 编辑备注弹窗开关 */
@State editModal: boolean = false;
/** 删除记录确认弹窗开关 */
@State delModal: boolean = false;
/** 当前编辑的记录索引 */
@State editIdx: number = 0;
/** 当前删除的记录索引 */
@State delIdx: number = 0;
Page1125 是应用的主页面组件，使用 @Entry 与 @Component 装饰器修饰。@Entry 表示这是应用的入口组件，@Component 表示这是一个自定义组件。组件内部通过一系列 @State 修饰的状态变量管理界面状态。
currentTab 是当前选中 Tab 的索引（0-3），控制主内容区显示哪个 Tab 的 Builder 函数，初始值 0 表示默认进入模板 Tab。breath 是呼吸动画开关，每秒由定时器翻转一次，联动折线图渐变透明度、线宽、数据点半径等多处视觉效果。timer 是定时器句柄，用于在组件销毁时清理定时器，避免内存泄漏。cateIdx 是头部场景 chips 的选中索引，控制哪个 chip 高亮显示。
addModal/editModal/delModal 是三个弹窗的开关布尔值，通过条件渲染控制对应弹窗的显示与隐藏。editIdx 与 delIdx 分别记录当前正在编辑或删除的记录索引，使弹窗内的操作能精确定位到目标记录。这种"开关状态 + 索引状态"的组合，是 ArkUI 弹窗系统的经典状态管理模式。
8.2 数据状态与表单状态
/** 精选模板合集数据 */
@State seriesList: Array<SeriesItem> = SERIES_LIST;
/** 热门模板榜数据 */
@State tplList: Array<TplItem> = TPL_LIST;
/** 下载记录列表数据 */
@State downloadRecords: Array<DownloadRecord> = DOWNLOAD_RECORDS;
/** 我的页功能清单数据 */
@State statList: Array<UserStat> = STAT_LIST;
/** 新建表单：模板直链 URL */
@State formUrl: string = '';
/** 新建表单：备注 */
@State formNote: string = '';
/** 编辑表单：记录备注 */
@State editNote: string = '';
这组状态变量管理组件的数据源与表单输入。seriesList、tplList、downloadRecords、statList 分别是四个 Tab 的列表数据源，初始值直接赋值为对应的 Mock 常量。由于这些常量中的元素都是 @Observed 类的实例，当元素属性被修改时（如修改 downloadRecords 中某条记录的 note 字段），框架能精确追踪并触发对应 ForEach 项的刷新。
formUrl 与 formNote 是新建下载任务弹窗的表单字段，分别对应模板直链 URL 与用户备注。editNote 是编辑备注弹窗的表单字段，对应记录备注。这三个表单状态在弹窗打开时初始化，在 TextInput 的 onChange 回调中实时更新，在弹窗确认时被业务方法读取并写入数据源。
8.3 Canvas 与 ArkWeb 状态
// --- Canvas 状态（模板 Tab 近 8 周下载趋势折线图） ---
/** 折线图 Canvas 就绪标志 */
@State canvasReady: boolean = false;
/** 折线图 Canvas 上下文（private，不用 @State） */
private lineCtx: CanvasRenderingContext2D = new CanvasRenderingContext2D(new RenderingContextSettings(true));
// --- ArkWeb 状态（6.1.1 特性：双 URL 溯源） ---
/** Web 控制器（加载页面 + 绑定下载代理 + 主动发起下载） */
private webController: webview.WebviewController = new webview.WebviewController();
/** 下载代理（四个回调：开始前/进行中/失败/完成） */
private downloadDelegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
/** 地址栏输入值（敲字不等于加载） */
@State urlInput: string = QUICK_SITES[0];
/** Web 组件实际加载值（点"前往"后才更新） */
@State webUrl: string = QUICK_SITES[0];
/** 当前下载文件名 */
@State dlName: string = '';
/** 当前下载进度（0~100） */
@State dlPercent: number = 0;
/** 下载状态文案 */
@State dlState: string = '空闲';
Canvas 状态包含 canvasReady（Canvas 就绪标志，@State 修饰，用于在呼吸定时器中判断是否可以重绘）与 lineCtx（Canvas 2D 上下文，private 修饰，不参与响应式）。lineCtx 通过 new CanvasRenderingContext2D(new RenderingContextSettings(true)) 创建，RenderingContextSettings(true) 的 true 参数开启抗锯齿，使折线与圆点边缘更平滑。lineCtx 不用 @State 是因为它本身不变化，变化的是它绘制的内容，通过手动调用 drawLineChart() 触发重绘。
ArkWeb 状态是本应用的核心。webController 是 WebviewController 实例，负责加载网页（通过 Web 组件的 src 属性绑定）、绑定下载代理（setDownloadDelegate）、主动发起下载（startDownload）。downloadDelegate 是 WebDownloadDelegate 实例，承载四个下载回调。urlInput 与 webUrl 的双状态分离是一个精妙设计——urlInput 是地址栏输入值，用户敲字时实时更新但不触发加载；webUrl 是 Web 组件实际加载值，只有用户点击"前往"按钮后才更新，避免用户每敲一个字符就触发一次网页加载。
dlName、dlPercent、dlState 是当前下载任务的三项状态，分别对应文件名、进度百分比、状态文案。这些状态在下载代理的回调中被更新，驱动下载 Tab 的进度条与状态文案实时刷新。
九、组件主体：业务方法
9.1 下载代理注册（双 URL 溯源核心）
/** 注册下载代理：四回调齐全，完成回调中调用 6.1.1 新增双接口 */
setupDownloadDelegate() {
// 下载开始前：必须调用 start() 提供沙箱路径，否则任务停在 PENDING
this.downloadDelegate.onBeforeDownload((item: webview.WebDownloadItem) => {
const hostCtx = this.getUIContext().getHostContext();
const dir = hostCtx ? hostCtx.filesDir : '';
item.start(dir + '/' + item.getSuggestedFileName());
});
// 下载进行中：刷新进度条与状态文案
this.downloadDelegate.onDownloadUpdated((item: webview.WebDownloadItem) => {
this.dlPercent = item.getPercentComplete();
this.dlState = '正在下载 ' + item.getPercentComplete() + '%';
});
// 下载失败：置失败文案（进度清零）
this.downloadDelegate.onDownloadFailed((item: webview.WebDownloadItem) => {
this.dlState = '下载失败 · ' + item.getGuid();
this.dlPercent = 0;
});
// 下载完成：★ 6.1.1 新特性——getOriginalUrl + getReferrerUrl 双溯源
this.downloadDelegate.onDownloadFinish((item: webview.WebDownloadItem) => {
const originalUrl: string = item.getOriginalUrl(); // 原始 URL 地址
const referrerUrl: string = item.getReferrerUrl(); // 引用页 URL 地址
this.downloadRecords.unshift(new DownloadRecord(
item.getSuggestedFileName(), (Math.round(item.getTotalBytes() / 10485.76) / 10) + ' MB',
'刚刚', originalUrl, referrerUrl, '本次会话下载'));
this.dlState = '下载完成';
this.dlPercent = 100;
});
// 绑定到 controller：网页内触发的下载才会进入上述回调（try-catch 消除抛错告警）
try {
this.webController.setDownloadDelegate(this.downloadDelegate);
} catch (error) {
console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
}
}
setupDownloadDelegate() 是本应用最核心的业务方法，它完成了下载代理的四回调注册与控制器绑定，是 ArkWeb 6.1.1 双 URL 溯源能力的落地实现。方法体内注册了四个回调，完整覆盖了下载的全生命周期。
第一个回调 onBeforeDownload 在下载开始前触发，参数是 WebDownloadItem 实例。这里有一个关键操作：必须调用 item.start(dir + '/' + item.getSuggestedFileName()) 提供沙箱存储路径，否则下载任务会一直停留在 PENDING 状态无法真正开始。getUIContext().getHostContext() 获取宿主上下文，filesDir 是应用沙箱的文件目录，getSuggestedFileName() 获取系统建议的文件名（通常根据 URL 推断或服务器 Content-Disposition 头解析）。两者拼接形成完整的保存路径，如 /data/storage/files/Q3Review_v3.2_20260825.pptx。
第二个回调 onDownloadUpdated 在下载进行中周期性触发，通过 getPercentComplete() 获取实时进度百分比，更新 dlPercent 与 dlState，驱动下载 Tab 的进度条与状态文案实时刷新。第三个回调 onDownloadFailed 在下载失败时触发，通过 getGuid() 获取任务唯一标识，用于日志排查，同时将进度清零、状态置为失败文案。
第四个回调 onDownloadFinish 是双 URL 溯源的核心。这里调用了 HarmonyOS 6.1.1 新增的两个接口：item.getOriginalUrl() 获取下载项的原始 URL 地址（即文件直链），item.getReferrerUrl() 获取引用页 URL 地址（即触发下载的页面）。两者结合构造一个完整的 DownloadRecord 实例，通过 unshift 插入到 downloadRecords 数组头部（最新记录显示在最上方），同时记录文件名（getSuggestedFileName()）、大小（getTotalBytes() 换算为 MB）、时间（“刚刚”）、备注（“本次会话下载”）。最后四个回调注册完成后，通过 webController.setDownloadDelegate(this.downloadDelegate) 将代理绑定到控制器，此后无论是网页内点击下载链接还是应用侧调用 startDownload，都会进入这四个回调。绑定操作用 try-catch 包裹，捕获可能的 BusinessError，避免在代理未就绪或重复绑定时抛错导致应用崩溃。
9.2 地址栏加载与主动下载
/** 地址栏"前往"：校验协议前缀（无 http(s):// 时自动补 https://）再加载 */
loadUrl() {
let url = this.urlInput.trim();
if (url === '') {
return;
}
if (!url.startsWith('https://') && !url.startsWith('http://')) {
url = 'https://' + url;
}
this.urlInput = url;
this.webUrl = url;
}
/** 应用侧主动发起下载（无需网页内点击，try-catch 包裹 BusinessError） */
triggerDownload(url: string) {
try {
this.dlName = url.slice(url.lastIndexOf('/') + 1);
this.dlPercent = 0;
this.dlState = '已发起下载请求';
this.webController.startDownload(url);
} catch (error) {
this.dlState = '发起失败 ' + (error as BusinessError).code;
}
}
loadUrl() 方法处理地址栏"前往"按钮的点击事件。它实现了协议前缀自动补全逻辑：先 trim() 去除首尾空格，空字符串直接返回不加载；再判断是否以 https:// 或 http:// 开头，若都不是则自动补 https:// 前缀（默认走更安全的 HTTPS）。最后同步更新 urlInput（地址栏显示补全后的 URL）与 webUrl（Web 组件实际加载的 URL）。这种"敲字不等于加载，点前往才加载"的双状态分离设计，避免了用户每敲一个字符就触发一次网页加载的性能浪费。
triggerDownload(url) 方法实现了应用侧主动发起下载的能力。它通过 url.slice(url.lastIndexOf('/') + 1) 从 URL 中提取文件名（取最后一个 / 之后的部分），更新 dlName、dlPercent（清零）、dlState（置为"已发起下载请求"），然后调用 webController.startDownload(url) 真正发起下载。整个调用用 try-catch 包裹，捕获 BusinessError，失败时将状态置为"发起失败 + 错误码"。这种应用侧主动下载能力，使应用无需依赖网页内的下载链接，就能直接从模板资源站拉取文件，适用于"新建下载任务"弹窗这种用户直接粘贴直链的场景。
9.3 Canvas 折线图绘制
/** 绘制近 8 周模板下载量趋势折线图（网格 + 渐变面积 + 连续折线 + 数据点 + 标签） */
drawLineChart() {
const ctx = this.lineCtx;
const w = 330; // 画布逻辑宽
const h = 190; // 画布逻辑高
const padL = 34; // 左边距（刻度区）
const padR = 16; // 右边距
const padT = 26; // 顶边距（数值标签区）
const padB = 30; // 底边距（周标签区）
const max = TREND_MAX;
const stepX = (w - padL - padR) / (WEEK_TREND.length - 1);
ctx.clearRect(0, 0, w, h);
// 背景网格：4 条横向参考线 + 左侧纵轴刻度
for (let i = 0; i <= 4; i++) {
const gy = padT + (h - padT - padB) * i / 4;
ctx.beginPath();
ctx.moveTo(padL, gy);
ctx.lineTo(w - padR, gy);
ctx.strokeStyle = COLORS.line;
ctx.lineWidth = 1;
ctx.stroke();
ctx.fillStyle = COLORS.text3;
ctx.font = '9px sans-serif';
ctx.textAlign = 'right';
ctx.fillText((max - max * i / 4).toFixed(0), padL - 6, gy + 3);
}
// 渐变面积填充（createLinearGradient，呼吸联动顶部透明度）
const grad = ctx.createLinearGradient(0, padT, 0, h - padB);
grad.addColorStop(0, this.breath ? COLORS.gradTop : COLORS.gradTopDim);
grad.addColorStop(1, COLORS.gradBottom);
ctx.beginPath();
ctx.moveTo(padL, h - padB);
for (let i = 0; i < WEEK_TREND.length; i++) {
const px = padL + i * stepX;
const py = h - padB - (WEEK_TREND[i].val / max) * (h - padT - padB);
ctx.lineTo(px, py);
}
ctx.lineTo(w - padR, h - padB);
ctx.closePath();
ctx.fillStyle = grad;
ctx.fill();
// 连续折线（moveTo 起点 + lineTo 连线，呼吸联动线宽）
ctx.beginPath();
for (let i = 0; i < WEEK_TREND.length; i++) {
const px = padL + i * stepX;
const py = h - padB - (WEEK_TREND[i].val / max) * (h - padT - padB);
if (i === 0) {
ctx.moveTo(px, py);
} else {
ctx.lineTo(px, py);
}
}
ctx.strokeStyle = COLORS.blue;
ctx.lineWidth = this.breath ? 2.5 : 2;
ctx.stroke();
// 数据点圆点 + 顶部数值标签 + 底部周标签（末点橙色高亮）
for (let i = 0; i < WEEK_TREND.length; i++) {
const px = padL + i * stepX;
const py = h - padB - (WEEK_TREND[i].val / max) * (h - padT - padB);
ctx.beginPath();
ctx.arc(px, py, this.breath ? 3.6 : 2.8, 0, Math.PI * 2);
ctx.fillStyle = COLORS.card;
ctx.fill();
ctx.strokeStyle = COLORS.blue;
ctx.lineWidth = 1.5;
ctx.stroke();
ctx.fillStyle = i === WEEK_TREND.length - 1 ? COLORS.orange : COLORS.sub;
ctx.font = '9px sans-serif';
ctx.textAlign = 'center';
ctx.fillText(WEEK_TREND[i].val.toFixed(1), px, py - 9);
ctx.fillStyle = COLORS.text3;
ctx.fillText(WEEK_TREND[i].label, px, h - padB + 15);
}
}
drawLineChart() 方法是 Canvas 折线图的完整绘制实现，它通过 CanvasRenderingContext2D 的系列 API，绘制了背景网格、渐变面积、连续折线、数据点、数值标签、周标签六个层次。
首先定义画布的布局参数：w=330（逻辑宽）、h=190（逻辑高）、padL=34（左边距，留给纵轴刻度）、padR=16（右边距）、padT=26（顶边距，留给数值标签）、padB=30（底边距，留给周标签）。stepX 是相邻数据点的水平间距，通过 (w - padL - padR) / (WEEK_TREND.length - 1) 计算，保证 8 个数据点均匀分布在绘图区内。clearRect(0, 0, w, h) 清空画布，避免上次绘制的内容残留。
背景网格部分通过 for 循环绘制 4 条横向参考线（i 从 0 到 4，共 5 个位置但最顶和最底各一条），gy 是每条线的纵坐标，通过 padT + (h - padT - padB) * i / 4 计算，使 4 条线均匀分布在绘图区内。每条线用 moveTo + lineTo + stroke 绘制，颜色用极浅分割线色 COLORS.line。同时在每个网格线左侧用 fillText 标注纵轴刻度值，刻度通过 (max - max * i / 4).toFixed(0) 计算，从顶部的 20（万次）到底部的 0，等间距递减。
渐变面积填充部分通过 createLinearGradient(0, padT, 0, h - padB) 创建从绘图区顶部到底部的垂直渐变。渐变顶部颜色通过 this.breath ? COLORS.gradTop : COLORS.gradTopDim 二选一，实现呼吸动画的明暗变化；渐变底部用 COLORS.gradBottom（接近透明）。然后通过 moveTo 起点到底部、lineTo 遍历所有数据点、lineTo 终点到底部、closePath 闭合路径，形成一个多边形区域，用 fill 填充渐变色。这个渐变面积使折线下方有了"重量感"，提升了图表的视觉层次。
连续折线部分通过 moveTo 起点 + lineTo 连线绘制主折线。注意第一个点用 moveTo（移动画笔不画线），后续点用 lineTo（连线到指定点），形成连续的折线。线宽通过 this.breath ? 2.5 : 2 二选一，实现呼吸动画的线宽变化。折线颜色用商务蓝 COLORS.blue，与渐变面积同色系，视觉协调。
数据点圆点部分通过 arc 绘制每个数据点的圆点，半径通过 this.breath ? 3.6 : 2.8 二选一，实现呼吸动画的点大小变化。圆点填充色用卡片白 COLORS.card，描边用商务蓝，形成"空心圆点"效果，使数据点在折线上清晰可辨。数值标签用 fillText 绘制在点上方 9 像素处，最后一个点（最新一周）用活力橙 COLORS.orange 高亮，其余用中灰副文本色 COLORS.sub，使最新数据成为视觉焦点。周标签用 fillText 绘制在绘图区底部下方 15 像素处，用浅灰弱文本色 COLORS.text3。
9.4 记录操作方法
/** 打开编辑备注弹窗（回填当前记录备注） */
openEditRecord(idx: number) {
this.editIdx = idx;
this.editNote = this.downloadRecords[idx].note;
this.editModal = true;
}
/** 保存新建下载任务（空 URL 兜底默认演示直链，触发 startDownload） */
saveDownload() {
const url = this.formUrl === '' ? 'https://dl.mobanpu.cn/ppt/Q3Review_v3.2_20260825.pptx' : this.formUrl;
this.triggerDownload(url);
this.formUrl = '';
this.formNote = '';
this.addModal = false;
}
/** 保存编辑备注（整体刷新数组引用以刷新列表） */
updateRecord() {
if (this.editIdx >= 0 && this.editIdx < this.downloadRecords.length) {
if (this.editNote !== '') {
this.downloadRecords[this.editIdx].note = this.editNote;
}
this.downloadRecords = this.downloadRecords.slice();
}
this.editModal = false;
}
/** 删除下载记录（确认弹窗回调） */
delRecord() {
if (this.delIdx >= 0 && this.delIdx < this.downloadRecords.length) {
this.downloadRecords.splice(this.delIdx, 1);
}
this.delModal = false;
}
openEditRecord(idx) 方法处理"改"按钮的点击，打开编辑备注弹窗。它先将 editIdx 设置为目标记录索引，再从该记录读取 note 字段回填到 editNote（使弹窗的 TextInput 显示当前备注），最后将 editModal 置为 true 显示弹窗。这种"先回填再显示"的顺序，确保弹窗出现时输入框已有内容。
saveDownload() 方法处理新建下载任务弹窗的"开始下载"按钮。它有一个兜底逻辑：当用户未填写 URL（formUrl 为空）时，使用一个默认演示直链 https://dl.mobanpu.cn/ppt/Q3Review_v3.2_20260825.pptx，避免用户因为不知道填什么而无法体验下载功能。然后调用 triggerDownload(url) 发起下载，清空表单字段，关闭弹窗。
updateRecord() 方法处理编辑备注弹窗的"保存"按钮。它先做边界检查（editIdx 在合法范围内），再做空值检查（editNote 非空才更新），然后修改目标记录的 note 字段。关键的一步是 this.downloadRecords = this.downloadRecords.slice()——通过 slice() 创建数组的新引用，触发 ArkUI 的响应式刷新机制。因为 @Observed 类的属性修改虽然能被追踪，但 ForEach 列表的整体刷新需要数组引用变更才能触发，这是 ArkUI 响应式系统的一个关键技巧。
delRecord() 方法处理删除确认弹窗的"删除"按钮。它先做边界检查，再通过 splice(this.delIdx, 1) 从数组中移除目标记录，最后关闭弹窗。splice 会直接修改原数组并触发响应式刷新，不需要像 updateRecord 那样额外 slice()，因为 splice 本身已经改变了数组的长度与结构，框架能感知到。
9.5 生命周期方法
/** 生命周期：绑定下载代理 + 启动呼吸动画定时器（联动 Canvas 重绘） */
aboutToAppear() {
this.setupDownloadDelegate();
this.timer = setInterval(() => {
this.breath = !this.breath;
if (this.canvasReady) {
this.drawLineChart();
}
}, 1000);
}
/** 生命周期：销毁时清理定时器 */
aboutToDisappear() {
clearInterval(this.timer);
}
aboutToAppear() 是组件即将出现时触发的生命周期回调。它完成两件关键工作：第一是调用 setupDownloadDelegate() 注册下载代理，确保组件出现后 Web 组件加载的网页触发的下载能进入回调；第二是启动呼吸动画定时器 setInterval(() => {...}, 1000)，每秒翻转 breath 布尔值，并判断 canvasReady 为 true 时调用 drawLineChart() 重绘折线图，实现呼吸动画联动 Canvas 重绘。
aboutToDisappear() 是组件即将消失时触发的生命周期回调。它调用 clearInterval(this.timer) 清理定时器，避免组件销毁后定时器仍在运行导致的内存泄漏与空指针异常。这种"在 aboutToAppear 启动、在 aboutToDisappear 清理"的对称设计，是 ArkUI 生命周期管理的标准范式。
十、build 主构建
/** 页面主构建：Stack 包裹主内容与三层弹窗 */
build() {
Stack() {
Column() {
this.headerMain()
Divider().strokeWidth(1).color(COLORS.line)
Scroll() {
Column() {
if (this.currentTab === 0) {
this.tabTpl()
} else if (this.currentTab === 1) {
this.tabWeb()
} else if (this.currentTab === 2) {
this.tabDownload()
} else {
this.tabMine()
}
}
.padding({ left: 14, right: 14, top: 12, bottom: 12 })
}
.layoutWeight(1)
.scrollBar(BarState.Off)
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;
})
}
}
.width('100%')
.height('100%')
.backgroundColor(COLORS.bg)
}
build() 是组件的主构建方法，它定义了页面的整体结构。最外层是 Stack，它允许子元素叠放，这是弹窗系统的基石——主内容在底层，弹窗在上层。Stack 内首先是 Column，纵向排列头部、分割线、可滚动内容区、底部导航。
内容区用 Scroll 包裹，使内容超出屏幕时可纵向滚动。Scroll 内是 Column，根据 currentTab 的值通过 if-else if-else 条件分支渲染对应 Tab 的 Builder 函数。这种基于状态的条件分支是 ArkUI 实现 Tab 切换的经典模式，相比 Tabs 组件，它更轻量、更可控，适合内容区不需要左右滑动切换的场景。scrollBar(BarState.Off) 隐藏滚动条，保持界面简洁。
Stack 内除了主内容 Column，还有三个条件渲染的弹窗：addModal 为 true 时渲染 panelAdd，editModal 为 true 时渲染 panelEdit，delModal 为 true 时渲染 panelDel。每个弹窗接收一个 onClose 回调函数（将对应开关置为 false），实现点击遮罩或取消按钮时关闭弹窗。由于 Stack 的后入元素叠在上层，弹窗会覆盖在主内容之上，形成全屏弹窗效果。backgroundColor(COLORS.bg) 设置页面底色为暖米白。
十一、Builder 函数群：头部
/** 头部：商务蓝渐变 Banner（品牌 slogan + 本周上新数）+ 搜索条 + 场景 chips */
@Builder
headerMain() {
Column({ space: 12 }) {
// 渐变 Banner
Column({ space: 6 }) {
Row() {
Text('📋 模板铺').fontSize(17).fontColor('#FFFFFF').fontWeight(FontWeight.Bold)
Column().layoutWeight(1)
Text('本周上新 128 套').fontSize(9).fontColor('rgba(255,255,255,0.85)')
}
.width('100%')
Text('好模板 · 铺就每一次高质量汇报').fontSize(11).fontColor('rgba(255,255,255,0.95)')
Text('PPT / Word / Excel 全格式 · 每周五批量更新').fontSize(9).fontColor('rgba(255,255,255,0.68)')
}
.width('100%')
.padding(14)
.borderRadius(14)
.linearGradient({ angle: 120, colors: [[COLORS.blueD, 0], [COLORS.blue, 0.6], [COLORS.orange, 1]] })
// 搜索条 + 新建任务按钮
Row({ space: 8 }) {
Row({ space: 6 }) {
Text('🔍').fontSize(12)
Text('搜索模板 / 粘贴下载链接').fontSize(10).fontColor(COLORS.text3)
}
.layoutWeight(1).height(34).padding({ left: 10, right: 10 })
.backgroundColor(COLORS.chip).borderRadius(17)
.onClick(() => {
this.currentTab = 1;
})
Text('+ 新建任务').fontSize(10).fontColor('#FFFFFF')
.padding({ left: 12, right: 12, top: 9, bottom: 9 })
.backgroundColor(COLORS.blue).borderRadius(17)
.onClick(() => {
this.addModal = true;
})
}
.width('100%')
// 场景 chips 横滑
Scroll() {
Row({ space: 8 }) {
ForEach(CATE_TAGS, (tag: string, idx: number) => {
Text(tag).fontSize(10)
.fontColor(this.cateIdx === idx ? '#FFFFFF' : COLORS.sub)
.padding({ left: 12, right: 12, top: 6, bottom: 6 })
.backgroundColor(this.cateIdx === idx ? COLORS.blue : COLORS.chip)
.borderRadius(13)
.onClick(() => {
this.cateIdx = idx;
})
}, (tag: string) => tag)
}
}
.scrollable(ScrollDirection.Horizontal)
.scrollBar(BarState.Off)
.width('100%')
}
.width('100%')
.padding({ left: 14, right: 14, top: 12, bottom: 10 })
.backgroundColor(COLORS.bg)
}
headerMain() Builder 构建了页面的头部区域，包含渐变 Banner、搜索条 + 新建任务按钮、场景 chips 横滑三个部分。
渐变 Banner 使用 linearGradient({ angle: 120, colors: [[COLORS.blueD, 0], [COLORS.blue, 0.6], [COLORS.orange, 1]] }) 设置 120 度斜向渐变，从深商务蓝（0% 位置）过渡到商务蓝（60% 位置），最后到活力橙（100% 位置），形成商务蓝主调、活力橙收尾的品牌色彩节奏。Banner 内顶部一行是品牌名"📋 模板铺"（粗体白色）与"本周上新 128 套"（小字半透明白色）的左右布局，中间用 Column().layoutWeight(1) 弹性占位推开。下方两行是品牌 slogan"好模板 · 铺就每一次高质量汇报"与格式说明"PPT / Word / Excel 全格式 · 每周五批量更新"，透明度逐行递减（0.95 → 0.68），形成层次感。
搜索条与新建任务按钮并排在 Row 内。搜索条是 Row 包裹的"🔍 图标 + 提示文案"，点击后跳转到网页 Tab（currentTab = 1），暗示用户可以在网页 Tab 粘贴下载链接。新建任务按钮是商务蓝背景的圆角胶囊按钮"+ 新建任务"，点击后打开新建下载任务弹窗（addModal = true）。
场景 chips 横滑区用 Scroll 包裹 Row，scrollable(ScrollDirection.Horizontal) 开启横向滚动，scrollBar(BarState.Off) 隐藏滚动条。ForEach 遍历 CATE_TAGS 渲染八个 chip，选中态（cateIdx === idx）用商务蓝背景 + 白色文字，未选中态用浅米色背景 + 中灰文字，通过 onClick 点击切换 cateIdx。chip 的 borderRadius(13) 与 padding 使其呈现胶囊形态。
十二、Builder 函数群：模板 Tab
12.1 模板 Tab 主结构
/** 模板 Tab：精选合集卡 + 大编号热门模板榜 + Canvas 折线图卡 */
@Builder
tabTpl() {
Column({ space: 12 }) {
this.recBanner()
this.rankCard()
this.chartCard()
}
.width('100%')
}
tabTpl() Builder 构建模板 Tab 的主结构，纵向排列三个卡片：精选合集卡 recBanner、热门模板榜 rankCard、Canvas 折线图卡 chartCard。三卡之间用 space: 12 的间距分隔，整体宽度占满。这种"精选 + 榜单 + 图表"的三段式结构，从"编辑推荐"到"用户热度"再到"趋势可视化"，层层递进地呈现模板内容，信息密度高且层次清晰。
12.2 精选模板合集卡
/** 精选模板合集卡（3 条：模板名 + 格式 PPT/Word/Excel + 适用场景） */
@Builder
recBanner() {
Column({ space: 10 }) {
Row() {
Text('🔥 精选模板').fontSize(13).fontColor(COLORS.title).fontWeight(FontWeight.Bold)
Column().layoutWeight(1)
Text('每周五上新').fontSize(9).fontColor(COLORS.text3)
}
.width('100%')
Text('📦 ' + SERIES_NAME + ' · 收录 3 套核心模板').fontSize(9).fontColor(COLORS.blue)
ForEach(this.seriesList, (rec: SeriesItem) => {
Row({ space: 10 }) {
Text(rec.icon).fontSize(24)
Column({ space: 3 }) {
Text(rec.name).fontSize(12).fontColor(COLORS.title).fontWeight(FontWeight.Bold)
Text(rec.fmt + ' · ' + rec.scene).fontSize(9).fontColor(COLORS.sub)
.maxLines(1).textOverflow({ overflow: TextOverflow.Ellipsis })
}
.layoutWeight(1).alignItems(HorizontalAlign.Start)
Text('获取').fontSize(10).fontColor(COLORS.blue)
.padding({ left: 12, right: 12, top: 6, bottom: 6 })
.borderRadius(12)
.border({ width: 1, color: COLORS.blue })
.onClick(() => {
this.currentTab = 1;
})
}
.width('100%')
.padding(11)
.borderRadius(11)
.backgroundColor(COLORS.chip)
}, (rec: SeriesItem) => rec.name)
}
.width('100%').padding(14).backgroundColor(COLORS.card).borderRadius(12)
}
recBanner() Builder 构建精选模板合集卡。卡片头部是"🔥 精选模板"标题与"每周五上新"辅助文案的左右布局，下方一行"📦 年终汇报全家桶 · 收录 3 套核心模板"用商务蓝小字标注合集名称与规模。
ForEach 遍历 seriesList 渲染三条精选模板。每条记录是一个 Row，左侧是格式徽标 emoji（24 号字大显示），中间是 Column 包裹的模板名（粗体）与格式 + 场景（单行省略号），右侧是"获取"按钮（商务蓝描边胶囊按钮，点击跳转到网页 Tab）。每条记录用浅米色背景 + 11 号圆角，形成独立的卡片单元。maxLines(1) + textOverflow({ overflow: TextOverflow.Ellipsis }) 确保格式与场景文案超长时单行省略，避免撑乱布局。
12.3 大编号热门模板榜
/** 大编号热门模板榜（8 条：名次 + 模板 + 格式 + 周下载 + 趋势） */
@Builder
rankCard() {
Column({ space: 10 }) {
Row() {
Text('🏆 本周热门模板榜').fontSize(13).fontColor(COLORS.title).fontWeight(FontWeight.Bold)
Column().layoutWeight(1)
Text('按下载量').fontSize(9).fontColor(COLORS.text3)
}
.width('100%')
ForEach(this.tplList, (t: TplItem, idx: number) => {
Row({ space: 10 }) {
Text(t.rank).fontSize(20).fontWeight(FontWeight.Bold)
.fontColor(idx < 3 ? COLORS.orange : COLORS.text3)
.width(30)
Column({ space: 3 }) {
Text(t.name).fontSize(12).fontColor(COLORS.title).fontWeight(FontWeight.Bold)
Text(t.author + ' · ' + t.fmt).fontSize(9).fontColor(COLORS.sub)
}
.layoutWeight(1).alignItems(HorizontalAlign.Start)
Column({ space: 2 }) {
Text('周下载 ' + t.heat).fontSize(9).fontColor(fmtColor(t.fmt)).fontWeight(FontWeight.Bold)
Text(trendIcon(t.trend)).fontSize(9).fontColor(trendColor(t.trend))
}
.alignItems(HorizontalAlign.End)
}
.width('100%')
.padding({ top: 8, bottom: 8 })
.borderRadius(10)
.backgroundColor(idx % 2 === 0 ? COLORS.chip : COLORS.card)
}, (t: TplItem) => t.rank)
}
.width('100%').padding(14).backgroundColor(COLORS.card).borderRadius(12)
}
rankCard() Builder 构建大编号热门模板榜。ForEach 遍历 tplList 渲染八条榜单记录。每条记录的左侧是大号名次（20 号字粗体），前三名用活力橙 COLORS.orange 高亮，四名及以后用浅灰弱文本色，形成金银铜的视觉差异。中间是 Column 包裹的模板名（粗体）与出品方 + 格式。右侧是 Column 包裹的周下载量（用 fmtColor(t.fmt) 映射格式颜色）与趋势文案（用 trendIcon(t.trend) + trendColor(t.trend) 映射）。
记录的背景色通过 idx % 2 === 0 ? COLORS.chip : COLORS.card 实现斑马纹效果——偶数索引用浅米色，奇数索引用纯白色，使长列表更易阅读。这种斑马纹设计在数据密集型列表中是常用的可读性优化手段。
12.4 Canvas 折线图卡
/** 图表卡：Canvas 近 8 周模板下载量趋势折线图（呼吸动画联动重绘） */
@Builder
chartCard() {
Column({ space: 10 }) {
Row() {
Text('📈 近 8 周下载趋势').fontSize(13).fontColor(COLORS.title).fontWeight(FontWeight.Bold)
Column().layoutWeight(1)
Text('Canvas 绘制').fontSize(9).fontColor(COLORS.text3)
}
.width('100%')
Canvas(this.lineCtx)
.width('100%')
.height(190)
.onReady(() => {
this.canvasReady = true;
this.drawLineChart();
})
Row() {
Text('单位：万次 · 周维度统计').fontSize(9).fontColor(COLORS.sub)
Column().layoutWeight(1)
Text('环比 +16.7%').fontSize(9).fontColor(COLORS.green)
}
.width('100%')
}
.width('100%').padding(14).backgroundColor(COLORS.card).borderRadius(12)
}
chartCard() Builder 构建 Canvas 折线图卡。卡片头部是"📈 近 8 周下载趋势"标题与"Canvas 绘制"辅助文案。中间是 Canvas(this.lineCtx) 组件，绑定 lineCtx 上下文，宽度占满、高度 190。onReady 回调在 Canvas 就绪时触发，将 canvasReady 置为 true（使呼吸定时器知道可以重绘了），并立即调用 drawLineChart() 绘制初始图表。底部一行是"单位：万次 · 周维度统计"说明与"环比 +16.7%"正向指标（增长绿色）。
onReady 是 Canvas 组件的关键生命周期回调。Canvas 组件的 2D 上下文在组件挂载到组件树并完成布局后才能就绪，在此之前调用 drawLineChart() 会因上下文未初始化而失败。因此 onReady 是触发首次绘制的正确时机，而 canvasReady 标志则使后续的呼吸定时器重绘有了安全前提。
十三、Builder 函数群：网页 Tab
/** 网页 Tab：地址栏 + 快捷站点 + Web 组件 + 主动下载（ArkWeb 特性页） */
@Builder
tabWeb() {
Column({ space: 10 }) {
// 地址栏：输入 + 前往（urlInput/webUrl 双状态分离）
Row({ space: 8 }) {
TextInput({ text: this.urlInput, placeholder: '输入网址，如 docs.qq.com' })
.layoutWeight(1).height(38).fontSize(11).fontColor(COLORS.title)
.backgroundColor(COLORS.chip).borderRadius(10)
.onChange((value: string) => {
this.urlInput = value;
})
Text('前往').fontSize(11).fontColor('#FFFFFF')
.padding({ left: 14, right: 14, top: 10, bottom: 10 })
.backgroundColor(COLORS.blue).borderRadius(10)
.onClick(() => {
this.loadUrl();
})
}
.width('100%')
// 快捷站点横滑（办公协同类站点，点击即加载）
Scroll() {
Row({ space: 8 }) {
ForEach(QUICK_SITES, (site: string) => {
Row({ space: 5 }) {
Text('🔗').fontSize(10)
Text(siteHost(site)).fontSize(9).fontColor(COLORS.sub)
.maxLines(1).textOverflow({ overflow: TextOverflow.Ellipsis })
}
.padding({ left: 10, right: 10, top: 6, bottom: 6 })
.backgroundColor(this.webUrl === site ? COLORS.blue : COLORS.chip)
.borderRadius(12)
.onClick(() => {
this.urlInput = site;
this.webUrl = site;
})
}, (site: string) => site)
}
}
.scrollable(ScrollDirection.Horizontal)
.scrollBar(BarState.Off)
.width('100%')
// Web 组件本体：网页内点击下载链接自动进入 delegate 回调
Web({ src: this.webUrl, controller: this.webController })
.layoutWeight(1)
.width('100%')
.borderRadius(10)
.backgroundColor(COLORS.chip)
// 主动下载演示行（应用侧 startDownload 触发）
Column({ space: 8 }) {
Row() {
Text('🧪 应用侧主动下载演示').fontSize(12).fontColor(COLORS.title).fontWeight(FontWeight.Bold)
Column().layoutWeight(1)
Text(this.dlState).fontSize(9).fontColor(this.dlState === '下载完成' ? COLORS.green : COLORS.blue)
}
.width('100%')
Row({ space: 10 }) {
Text('下载 Q3 复盘 PPT 模板').fontSize(10).fontColor('#FFFFFF')
.layoutWeight(1).textAlign(TextAlign.Center)
.padding({ top: 9, bottom: 9 }).backgroundColor(COLORS.blue).borderRadius(9)
.onClick(() => {
this.triggerDownload('https://dl.mobanpu.cn/ppt/Q3Review_v3.2_20260825.pptx');
})
Text('下载 2026 合同 Word 包').fontSize(10).fontColor(COLORS.orange)
.layoutWeight(1).textAlign(TextAlign.Center)
.padding({ top: 9, bottom: 9 })
.borderRadius(9).border({ width: 1, color: COLORS.orange })
.onClick(() => {
this.triggerDownload('https://cdn.huazhang.cn/doc/Contract2026_v3.4.docx');
})
}
.width('100%')
Text('提示：网页内点击下载链接同样会触发 WebDownloadDelegate 四回调').fontSize(8).fontColor(COLORS.text3)
}
.width('100%').padding(12).backgroundColor(COLORS.card).borderRadius(12)
}
.width('100%')
.height('100%')
}
tabWeb() Builder 构建网页 Tab，这是 ArkWeb 特性页，包含地址栏、快捷站点横滑、Web 组件本体、主动下载演示四个部分。
地址栏是 TextInput + "前往"按钮的组合。TextInput 的 text 绑定 urlInput，onChange 回调实时更新 urlInput（但不触发加载）。"前往"按钮点击调用 loadUrl()，该方法校验协议前缀后同步更新 urlInput 与 webUrl，触发 Web 组件加载。这种"敲字不等于加载"的双状态分离设计，避免了输入过程中的无效加载。
快捷站点横滑区用 Scroll + Row 横向排列四个站点卡片。每个卡片显示"🔗 图标 + 域名"（通过 siteHost(site) 去掉协议前缀）。当前加载的站点（webUrl === site）用商务蓝背景 + 白色文字高亮，其余用浅米色背景。点击卡片直接同步 urlInput 与 webUrl 为该站点，触发 Web 组件加载。
Web 组件本体 Web({ src: this.webUrl, controller: this.webController }) 是 ArkWeb 的核心组件。src 绑定 webUrl，controller 绑定 webController。当 webUrl 变化时，Web 组件自动加载新 URL。layoutWeight(1) 使 Web 组件弹性占满剩余高度，borderRadius(10) 圆角化，backgroundColor(COLORS.chip) 设置加载前的占位底色。关键点是：由于 aboutToAppear 中已通过 setDownloadDelegate 将下载代理绑定到 webController，网页内任何点击下载链接的行为都会自动进入下载代理的四个回调，无需在此处额外处理。
主动下载演示行是应用侧 startDownload 的触发入口。它包含两个按钮：蓝色实心按钮"下载 Q3 复盘 PPT 模板"与橙色描边按钮"下载 2026 合同 Word 包"，分别点击调用 triggerDownload 传入不同的直链 URL。状态文案 dlState 实时显示在右上角，下载完成时用增长绿，其他状态用商务蓝。底部提示文案"网页内点击下载链接同样会触发 WebDownloadDelegate 四回调"明确告知用户：无论是网页内点击还是应用侧主动发起，下载审计逻辑统一收口。
十四、Builder 函数群：下载 Tab
/** 下载 Tab：进行中任务卡 + 代码预览卡 + 完成记录双 URL 溯源列表 */
@Builder
tabDownload() {
Column({ space: 12 }) {
// 进行中任务卡（进度条 + 状态）
Column({ space: 10 }) {
Row() {
Text('⬇ 下载任务').fontSize(13).fontColor(COLORS.title).fontWeight(FontWeight.Bold)
Column().layoutWeight(1)
Text(this.dlState).fontSize(9).fontColor(COLORS.blue)
}
.width('100%')
Text(this.dlName === '' ? '暂无进行中任务（可在网页 Tab 触发）' : this.dlName)
.fontSize(10).fontColor(COLORS.sub)
.maxLines(1).textOverflow({ overflow: TextOverflow.Ellipsis })
Progress({ value: this.dlPercent, total: 100, type: ProgressType.Linear })
.width('100%').height(6)
.color(COLORS.blue).backgroundColor(COLORS.chip)
Row() {
Text('进度 ' + this.dlPercent + '%').fontSize(9).fontColor(COLORS.sub)
Column().layoutWeight(1)
Text('保存至沙箱 filesDir').fontSize(9).fontColor(COLORS.text3)
}
.width('100%')
}
.width('100%').padding(14).backgroundColor(COLORS.card).borderRadius(12)
// onDownloadFinish 代码预览卡（体现 6.1.1 新增双接口）
Column({ space: 6 }) {
Text('⌨️ onDownloadFinish 回调（HarmonyOS 6.1.1 新增）').fontSize(12)
.fontColor(COLORS.title).fontWeight(FontWeight.Bold)
Column({ space: 4 }) {
Text('this.downloadDelegate.onDownloadFinish(').fontSize(9).fontFamily('monospace').fontColor('rgba(222,230,244,0.72)')
Text(' (item: webview.WebDownloadItem) => {').fontSize(9).fontFamily('monospace').fontColor('rgba(222,230,244,0.72)')
Text(' const original = item.getOriginalUrl();').fontSize(9).fontFamily('monospace').fontColor('#7EC2FF')
Text(' const referrer = item.getReferrerUrl();').fontSize(9).fontFamily('monospace').fontColor('#FFC95E')
Text(' });').fontSize(9).fontFamily('monospace').fontColor('rgba(222,230,244,0.72)')
}
.width('100%').padding(10).borderRadius(8).backgroundColor(COLORS.codeBg)
Text('原始 URL 追踪模板直链来源，引用页 URL 记录触发下载的页面').fontSize(8).fontColor(COLORS.text3)
}
.width('100%').padding(14).backgroundColor(COLORS.card).borderRadius(12)
// 已完成记录列表（每条含双 URL 溯源信息）
Column({ space: 10 }) {
Row() {
Text('🗂 历史下载记录').fontSize(13).fontColor(COLORS.title).fontWeight(FontWeight.Bold)
Column().layoutWeight(1)
Text(this.downloadRecords.length + ' 条').fontSize(9).fontColor(COLORS.text3)
}
.width('100%')
ForEach(this.downloadRecords, (rec: DownloadRecord, idx: number) => {
Column({ space: 6 }) {
Row({ space: 8 }) {
Text('📦').fontSize(14)
Column({ space: 2 }) {
Text(rec.fileName).fontSize(11).fontColor(COLORS.title).fontWeight(FontWeight.Bold)
.maxLines(1).textOverflow({ overflow: TextOverflow.Ellipsis })
Text(rec.fileSize + ' · ' + rec.finishTime + ' · ' + rec.note).fontSize(9).fontColor(COLORS.sub)
.maxLines(1).textOverflow({ overflow: TextOverflow.Ellipsis })
}
.layoutWeight(1).alignItems(HorizontalAlign.Start)
Text('改').fontSize(9).fontColor(COLORS.sub)
.padding({ left: 8, right: 8, top: 4, bottom: 4 })
.backgroundColor(COLORS.chip).borderRadius(8)
.onClick(() => {
this.openEditRecord(idx);
})
Text('删').fontSize(9).fontColor(COLORS.red)
.padding({ left: 8, right: 8, top: 4, bottom: 4 })
.backgroundColor(COLORS.chip).borderRadius(8)
.onClick(() => {
this.delIdx = idx;
this.delModal = true;
})
}
.width('100%')
// ★ 原始 URL 溯源行（getOriginalUrl 结果）
Row({ space: 6 }) {
Text('🔗').fontSize(9)
Text(rec.originalUrl).fontSize(8).fontFamily('monospace').fontColor(COLORS.blue)
.layoutWeight(1).maxLines(1).textOverflow({ overflow: TextOverflow.Ellipsis })
}
.width('100%')
// ★ 引用页 URL 溯源行（getReferrerUrl 结果）
Row({ space: 6 }) {
Text('📄').fontSize(9)
Text(rec.referrerUrl).fontSize(8).fontFamily('monospace').fontColor(COLORS.orange)
.layoutWeight(1).maxLines(1).textOverflow({ overflow: TextOverflow.Ellipsis })
}
.width('100%')
}
.width('100%').padding(11).borderRadius(11).backgroundColor(COLORS.chip)
}, (rec: DownloadRecord) => rec.fileName)
}
.width('100%').padding(14).backgroundColor(COLORS.card).borderRadius(12)
}
.width('100%')
}
tabDownload() Builder 构建下载 Tab，这是双 URL 溯源能力的展示核心，包含进行中任务卡、代码预览卡、已完成记录双 URL 溯源列表三个部分。
进行中任务卡显示当前下载任务的状态。顶部是"⬇ 下载任务"标题与状态文案 dlState（商务蓝）的左右布局。中间是文件名（无任务时显示"暂无进行中任务（可在网页 Tab 触发）"提示文案），用单行省略号避免长文件名撑乱布局。下方是 Progress 线性进度条，value 绑定 dlPercent，total 为 100，color 为商务蓝，backgroundColor 为浅米色，形成清晰的进度对比。底部是"进度 X%"与"保存至沙箱 filesDir"的左右布局，使用户明确知道文件保存位置。
代码预览卡是一个特色设计——它直接在界面上展示 onDownloadFinish 回调的源代码，用深藏蓝代码预览底色 COLORS.codeBg 模拟代码编辑器观感。代码用 fontFamily('monospace') 等宽字体显示，关键字 getOriginalUrl 用蓝色 #7EC2FF 高亮，getReferrerUrl 用橙色 #FFC95E 高亮，其他代码用半透明灰白色 rgba(222,230,244,0.72)。这种"代码即文档"的设计，使用户在查看下载记录的同时，能直观理解双 URL 溯源的技术实现，是一个兼具功能与教学价值的设计。
已完成记录列表是双 URL 溯源的核心展示区。ForEach 遍历 downloadRecords 渲染每条记录。每条记录是一个 Column，包含三行：第一行是文件信息行（📦 图标 + 文件名 + 大小/时间/备注 + "改"按钮 + "删"按钮），第二行是原始 URL 溯源行（🔗 图标 + 蓝色等宽字体 URL，单行省略），第三行是引用页 URL 溯源行（📄 图标 + 橙色等宽字体 URL，单行省略）。原始 URL 用商务蓝、引用页 URL 用活力橙，使两类 URL 一眼可辨。"改"按钮点击调用 openEditRecord(idx) 打开编辑弹窗，"删"按钮点击设置 delIdx 并打开删除确认弹窗。每条记录用浅米色背景 + 11 号圆角，形成独立的溯源卡片。
十五、Builder 函数群：我的 Tab
/** 我的 Tab：职场身份渐变大卡 + 下载统计行 + 功能清单行 */
@Builder
tabMine() {
Column({ space: 12 }) {
// 职场身份渐变大卡
Column({ space: 8 }) {
Row({ space: 12 }) {
Text('👔').fontSize(34)
Column({ space: 4 }) {
Text('效率达人 · 周正扬').fontSize(15).fontColor('#FFFFFF').fontWeight(FontWeight.Bold)
Text('市场部 · 高级策划专员').fontSize(9).fontColor('rgba(255,255,255,0.82)')
}
.layoutWeight(1).alignItems(HorizontalAlign.Start)
Text('效率 Lv.7').fontSize(10).fontColor('#FFFFFF')
.padding({ left: 10, right: 10, top: 5, bottom: 5 })
.borderRadius(10).backgroundColor('rgba(255,255,255,0.24)')
}
.width('100%')
Row({ space: 8 }) {
Column({ space: 2 }) {
Text('186').fontSize(15).fontColor('#FFFFFF').fontWeight(FontWeight.Bold)
Text('累计下载').fontSize(8).fontColor('rgba(255,255,255,0.72)')
}
.layoutWeight(1)
Column({ space: 2 }) {
Text('38').fontSize(15).fontColor('#FFFFFF').fontWeight(FontWeight.Bold)
Text('本月记录').fontSize(8).fontColor('rgba(255,255,255,0.72)')
}
.layoutWeight(1)
Column({ space: 2 }) {
Text('64').fontSize(15).fontColor('#FFFFFF').fontWeight(FontWeight.Bold)
Text('收藏模板').fontSize(8).fontColor('rgba(255,255,255,0.72)')
}
.layoutWeight(1)
Column({ space: 2 }) {
Text('6').fontSize(15).fontColor('#FFFFFF').fontWeight(FontWeight.Bold)
Text('上传模板').fontSize(8).fontColor('rgba(255,255,255,0.72)')
}
.layoutWeight(1)
}
.width('100%')
}
.width('100%').padding(16).borderRadius(14)
.linearGradient({ angle: 135, colors: [[COLORS.blueD, 0], [COLORS.blue, 0.55], [COLORS.orange, 1]] })
// 功能清单行
Column({ space: 0 }) {
ForEach(this.statList, (st: UserStat) => {
Row({ space: 10 }) {
Text(st.icon).fontSize(15)
Text(st.label).fontSize(11).fontColor(COLORS.title)
.layoutWeight(1)
Text(st.value).fontSize(9).fontColor(COLORS.text3)
if (st.arrow) {
Text('›').fontSize(14).fontColor(COLORS.text3)
}
}
.width('100%')
.padding({ top: 11, bottom: 11 })
.border({ width: { bottom: 1 }, color: COLORS.line })
.onClick(() => {
if (st.label === '下载历史') {
this.currentTab = 2;
}
})
}, (st: UserStat) => st.label)
}
.width('100%').padding({ left: 14, right: 14 }).backgroundColor(COLORS.card).borderRadius(12)
Text('模板铺 v6.1.1 · ArkWeb 双 URL 溯源版').fontSize(8).fontColor(COLORS.text3)
}
.width('100%')
}
tabMine() Builder 构建我的 Tab，包含职场身份渐变大卡与功能清单行两个部分。
职场身份渐变大卡使用 linearGradient({ angle: 135, colors: [[COLORS.blueD, 0], [COLORS.blue, 0.55], [COLORS.orange, 1]] }) 设置 135 度对角渐变，从深商务蓝（0%）过渡到商务蓝（55%），最后到活力橙（100%），比头部 Banner 的 120 度更斜，形成视觉差异。卡片顶部一行是 👔 emoji（34 号字大显示）+ 用户名/职位（白色文字）+ "效率 Lv.7"等级标签（半透明白色背景胶囊）。下方一行是四列统计数据（累计下载 186、本月记录 38、收藏模板 64、上传模板 6），每列用 layoutWeight(1) 等宽分布，数值用粗体白色，标签用半透明白色。这种渐变大卡设计使个人中心顶部具有强烈的品牌感与身份感。
功能清单行通过 ForEach 遍历 statList 渲染八行功能项。每行从左到右是：功能图标 emoji、功能名（弹性占满）、状态值、右箭头（if (st.arrow) 条件渲染）。行与行之间通过 border({ width: { bottom: 1 }, color: COLORS.line }) 设置底部分割线，形成清晰的行分隔。点击事件有条件判断：当 st.label === '下载历史' 时跳转到下载 Tab（currentTab = 2），使"下载历史"功能项成为从我的页快速进入下载溯源的入口。底部"模板铺 v6.1.1 · ArkWeb 双 URL 溯源版"版本号文案用最小字号 8，既标注版本又不抢视觉焦点。
十六、Builder 函数群：底部导航
/** 底部导航：4 Tab 单排（选中商务蓝高亮 + 图标放大） */
@Builder
tabBar() {
Row() {
ForEach(TAB_LIST, (t: TabMeta, idx: number) => {
Column({ space: 3 }) {
Text(t.icon).fontSize(this.currentTab === idx ? 20 : 17)
.opacity(this.currentTab === idx ? 1 : 0.65)
Text(t.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: 7, bottom: 7 })
.onClick(() => {
this.currentTab = idx;
})
}, (t: TabMeta) => t.label)
}
.width('100%')
.backgroundColor(COLORS.card)
.border({ width: { top: 1 }, color: COLORS.line })
}
tabBar() Builder 构建底部导航。Row 单排布局，四个 Tab 通过 ForEach 渲染，每个 Tab 用 layoutWeight(1) 等宽分布。选中态（currentTab === idx）通过多维度视觉差异体现：图标字号从 17 放大到 20、透明度从 0.65 提升到 1.0、标签文字从浅灰弱文本色变为商务蓝（COLORS.tabOn）、字重从常规变为粗体。这种多维度的状态反馈让用户对当前所在页面有明确的感知。
顶部用 border({ width: { top: 1 }, color: COLORS.line }) 仅设置上边框线，将导航栏与内容区视觉分隔。点击事件直接设置 currentTab 状态，触发主内容区的条件分支切换到对应 Tab 的 Builder 函数。这种简洁的 Tab 切换机制无需 Tabs 组件的复杂配置，适合内容区不需要滑动切换的场景。
十七、Builder 函数群：弹窗系统
17.1 全屏遮罩
/** 弹窗全屏遮罩（点击遮罩关闭弹窗） */
@Builder
modalOverlay(onClose: () => void) {
Stack() {
Column().width('100%').height('100%').backgroundColor(COLORS.mask)
}
.width('100%')
.height('100%')
.alignContent(Alignment.Center)
.onClick(() => onClose())
}
modalOverlay 是弹窗系统的通用遮罩组件。它接收一个 onClose 回调函数作为参数，点击遮罩区域时调用该回调关闭弹窗。遮罩使用 COLORS.mask（rgba(43,41,38,0.42)）半透明背景色，覆盖全屏。外层 Stack 设置 alignContent(Alignment.Center) 使后续叠加的弹窗面板自动居中显示。
这个设计体现了 Builder 函数的参数化能力——通过传入不同的回调函数，同一个遮罩组件可以服务于多个弹窗场景。这种"遮罩 + 面板"的组合模式是移动端弹窗的经典实现，遮罩负责点击外部关闭，面板负责具体业务交互。alignContent(Alignment.Center) 是关键，它使后续叠加的面板自动居中，无需面板自己计算居中位置。
17.2 新建下载任务弹窗
/** 新建下载任务弹窗面板（模板直链 + 备注） */
@Builder
panelAdd(onClose: () => void) {
Stack() {
this.modalOverlay(onClose)
Column({ space: 12 }) {
Text('新建下载任务').fontSize(15).fontColor(COLORS.title).fontWeight(FontWeight.Bold)
Column({ space: 6 }) {
Text('模板直链 URL').fontSize(9).fontColor(COLORS.sub)
TextInput({ text: this.formUrl, placeholder: 'https://dl.mobanpu.cn/ppt/xxx.pptx' })
.fontSize(11).fontColor(COLORS.title)
.backgroundColor(COLORS.chip).borderRadius(8)
.onChange((value: string) => {
this.formUrl = value;
})
}
.width('100%').alignItems(HorizontalAlign.Start)
Column({ space: 6 }) {
Text('备注（可选）').fontSize(9).fontColor(COLORS.sub)
TextInput({ text: this.formNote, placeholder: '如：年终汇报用 / 同事推荐' })
.fontSize(11).fontColor(COLORS.title)
.backgroundColor(COLORS.chip).borderRadius(8)
.onChange((value: string) => {
this.formNote = value;
})
}
.width('100%').alignItems(HorizontalAlign.Start)
Text('发起后经 startDownload 触发，完成回调记录双 URL').fontSize(8).fontColor(COLORS.text3)
Row({ space: 10 }) {
Text('取消').fontSize(12).fontColor(COLORS.sub)
.layoutWeight(1).textAlign(TextAlign.Center)
.padding({ top: 9, bottom: 9 }).backgroundColor(COLORS.chip).borderRadius(9)
.onClick(() => onClose())
Text('开始下载').fontSize(12).fontColor('#FFFFFF').fontWeight(FontWeight.Bold)
.layoutWeight(1).textAlign(TextAlign.Center)
.padding({ top: 9, bottom: 9 }).backgroundColor(COLORS.blue).borderRadius(9)
.onClick(() => {
this.saveDownload();
})
}
.width('100%')
}
.width('78%').padding(16).backgroundColor(COLORS.card).borderRadius(14)
}
.width('100%')
.height('100%')
.alignContent(Alignment.Center)
}
panelAdd 是新建下载任务弹窗面板。它在 Stack 内叠加 modalOverlay 遮罩与 Column 面板。面板宽度 78%，圆角 14，纯白卡片底色。面板内容包含标题"新建下载任务"、模板直链 URL 输入框（formUrl）、备注输入框（formNote）、技术提示文案"发起后经 startDownload 触发，完成回调记录双 URL"、取消与开始下载两个按钮。取消按钮点击调用 onClose 关闭弹窗，开始下载按钮点击调用 saveDownload() 执行下载逻辑。两个按钮用 layoutWeight(1) 等宽分布，取消用浅米色背景，开始下载用商务蓝背景 + 白色粗体文字，形成主次分明。
技术提示文案"发起后经 startDownload 触发，完成回调记录双 URL"是一个重要的用户教育设计——它明确告知用户，新建任务会通过 startDownload 触发，完成后会自动记录原始 URL 与引用页 URL，使用户对双 URL 溯源机制有直观认知。
17.3 编辑备注弹窗
/** 编辑备注弹窗面板（回填当前记录备注） */
@Builder
panelEdit(onClose: () => void) {
Stack() {
this.modalOverlay(onClose)
Column({ space: 12 }) {
Text('编辑模板备注').fontSize(15).fontColor(COLORS.title).fontWeight(FontWeight.Bold)
Column({ space: 6 }) {
Text('记录备注').fontSize(9).fontColor(COLORS.sub)
TextInput({ text: this.editNote, placeholder: '如：年终汇报用 / 限时免费' })
.fontSize(11).fontColor(COLORS.title)
.backgroundColor(COLORS.chip).borderRadius(8)
.onChange((value: string) => {
this.editNote = value;
})
}
.width('100%').alignItems(HorizontalAlign.Start)
Row({ space: 10 }) {
Text('取消').fontSize(12).fontColor(COLORS.sub)
.layoutWeight(1).textAlign(TextAlign.Center)
.padding({ top: 9, bottom: 9 }).backgroundColor(COLORS.chip).borderRadius(9)
.onClick(() => onClose())
Text('保存').fontSize(12).fontColor('#FFFFFF').fontWeight(FontWeight.Bold)
.layoutWeight(1).textAlign(TextAlign.Center)
.padding({ top: 9, bottom: 9 }).backgroundColor(COLORS.blue).borderRadius(9)
.onClick(() => {
this.updateRecord();
})
}
.width('100%')
}
.width('78%').padding(16).backgroundColor(COLORS.card).borderRadius(14)
}
.width('100%')
.height('100%')
.alignContent(Alignment.Center)
}
panelEdit 是编辑备注弹窗面板。结构与 panelAdd 类似，但只有一个输入框——记录备注（editNote）。关键点是 TextInput 的 text 绑定 editNote，而 editNote 在 openEditRecord(idx) 中已被回填为当前记录的备注值，因此弹窗出现时输入框已有内容，用户可以直接在原有备注基础上修改。保存按钮点击调用 updateRecord()，该方法通过 slice() 创建数组新引用确保 ForEach 列表刷新。
17.4 删除确认弹窗
/** 删除记录确认弹窗面板 */
@Builder
panelDel(onClose: () => void) {
Stack() {
this.modalOverlay(onClose)
Column({ space: 14 }) {
Text('🗑').fontSize(30)
Text('删除这条下载记录？').fontSize(14).fontColor(COLORS.title).fontWeight(FontWeight.Bold)
Text('仅移除记录，不影响已保存到沙箱的文件').fontSize(9).fontColor(COLORS.text3)
Row({ space: 10 }) {
Text('取消').fontSize(12).fontColor(COLORS.sub)
.layoutWeight(1).textAlign(TextAlign.Center)
.padding({ top: 9, bottom: 9 }).backgroundColor(COLORS.chip).borderRadius(9)
.onClick(() => onClose())
Text('删除').fontSize(12).fontColor('#FFFFFF').fontWeight(FontWeight.Bold)
.layoutWeight(1).textAlign(TextAlign.Center)
.padding({ top: 9, bottom: 9 }).backgroundColor(COLORS.red).borderRadius(9)
.onClick(() => {
this.delRecord();
})
}
.width('100%')
}
.width('72%').padding(18).backgroundColor(COLORS.card).borderRadius(14)
}
.width('100%')
.height('100%')
.alignContent(Alignment.Center)
}
panelDel 是删除确认弹窗面板。它比新建和编辑弹窗更简洁，因为不需要输入框。面板顶部是 🗑 大图标（30 号字），下方是"删除这条下载记录？"标题与"仅移除记录，不影响已保存到沙箱的文件"风险提示文案。这个提示文案明确告知用户，删除操作只移除应用内的记录条目，不会删除已保存到沙箱目录的实体文件，降低了用户对误删文件的担忧。
确认删除按钮使用风险红 COLORS.red 背景，与取消按钮的浅米色形成强烈对比，红色在 UI 设计中代表警示和危险，提醒用户这是一个需要谨慎的破坏性操作。点击确认调用 delRecord() 执行删除。面板宽度 72%，比新建和编辑弹窗的 78% 略窄，使删除确认弹窗在视觉上更聚焦、更紧凑，符合"确认对话框"的紧凑设计惯例。
十八、技术特性对比
| 特性维度 | 本应用实现方案 | 传统实现方案 | 优势说明 |
|---|---|---|---|
| 下载溯源能力 | ArkWeb WebDownloadDelegate + getOriginalUrl/getReferrerUrl 双接口 | 仅记录下载 URL，无引用页信息 | 双 URL 完整还原"从哪个页面下载了哪个直链"，来源审计无死角 |
| 下载生命周期 | onBeforeDownload/onDownloadUpdated/onDownloadFailed/onDownloadFinish 四回调齐全 | 仅 success/fail 两回调 | 覆盖开始前/进行中/失败/完成全流程，进度可观测、失败可排查 |
| 下载启动机制 | onBeforeDownload 中调用 start() 提供沙箱路径 | 系统默认路径或需自行实现存储 | 沙箱 filesDir 显式可控，文件路径可预测、可管理 |
| 主动下载 | webController.startDownload(url) 应用侧发起 | 仅依赖网页内点击下载链接 | 支持新建任务弹窗粘贴直链直接下载，无需加载网页 |
| 图表实现 | Canvas + CanvasRenderingContext2D 纯代码绘制 | MPChart 等第三方图表库 | 零依赖，可定制性高，支持呼吸动画无缝集成 |
| 图表动画 | setInterval 每秒翻转 breath 驱动重绘 | 属性动画或 Lottie | 轻量级实现，一处状态驱动渐变/线宽/点半径多处效果 |
| 主题方案 | 暖米白 + 商务蓝 + 活力橙浅色三色系 | Material Design 标准色板或纯白 | 米白底护眼、商务蓝专业、活力橙点睛，办公场景调性契合 |
| 布局策略 | 四 Tab 完全差异化布局（精选/榜单/图表 + Web + 下载 + 个人） | 统一列表式布局 | 视觉丰富度高，避免审美疲劳，功能区分明确 |
| 地址栏设计 | urlInput/webUrl 双状态分离，敲字不等于加载 | 单状态实时加载 | 避免输入过程触发无效加载，性能更优 |
| 数据响应 | @Observed + @State + slice() 刷新引用 | 手动调用 notifyDataSetChanged | 精准局部刷新，slice 确保列表整体刷新 |
| 弹窗系统 | Stack 叠层 + 条件渲染 + 回调式关闭 + 通用 modalOverlay | Dialog 组件或第三方弹窗库 | 无外部依赖，遮罩与面板解耦，关闭逻辑灵活委托 |
| 代码预览 | 界面内嵌 onDownloadFinish 源码 + 语法高亮配色 | 纯文字说明或截图 | 代码即文档，用户查看记录同时理解溯源实现 |
| 格式识别 | fmtColor 函数映射 PPT 蓝/Word 橙/Excel 绿 | 统一颜色或需自行封装 | 颜色即格式，一眼可辨，认知负担低 |
十九、总结
本应用完整展示了 HarmonyOS ArkUI 框架在办公模板资源平台场景下的工程实践能力，特别是 ArkWeb 6.1.1 双 URL 下载溯源特性的落地实现。从整体架构来看，代码通过颜色系统、常量定义、辅助函数、数据模型、组件主体、Builder 函数群六个层次的清晰划分，实现了高内聚低耦合的代码组织。颜色系统集中管理 18 个主题色字段（含三档呼吸渐变色），为未来主题切换预留了接口；常量定义将所有 Mock 数据和配置选项抽离为独立常量，便于后续替换为真实接口数据；辅助函数封装了趋势映射、格式映射、URL 处理等可复用逻辑；数据模型使用 @Observed 装饰器实现响应式数据追踪，特别是 DownloadRecord 类承载了双 URL 溯源的核心数据结构。
双 URL 下载溯源功能是本应用的技术核心。通过 WebDownloadDelegate 的四回调体系，应用实现了从下载启动、进度刷新、失败处理到完成溯源的全链路可观测。在 onDownloadFinish 完成回调中，调用 HarmonyOS 6.1.1 新增的 getOriginalUrl() 与 getReferrerUrl() 两个接口，分别获取下载项的原始 URL 地址与引用页 URL 地址，构造完整的 DownloadRecord 记录。这两个 URL 的区别在于：原始 URL 回答"下载了什么文件、文件从哪台 CDN 服务器取"，引用页 URL 回答"用户从哪个页面、哪个入口点击的下载"。两者结合，完整还原了用户的下载行为链，使办公模板平台具备了版权追溯、下载来源统计、模板推荐回流分析、恶意下载检测等企业级能力。无论是网页内点击下载链接还是应用侧 startDownload 主动发起，都统一收口到这四个回调，使下载审计逻辑只需一处实现即可覆盖所有来源。
Canvas 折线图绘制能力是本应用的另一技术亮点。通过 CanvasRenderingContext2D 的系列 API，应用绘制了近 8 周模板下载量趋势折线图，包含背景网格、渐变面积、连续折线、数据点圆点、数值标签、周标签六个层次。createLinearGradient 实现的渐变面积填充使折线下方有了"重量感"，moveTo + lineTo 连续连线绘制主折线，arc 绘制数据点圆点配合空心描边形成可辨节点，末点活力橙高亮使最新数据成为视觉焦点。更巧妙的是，折线图通过 setInterval 每秒翻转 breath 布尔值驱动重绘，使渐变透明度、线宽、数据点半径呈现"呼吸"般的动态效果，让静态图表拥有了生命力。onReady 回调确保首次绘制在 Canvas 上下文就绪后触发，canvasReady 标志使后续重绘有了安全前提，这两个机制共同保证了绘制的稳定性。
四 Tab 差异化布局设计是本应用在 UI 层面的亮点。模板 Tab 采用精选合集卡 + 大编号热门榜 + Canvas 折线图的组合，从编辑推荐到用户热度再到趋势可视化层层递进；网页 Tab 采用地址栏 + 快捷站点 + Web 组件 + 主动下载演示的组合，完整展示 ArkWeb 的加载与下载能力；下载 Tab 采用进行中任务卡 + 代码预览卡 + 双 URL 溯源列表的组合，使下载状态与溯源信息一目了然；我的 Tab 采用职场身份渐变大卡 + 功能清单行的组合，简洁组织个人信息与功能入口。每个 Tab 的布局都经过独立设计，避免了千篇一律的列表式界面。特别是下载 Tab 中的代码预览卡，将 onDownloadFinish 回调的源码以语法高亮的形式直接呈现在界面上，使用户在查看下载记录的同时能直观理解双 URL 溯源的技术实现，是兼具功能与教学价值的设计。
浅色主题方案的实现也值得称道。暖米白 #F8F6F2 作为页面底色，不是纯白而是带轻微米色调，降低了大面积白底对眼睛的刺激，更符合长时间办公阅读的舒适度需求。纯白 #FFFFFF 用于卡片底色，与米白底色形成微弱但可感知的层次差，使卡片从背景中"浮起"。商务蓝 #2563EB 与深商务蓝 #1D4ED8 构成品牌主色对，活力橙 #F59E0B 作为强调色用于折线图末点高亮、引用页 URL 文字色、橙色描边按钮等关键视觉锚点，形成冷暖对比。多处使用 linearGradient 渐变背景（120 度用于头部 Banner，135 度用于职场身份大卡）为界面增添了层次感和立体感。呼吸动画通过一个 setInterval 定时器每秒翻转 breath 布尔值，驱动折线图渐变透明度、线宽、数据点半径等多处视觉效果，实现了"一处状态控制多处动画"的高效设计。
弹窗系统采用了 Stack 叠层 + 条件渲染 + 回调式关闭的架构。modalOverlay 提供通用的半透明遮罩，panelAdd/panelEdit/panelDel 三个面板分别处理新建下载任务、编辑备注、删除确认场景。每个面板接收 onClose 回调函数，实现了关闭逻辑的灵活委托。删除确认弹窗使用红色背景的确认按钮和"仅移除记录，不影响已保存到沙箱的文件"的风险提示文案，遵循了破坏性操作的设计规范。编辑备注保存时通过 this.downloadRecords = this.downloadRecords.slice() 创建数组新引用确保 ForEach 列表刷新，这是 ArkUI 响应式系统的一个关键技巧——@Observed 类的属性修改虽能被追踪，但 ForEach 列表的整体刷新需要数组引用变更才能触发。
从工程实践的角度看，本应用虽然是一个功能演示级别的单文件应用，但其代码组织方式、状态管理策略、UI 设计理念都体现了成熟的前端工程思维。@Observed + @State 的响应式数据流、Builder 函数的参数化复用、条件渲染驱动的弹窗系统、数据驱动的 UI 适配、双状态分离的地址栏设计、Canvas 与定时器联动的呼吸动画，这些模式都可以直接迁移到更大规模的模块化项目中。对于希望学习 HarmonyOS ArkUI 开发、ArkWeb 下载代理能力、Canvas 自定义图表绘制的开发者来说，本应用是一个结构完整、注释详尽、可直接运行参考的优质学习材料，特别是 getOriginalUrl 与 getReferrerUrl 双接口的落地示例，为企业在下载溯源、来源审计、行为分析等场景的 ArkWeb 实践提供了可直接复用的工程范式。
附录：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 将自动执行以下操作：
- 生成项目骨架（Stage 模型目录结构）
- 执行
ohpm install安装依赖 - 运行 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 应用的功能开发。
本文基于 DevEco Studio 6.1.1 Release 版本编写，不同版本界面可能存在细微差异。
讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。
更多推荐
6
0- 0
已为社区贡献17条内容
所有评论(0)