一、技术前言
在文化创意产业蓬勃发展的今天，非物质文化遗产的数字化传承正成为连接古今的关键纽带。从唐草卷纹到宋瓷缠枝，从回纹锦缎到冰裂青瓷，每一件纹样素材都承载着千年的审美密码与工艺智慧。然而，传统纹样素材管理平台往往面临三大困境：纹样品类缺乏可视化占比分析、朝代与品类的双层导航交互割裂、WebP 素材的元数据读写无法在端侧完成。这些痛点使得非遗纹样的数字化传播始终停留在"图片仓库"的初级阶段。
HarmonyOS ArkUI 框架以其声明式 UI 范式为这些问题提供了系统级的解决方案。ArkUI 基于 TypeScript 扩展的 ArkTS 语言，通过 @Component 装饰器封装可复用的组件单元，通过 @State、@Observed 等状态管理装饰器实现数据驱动渲染，通过 @Builder 方法将复杂的 UI 结构拆分为可组合的构建块。这种声明式组件化架构天然契合非遗纹样平台"数据-视图-交互"三层紧耦合的需求------纹样实体的增删改可以实时驱动卡片列表刷新，Canvas 自绘图表能够响应状态变化而重绘，嵌套滚动的时间轴可以精确记录用户的浏览路径。
本平台深度融合了 HarmonyOS 6.1.1 的三大前沿特性。Canvas 自绘引擎 通过 CanvasRenderingContext2D 实现 drawPie 环形图------五扇区 arc 路径填色配合中心镂空裁切，叠加 fillText 百分比标注与馆藏总量中心文字，setInterval 每秒翻转 breath 状态并手动调用 drawPie() 实现呼吸微动重绘。Tabs 嵌套滚动 API 24 通过 nestedScroll(TabsNestedScrollMode) 让内层纹样类别列表滑到边缘后联动外层朝代频道，SELF_FIRST（先内后外）与 SELF_ONLY（仅内层）两种模式可实时切换，每一次翻页事件均被 onChange 回调捕获并写入时间轴日志。Image Kit WebP 元数据 API 24 实现了完整的"生成→读取→写入→回读校验"沙箱链路------createPixelMap 编码像素画为 WebP 并落盘 filesDir，readImageMetadataByType 读取五字段快照，writeImageMetadata 写回帧延迟与循环次数，再重建 ImageSource 二次读取比对校验，全程零权限沙箱操作。
二、整体架构流程图
#mermaid-svg-UnOB4GdDd5LMs9eQ{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-UnOB4GdDd5LMs9eQ .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-UnOB4GdDd5LMs9eQ .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-UnOB4GdDd5LMs9eQ .error-icon{fill:#552222;}#mermaid-svg-UnOB4GdDd5LMs9eQ .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-UnOB4GdDd5LMs9eQ .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-UnOB4GdDd5LMs9eQ .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-UnOB4GdDd5LMs9eQ .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-UnOB4GdDd5LMs9eQ .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-UnOB4GdDd5LMs9eQ .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-UnOB4GdDd5LMs9eQ .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-UnOB4GdDd5LMs9eQ .marker{fill:#333333;stroke:#333333;}#mermaid-svg-UnOB4GdDd5LMs9eQ .marker.cross{stroke:#333333;}#mermaid-svg-UnOB4GdDd5LMs9eQ svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-UnOB4GdDd5LMs9eQ p{margin:0;}#mermaid-svg-UnOB4GdDd5LMs9eQ .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-UnOB4GdDd5LMs9eQ .cluster-label text{fill:#333;}#mermaid-svg-UnOB4GdDd5LMs9eQ .cluster-label span{color:#333;}#mermaid-svg-UnOB4GdDd5LMs9eQ .cluster-label span p{background-color:transparent;}#mermaid-svg-UnOB4GdDd5LMs9eQ .label text,#mermaid-svg-UnOB4GdDd5LMs9eQ span{fill:#333;color:#333;}#mermaid-svg-UnOB4GdDd5LMs9eQ .node rect,#mermaid-svg-UnOB4GdDd5LMs9eQ .node circle,#mermaid-svg-UnOB4GdDd5LMs9eQ .node ellipse,#mermaid-svg-UnOB4GdDd5LMs9eQ .node polygon,#mermaid-svg-UnOB4GdDd5LMs9eQ .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-UnOB4GdDd5LMs9eQ .rough-node .label text,#mermaid-svg-UnOB4GdDd5LMs9eQ .node .label text,#mermaid-svg-UnOB4GdDd5LMs9eQ .image-shape .label,#mermaid-svg-UnOB4GdDd5LMs9eQ .icon-shape .label{text-anchor:middle;}#mermaid-svg-UnOB4GdDd5LMs9eQ .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-UnOB4GdDd5LMs9eQ .rough-node .label,#mermaid-svg-UnOB4GdDd5LMs9eQ .node .label,#mermaid-svg-UnOB4GdDd5LMs9eQ .image-shape .label,#mermaid-svg-UnOB4GdDd5LMs9eQ .icon-shape .label{text-align:center;}#mermaid-svg-UnOB4GdDd5LMs9eQ .node.clickable{cursor:pointer;}#mermaid-svg-UnOB4GdDd5LMs9eQ .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-UnOB4GdDd5LMs9eQ .arrowheadPath{fill:#333333;}#mermaid-svg-UnOB4GdDd5LMs9eQ .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-UnOB4GdDd5LMs9eQ .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-UnOB4GdDd5LMs9eQ .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-UnOB4GdDd5LMs9eQ .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-UnOB4GdDd5LMs9eQ .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-UnOB4GdDd5LMs9eQ .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-UnOB4GdDd5LMs9eQ .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-UnOB4GdDd5LMs9eQ .cluster text{fill:#333;}#mermaid-svg-UnOB4GdDd5LMs9eQ .cluster span{color:#333;}#mermaid-svg-UnOB4GdDd5LMs9eQ div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-UnOB4GdDd5LMs9eQ .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-UnOB4GdDd5LMs9eQ rect.text{fill:none;stroke-width:0;}#mermaid-svg-UnOB4GdDd5LMs9eQ .icon-shape,#mermaid-svg-UnOB4GdDd5LMs9eQ .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-UnOB4GdDd5LMs9eQ .icon-shape p,#mermaid-svg-UnOB4GdDd5LMs9eQ .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-UnOB4GdDd5LMs9eQ .icon-shape .label rect,#mermaid-svg-UnOB4GdDd5LMs9eQ .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-UnOB4GdDd5LMs9eQ .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-UnOB4GdDd5LMs9eQ .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-UnOB4GdDd5LMs9eQ :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} Page1223 主组件
headerBanner 头部朱砂渐变Banner
内容区 6 Tab 切换
tabBar 底部导航
modalOverlay 弹窗遮罩
Tab0 素材馆
朝代筛选+双列卡片+环形图+柱状图
Tab1 频道
朝代×纹样双层Tabs嵌套滚动
Tab2 日志
nestedScroll翻页时间轴
Tab3 工坊
纹理五选一+WebP生成落盘
Tab4 元数据
五字段读取写入回读校验
Tab5 我的
守艺人渐变大卡+任务清单
Canvas自绘引擎
drawPie环形图呼吸重绘
Tabs嵌套滚动
nestedScroll模式切换
ImageKit WebP
像素画编码落盘沙箱
ImageKit元数据
读写回读全链路校验
panelAdd 新建纹样收藏
panelEdit 编辑用途描述
panelDel 删除确认
整体架构以 Page1223 为根组件，采用 Stack 容器实现页面层叠。底层是 Column 纵向布局，依次承载头部朱砂渐变 Banner、内容区和底部 Tab 栏；顶层是全屏弹窗遮罩层。内容区通过 currentTab 状态索引在 6 个 @Builder 方法间切换，每个 Tab 拥有完全独立的布局结构和业务逻辑。三大特性分别在素材馆（Canvas 环形图）、频道（Tabs 嵌套滚动）、工坊与元数据（ImageKit WebP）四个 Tab 上挂载，但所有状态变量统一声明在组件顶层 @State 区域，实现跨 Tab 数据共享------例如工坊生成的 WebP 路径直接被元数据 Tab 的读取按钮消费，频道的翻页日志直接被日志 Tab 的时间轴展示。
三、色彩体系设计
3.1 ColorPalette 接口定义
平台采用浅色宣纸主题，通过 ColorPalette 接口集中声明全部颜色字段，每个字段对应一种语义角色：
typescript
interface ColorPalette {
bg: string; // 页面底色·宣纸米白
card: string; // 卡片底色·纯白
chip: string; // 胶囊/输入底色·米杏
title: string; // 主标题·墨褐
sub: string; // 次级文字·驼褐
text3: string; // 弱化文字·浅驼
red: string; // 主题色·朱砂
redD: string; // 主题色深·深朱砂
blue: string; // 辅色·黛蓝
gold: string; // 辅色·鎏金
green: string; // 辅色·苔绿
line: string; // 分割线·米灰
tabOn: string; // Tab 激活色·朱砂
mask: string; // 弹窗遮罩·墨褐半透
onMain: string; // 深色底上的白字
gradA: string; // 渐变起点·朱砂（头部/会员卡）
gradB: string; // 渐变终点·深朱砂（统计大卡）
}接口设计遵循"语义命名"原则：不使用 color1、color2 这样的无意义编号，而是用 red、blue、gold、green 这类既有文化语义的色名。onMain 字段专门为深色渐变背景上的白字设计，保证头部 Banner 和会员大卡上的文字对比度。gradA 与 gradB 作为渐变端点色，分别用于头部 Banner 的朱砂渐变和统计大卡的深朱砂渐变。
3.2 COLORS 常量逐色分析
typescript
const COLORS: ColorPalette = {
bg: '#F7F3EC', // 宣纸米白，模拟古籍纸张的温润底色
card: '#FFFFFF', // 纯白卡片底色，提供最清爽的信息承载面
chip: '#EFE8DC', // 米杏色胶囊底，比背景略深一档形成层次
title: '#3B2F25', // 墨褐色主标题，如同墨笔书写的深色字迹
sub: '#8A7A64', // 驼褐色副标题，层次柔和过渡
text3: '#B5A88F', // 浅驼色弱文本，辅助信息不抢视觉
red: '#C0392B', // 朱砂红主色，中国传统正色之首
redD: '#9A2C20', // 深朱砂，渐变终点与删除操作色
blue: '#2C3E7A', // 黛蓝色，朝代徽标与信息标识
blueD: '#1F2D5C', // 深黛蓝，会员卡三列格底色
gold: '#B8860B', // 鎏金色，外层频道徽标与优选档位
green: '#5E8C61', // 苔绿色，内层频道徽标与完成态
line: '#E8E0D0', // 米灰色分割线，低对比度不干扰
tabOn: '#C0392B', // Tab选中色与主题朱砂一致
mask: 'rgba(59,47,37,0.55)', // 墨褐半透遮罩
onMain: '#FFFFFF', // 深色底白字
gradA: '#C0392B', // 渐变起点朱砂
gradB: '#9A2C20' // 渐变终点深朱砂
};色彩设计深植于中国传统美学。朱砂（#C0392B）作为主色调，取自书画印泥的千年正色，贯穿头部 Banner、Tab 选中态、主操作按钮和删除确认，成为平台的视觉锚点。黛蓝（#2C3E7A）取自青花瓷釉下彩的发色区间，用于朝代徽标和信息标识。鎏金（#B8860B）和苔绿（#5E8C61）分别对应外层频道和内层频道的层级徽标，让用户在嵌套滚动时凭颜色即可判断当前所处层级。宣纸米白（#F7F3EC）作为页面底色模拟古籍纸张的温润质感，与纯白卡片底色形成微妙层次差异。
四、Tab 元数据与辅助数据
4.1 底部导航 Tab 定义
typescript
interface TabMeta {
icon: string; // Tab 图标
label: string; // Tab 标签
}
const TAB_LIST: TabMeta[] = [
{ icon: '🏛️', label: '素材' },
{ icon: '🌀', label: '频道' },
{ icon: '📜', label: '日志' },
{ icon: '🎨', label: '工坊' },
{ icon: '🧬', label: '元数据' },
{ icon: '👤', label: '我的' }
];6 个 Tab 单排排列，从素材浏览到个人中心覆盖非遗纹样管理的完整流程。每个 Tab 的图标与其功能语义紧密对应：🏛️ 代表馆藏素材库，🌀 代表频道流转导航，📜 代表时间轴日志记录，🎨 代表样图工坊创作，🧬 代表元数据基因解码，👤 代表守艺人个人中心。TabMeta 接口将图标与标签绑定为单一体，ForEach 渲染时以 tab.label 作为键值保证唯一性。
4.2 嵌套频道数据
typescript
interface ChannelItem {
name: string; // 朝代频道名
icon: string; // 朝代频道图标
}
const OUTER_CHANNELS: ChannelItem[] = [
{ name: '唐', icon: '🏯' },
{ name: '宋', icon: '🖌' },
{ name: '元', icon: '🏇' },
{ name: '明', icon: '🏮' },
{ name: '清', icon: '🪷' }
];
const INNER_TABS: string[] = ['回纹', '云纹', '方胜', '冰裂', '联珠'];外层 5 个朝代频道代表中国纹样艺术的五大高峰时期：唐代（🏯 宫殿建筑）、宋代（🖌 文人书画）、元代（🏇 游牧骑射）、明代（🏮 灯笼节庆）、清代（🪷 莲花雅趣）。内层 5 个纹样类别覆盖中国传统装饰纹样的五大谱系------回纹（横竖折线连绵不断）、云纹（如意云头层层叠叠）、方胜（两菱相扣同心相连）、冰裂（冰面裂纹织理纵横）、联珠（圆珠连环成带成圈）。两层 Tabs 嵌套形成 25 个朝代×纹样的交叉矩阵，每个矩阵下有 8 条素材卡片，共 200 个纹样条目。
4.3 Canvas 环形图数据
typescript
interface PieData {
val: number; // 占比（%，合计 100）
label: string; // 品类名
}
const PIE_DATA: PieData[] = [
{ val: 30, label: '回纹' },
{ val: 25, label: '云纹' },
{ val: 18, label: '方胜' },
{ val: 15, label: '冰裂' },
{ val: 12, label: '联珠' }
];
const PIE_COLORS: string[] = [COLORS.red, COLORS.blue, COLORS.gold, COLORS.green, COLORS.redD];
const PIE_TOTAL: number = 1280;五品类馆藏占比数据体现了回纹作为最基础纹样的主导地位（30%），云纹紧随其后（25%），方胜与冰裂居中（18% 与 15%），联珠作为最复杂的编织纹样占比最小（12%）。PIE_COLORS 数组直接引用 COLORS 常量，保证环形图扇区配色与全局主题完全一致。PIE_TOTAL 作为环形图中心镂空区域的核心文字，展示馆藏纹样总量 1280 件。ArkTS 语法要求内联类型必须先定义 interface，因此 {val: number, label: string}[] 形式无法通过编译，必须声明 PieData 接口。
4.4 月度柱状图数据
typescript
const MONTH_IDX: number[] = [0, 1, 2, 3, 4, 5];
const MONTH_NAME: string[] = ['03', '04', '05', '06', '07', '08'];
const DOWNLOAD_VAL: number[] = [320, 410, 380, 520, 470, 610];
const BAR_MAX: number = 640;近 6 个月的纹样素材成交量整体呈上升趋势（320→610），反映非遗纹样数字化传播的热度增长。满刻度 BAR_MAX 设为 640 件，高于最大值 610 以保留视觉余量。柱高换算公式为 DOWNLOAD_VAL[i] / BAR_MAX * 96，即满刻度对应 96vp 的柱高。MONTH_IDX 数组作为索引遍历器，使 ForEach 的键值生成器可以拼接 bar_${i}_${this.breath}，让呼吸状态变化时触发柱状图重新渲染。
4.5 WebP 工坊纹理数据
typescript
interface TextureItem {
key: string; // 像素算法键
name: string; // 对应纹样名
label: string; // 纹理标签
desc: string; // 寓意说明
}
const TEXTURES: TextureItem[] = [
{ key: 'diag', name: '回纹', label: '斜纹', desc: '横竖折线连绵不断，寓意福寿绵长、富贵不断头' },
{ key: 'checker', name: '方胜', label: '棋盘', desc: '两菱相扣同心相连，寓意同心永结、吉祥永续' },
{ key: 'horz', name: '云纹', label: '横带', desc: '如意云头层层叠叠，寓意平步青云、节节高升' },
{ key: 'vert', name: '冰裂', label: '竖带', desc: '冰面裂纹织理纵横，寓意破冰新生、寒尽春来' },
{ key: 'ring', name: '联珠', label: '同心环', desc: '圆珠连环成带成圈，寓意绵延不绝、珠联璧合' }
];纹理五选一将像素算法与纹样语义一一映射。key 字段是像素生成算法的分支键，pixelColor 函数据此选择不同的织理算法：diag 对应斜纹（行列相加取模形成 45 度斜带）、checker 对应棋盘（8×8 分块行列块索引相加取模）、horz 对应横带（每 16 行换一色）、vert 对应竖带（每 16 列换一色）、ring 对应同心环（按到画布中心的欧氏距离分环）。每个纹理的 desc 字段赋予了像素画以文化内涵，让技术生成不再冰冷。
五、工具函数分析
5.1 嵌套模式文案映射
typescript
function modeLabel(mode: TabsNestedScrollMode): string {
return mode === TabsNestedScrollMode.SELF_FIRST
? 'SELF_FIRST·先内后外' : 'SELF_ONLY·仅内层';
}
function modeShort(mode: TabsNestedScrollMode): string {
return mode === TabsNestedScrollMode.SELF_FIRST ? '先内后外' : '仅内层';
}这两个函数将 TabsNestedScrollMode 枚举值翻译为中文文案。modeLabel 返回完整文案（含枚举名前缀），用于日志 Tab 的时间轴记录，确保工程师可以通过文案逆向还原技术状态。modeShort 返回简短文案，用于头部胶囊和模式切换 chips，在有限空间内呈现核心信息。这种"完整版+简版"的双文案策略，兼顾了可读性与信息密度。
5.2 数值格式化函数群
typescript
function fmtField(v: number, unit: string): string {
return v < 0 ? '未提供' : `${v}${unit}`;
}
function loopText(v: number): string {
if (v < 0) { return '未提供'; }
if (v === 0) { return '0（不限）'; }
return `${v} 次`;
}
function sizeText(v: number): string {
return v < 0 ? '未提供' : `${v} px`;
}这三个格式化函数共同遵循"-1 表示未提供"的兜底策略。WebP 元数据的五个字段（canvasWidth、canvasHeight、delayTime、unclampedDelayTime、loopCount）全部为可选值，读取时可能返回 undefined。平台使用 ?? -1 空值合并运算符将 undefined 转为 -1，再由格式化函数将 -1 渲染为"未提供"文案。loopText 额外处理了 0 这个特殊值------在 WebP 动画语义中 loopCount=0 表示无限循环，因此渲染为"0（不限）"而非"0 次"。
5.3 像素颜色转换与织理算法
typescript
function hexToRgba(hex: string): number {
const r = parseInt(hex.slice(1, 3), 16);
const g = parseInt(hex.slice(3, 5), 16);
const b = parseInt(hex.slice(5, 7), 16);
return 0xFF000000 | (b << 16) | (g << 8) | r;
}
function pixelColor(row: number, col: number, key: string, palette: string[]): number {
const n = palette.length;
if (key === 'checker') {
return hexToRgba(palette[(Math.floor(row / 8) + Math.floor(col / 8)) % n]);
}
if (key === 'horz') {
return hexToRgba(palette[Math.floor(row / 16) % n]);
}
if (key === 'vert') {
return hexToRgba(palette[Math.floor(col / 16) % n]);
}
if (key === 'ring') {
const dx = col - CANVAS_SIZE / 2;
const dy = row - CANVAS_SIZE / 2;
const dist = Math.sqrt(dx * dx + dy * dy);
return hexToRgba(palette[Math.floor(dist / 9) % n]);
}
return hexToRgba(palette[(row + col) % n]);
}hexToRgba 将十六进制颜色字符串转为 RGBA8888 小端排列的 32 位无符号整数。WebP 像素画使用 Uint32Array 逐像素直写，每个像素占 4 字节，字节序为 RGBA（小端序下高位 A=0xFF，低三字节为 B、G、R）。因此转换公式为 0xFF000000 | (b << 16) | (g << 8) | r，先拼 alpha 通道再按 BGR 顺序排列。
pixelColor 是像素织理的核心算法分发器，根据纹理 key 选择不同的色彩映射规则。棋盘纹以 8 像素为单位分块，行列块索引之和取模色板长度，形成黑白交替的方格图案。横带纹以 16 行为周期换色，模拟云纹的横向层叠。竖带纹以 16 列为周期换色，模拟冰裂的纵向裂理。同心环纹计算像素到画布中心的欧氏距离，每 9 像素换一色，形成从中心向外扩散的同心圆环。斜纹为默认分支，行列索引之和取模色板长度，形成 45 度斜向条纹。
5.4 语义配色函数群
typescript
function catColor(cat: string): string {
if (cat === '回纹') { return COLORS.red; }
if (cat === '云纹') { return COLORS.blue; }
if (cat === '方胜') { return COLORS.gold; }
if (cat === '冰裂') { return COLORS.green; }
if (cat === '联珠') { return COLORS.redD; }
return COLORS.text3;
}
function scoreBadge(score: number): string {
if (score >= 92) { return '精选'; }
if (score >= 88) { return '优选'; }
return '良品';
}
function scoreColor(score: number): string {
if (score >= 92) { return COLORS.red; }
if (score >= 88) { return COLORS.gold; }
return COLORS.green;
}catColor 将纹样品类名映射为主题色：回纹朱砂、云纹黛蓝、方胜鎏金、冰裂苔绿、联珠深朱砂。这种一一对应的配色策略让用户在素材卡片列表中凭色块即可辨识品类，降低认知负荷。scoreBadge 与 scoreColor 将 0-100 的适配度评分分为三档------92 分以上为"精选"配朱砂色、88 分以上为"优选"配鎏金色、其余为"良品"配苔绿色。三档分级不仅提供文字标签，还以颜色形成视觉梯度。
5.5 状态与日志配色函数
typescript
function genStateColor(state: string): string {
if (state.indexOf('失败') >= 0) { return COLORS.redD; }
if (state.indexOf('生成中') >= 0) { return COLORS.gold; }
if (state.indexOf('已生成') >= 0) { return COLORS.green; }
return COLORS.text3;
}
function opColor(op: string): string {
if (op === '生成样图') { return COLORS.blue; }
if (op === '读取元数据') { return COLORS.green; }
if (op === '写入元数据') { return COLORS.red; }
return COLORS.gold;
}
function layerColor(layer: string): string {
return layer === '外层朝代' ? COLORS.gold : COLORS.green;
}三个函数分别服务于不同的状态指示场景。genStateColor 根据 WebP 生成状态文案中的关键词匹配颜色------含"失败"配深朱砂警示、含"生成中"配鎏金等待、含"已生成"配苔绿完成、默认配浅驼弱化。opColor 为元数据操作日志的四类操作分配语义色------生成配黛蓝、读取配苔绿、写入配朱砂、回读配鎏金。layerColor 区分嵌套滚动的两个层级------外层朝代配鎏金、内层类别配苔绿。这些配色函数使得纯文本日志也能携带视觉信息。
六、数据模型层
6.1 PatternItem 纹样素材模型
typescript
@Observed
export class PatternItem {
name: string; // 纹样名
dynasty: string; // 朝代
cat: string; // 品类
uses: string; // 用途描述
score: number; // 适配度评分
constructor(name: string, dynasty: string, cat: string, uses: string, score: number) {
this.name = name;
this.dynasty = dynasty;
this.cat = cat;
this.uses = uses;
this.score = score;
}
}PatternItem 是素材馆双列卡片的业务实体，使用 @Observed 装饰器声明为可观察对象。@Observed 的作用是：当该类的实例属性被修改时，所有通过 @State 或 @ObjectLink 绑定该实例的组件都会收到变更通知并触发重新渲染。这意味着弹窗中调用 this.patternList[this.editIdx].uses = newValue 修改用途描述后，素材卡片上的文字会自动更新。五个字段涵盖纹样的核心属性------名称（如"唐草卷纹"）、朝代（唐/宋/元/明/清）、品类（回纹/云纹/方胜/冰裂/联珠）、用途描述（工艺载体与应用场景）、适配度评分（0-100 数值）。
6.2 InnerCard 内层子类卡片模型
typescript
@Observed
export class InnerCard {
id: string; // 唯一键
tag: string; // 所属纹样类别子页签名
title: string; // 卡片标题
desc: string; // 卡片描述
constructor(id: string, tag: string, title: string, desc: string) {
this.id = id;
this.tag = tag;
this.title = title;
this.desc = desc;
}
}
function innerMockData(channel: ChannelItem, tabName: string): InnerCard[] {
const list: InnerCard[] = [];
for (let i = 1; i <= 8; i++) {
list.push(new InnerCard(
`${channel.name}-${tabName}-${i}`,
tabName,
`${tabName}纹·${INNER_TITLES[i - 1]} 第 ${i} 期`,
`${channel.icon} 「${channel.name}」频道「${tabName}」子类第 ${i} 条素材：${INNER_WORKS[i - 1]}，${INNER_NOTES[i - 1]}`));
}
return list;
}InnerCard 是嵌套 Tabs 内层列表的条目实体，同样使用 @Observed 装饰。id 字段采用"朝代-品类-序号"三段拼接（如"唐-回纹-1"）保证全局唯一性，作为 ForEach 的键值。innerMockData 是 Mock 数据生成器，为每个朝代×品类的交叉矩阵生成 8 条卡片数据。标题拼接纹样类别与工艺载体名称（如"回纹纹·织锦提花 第 1 期"），描述拼接频道图标、朝代名、品类名、作品名和工艺注解，保证内容超过一屏以触发嵌套滚动效果。
6.3 SwipeLog 滑动日志模型
typescript
@Observed
export class SwipeLog {
layer: string; // 层级
tabName: string; // 翻到的页签名
fromIdx: number; // 起始索引
toIdx: number; // 目标索引
mode: string; // 触发时的嵌套模式
time: string; // 记录时间
constructor(layer: string, tabName: string, fromIdx: number, toIdx: number, mode: string) {
this.layer = layer;
this.tabName = tabName;
this.fromIdx = fromIdx;
this.toIdx = toIdx;
this.mode = mode;
const d = new Date();
this.time = `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}:${String(d.getSeconds()).padStart(2, '0')}`;
}
}SwipeLog 记录每一次 Tab 翻页事件，是日志 Tab 时间轴的数据来源。layer 区分事件来源（"外层朝代"或"内层类别"），fromIdx 和 toIdx 记录翻页的起始页和目标页索引，mode 记录事件发生时的嵌套滚动模式（SELF_FIRST·先内后外 或 SELF_ONLY·仅内层），time 在构造函数中自动生成当前时间的 HH:mm:ss 格式时间戳。使用 padStart(2, '0') 保证时分秒始终为两位数，维持时间轴的等宽对齐。
6.4 WebpMetaSnapshot 元数据快照模型
typescript
@Observed
export class WebpMetaSnapshot {
canvasWidth: number; // 画布宽（px），-1=未提供
canvasHeight: number; // 画布高（px），-1=未提供
delayTime: number; // 帧延迟（钳制后 ms），-1=未提供
unclampedDelayTime: number; // 帧延迟（未钳制 ms），-1=未提供
loopCount: number; // 循环次数，-1=未提供（0=不限）
constructor(w: number, h: number, d: number, u: number, l: number) {
this.canvasWidth = w;
this.canvasHeight = h;
this.delayTime = d;
this.unclampedDelayTime = u;
this.loopCount = l;
}
}WebpMetaSnapshot 镜像 WebP 图片的五字段元数据。canvasWidth 和 canvasHeight 是画布尺寸（像素），delayTime 是限幅后的帧延迟（毫秒，受 [100, 65535] 钳制区间约束），unclampedDelayTime 是未限幅的原始帧延迟，loopCount 是循环次数（0 表示无限循环）。所有字段使用 -1 作为"未提供"的哨兵值，因为 WebP 元数据的五个字段全部为可选------静态 WebP 可能没有帧延迟信息，单帧图可能没有循环次数。@Observed 装饰使得快照字段的赋值会自动触发快照卡片的重新渲染。
6.5 MetaOpLog 操作日志模型
typescript
@Observed
export class MetaOpLog {
op: string; // 操作名
detail: string; // 结果明细
time: string; // 记录时间
constructor(op: string, detail: string) {
this.op = op;
this.detail = detail;
const d = new Date();
this.time = `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}:${String(d.getSeconds()).padStart(2, '0')}`;
}
}MetaOpLog 记录元数据操作的完整链路日志。op 字段取值为"生成样图"、"读取元数据"、"写入元数据"、"回读校验"四类，detail 字段记录操作结果明细（成功时包含文件大小或字段值，失败时包含错误码和消息）。每次操作完成后通过 unshift 置顶到日志列表，超过 30 条时 pop 裁剪尾部，保持日志流在可控长度内。time 字段与 SwipeLog 一样在构造函数中自动生成时间戳。
七、组件主体结构
7.1 @State 状态变量声明
typescript
@Entry
@Component
struct Page1223 {
/************* 基础 UI 状态 *************/
@State currentTab: number = 0; // 当前 Tab 索引
@State breath: boolean = false; // 呼吸动画开关
private timer: number = -1; // 呼吸动画定时器句柄
/************* 弹窗状态（三态统一） *************/
@State addModal: boolean = false; // 新建纹样收藏弹窗
@State editModal: boolean = false; // 编辑用途弹窗
@State delModal: boolean = false; // 删除确认弹窗
@State editIdx: number = -1; // 编辑条目索引
@State delIdx: number = -1; // 删除条目索引
@State inputText: string = ''; // 弹窗输入框内容
/************* 素材馆业务状态 *************/
@State patternList: PatternItem[] = PATTERN_LIST; // 纹样素材数据
@State activeDynasty: string = '全部'; // 当前朝代筛选组件状态变量分为五个语义分组。基础 UI 状态包含 currentTab（当前激活的 Tab 索引）和 breath（呼吸动画的布尔翻转器），timer 作为定时器句柄声明为 private 而非 @State，因为它不参与 UI 渲染。弹窗状态采用三态统一设计------三个布尔标志（addModal、editModal、delModal）互斥激活，两个索引（editIdx、delIdx）记录操作目标，一个 inputText 统一承载弹窗输入框内容。素材馆业务状态包含纹样素材数组（初始值为 PATTERN_LIST 常量）和当前朝代筛选条件。
7.2 三大特性状态声明
typescript
/************* 特性 A 状态（Canvas 绘制） *************/
private pieCtx: CanvasRenderingContext2D =
new CanvasRenderingContext2D(new RenderingContextSettings(true));
/************* 特性 B 状态（Tabs 嵌套滚动） *************/
@State nestedMode: TabsNestedScrollMode = TabsNestedScrollMode.SELF_FIRST;
@State outerIndex: number = 0;
@State innerIndex: number = 0;
@State swipeLogs: SwipeLog[] = [];
/************* 特性 C 状态（WebP 元数据） *************/
@State textureIdx: number = 0;
@State pixelMap?: image.PixelMap = undefined;
@State webpPath: string = '';
@State genState: string = '待生成';
@State metaSnapshot?: WebpMetaSnapshot = undefined;
@State writeDelay: number = 120;
@State writeLoop: number = 3;
@State verifySnapshot?: WebpMetaSnapshot = undefined;
@State opLogs: MetaOpLog[] = [];特性 A 的 Canvas 上下文 pieCtx 声明为 private 而非 @State，因为 CanvasRenderingContext2D 实例本身不变化，变化的是它绘制的画面------breath 状态变化时手动调用 drawPie() 重绘即可。特性 B 的嵌套滚动状态包含模式枚举（默认 SELF_FIRST）、外层朝代索引、内层纹样索引和翻页日志数组。特性 C 的 WebP 元数据状态最为丰富，覆盖纹理选择（textureIdx）、像素画预览（pixelMap）、沙箱路径（webpPath）、生成状态文案（genState）、读取快照（metaSnapshot）、写入参数（writeDelay、writeLoop）、回读校验快照（verifySnapshot）和操作日志（opLogs）。
7.3 生命周期与根构建
typescript
aboutToAppear() {
this.timer = setInterval(() => {
this.breath = !this.breath;
this.drawPie();
}, 1000);
}
aboutToDisappear() {
if (this.timer !== -1) {
clearInterval(this.timer);
this.timer = -1;
}
}
build() {
Stack({ alignContent: Alignment.Center }) {
Column() {
this.headerBanner()
Divider().strokeWidth(1).color(COLORS.line)
Column() {
if (this.currentTab === 0) {
this.tabPatterns()
} else if (this.currentTab === 1) {
this.tabNested()
} else if (this.currentTab === 2) {
this.tabLogs()
} else if (this.currentTab === 3) {
this.tabStudio()
} else if (this.currentTab === 4) {
this.tabMeta()
} else {
this.tabMine()
}
}.layoutWeight(1).width('100%')
this.tabBar()
}.width('100%').height('100%')
if (this.addModal || this.editModal || this.delModal) {
this.modalOverlay(() => { this.closeAllModals(); })
}
}.width('100%').height('100%').backgroundColor(COLORS.bg)
}aboutToAppear 在组件挂载时启动 1000ms 间隔的定时器，每秒翻转 breath 布尔值并调用 drawPie() 重绘 Canvas。这是"手动重绘"模式的典型实现------Canvas 组件不像 @State 绑定的 UI 元素那样自动响应状态变化重绘，必须在状态变更后显式调用绘制方法。aboutToDisappear 在组件销毁时清理定时器，避免内存泄漏。
build() 方法使用 Stack 容器实现页面层叠。内层 Column 从上到下依次排列头部 Banner、分割线、内容区和底部 Tab 栏。内容区通过 if-else 链根据 currentTab 索引切换 6 个 @Builder 方法，每个 Tab 拥有完全独立的布局结构。layoutWeight(1) 让内容区占据剩余空间。最外层的弹窗遮罩层通过 if 条件渲染------当三个弹窗标志中任一为 true 时渲染 modalOverlay，否则不渲染，实现弹窗的按需出现。
八、头部区域详解
typescript
@Builder
headerBanner() {
Column({ space: 10 }) {
Row() {
Column({ space: 4 }) {
Text('匠纹库 · 非遗纹样素材平台').fontSize(20).fontWeight(FontWeight.Bold)
.fontColor(COLORS.onMain)
Text(this.currentTab === 0 ? `素材馆 · 馆藏 ${this.patternList.length} 套`
: this.currentTab === 1 ? '频道 · 朝代×纹样双层 Tabs'
: this.currentTab === 2 ? '滑动日志 · nestedScroll 时间线'
: this.currentTab === 3 ? 'WebP 纹理样图工坊'
: this.currentTab === 4 ? '元数据读写 · 五字段'
: '守艺人中心').fontSize(11).fontColor(COLORS.onMain).opacity(0.85)
}.alignItems(HorizontalAlign.Start).layoutWeight(1)
Circle({ width: 10, height: 10 })
.fill(COLORS.onMain)
.opacity(this.breath ? 0.9 : 0.45)
}.width('100%')
Row({ space: 8 }) {
Row({ space: 6 }) {
Text('🏛️').fontSize(10)
Text(`馆藏 ${PIE_TOTAL} 件`).fontSize(10).fontColor(COLORS.sub)
}.padding({ left: 10, right: 10, top: 6, bottom: 6 })
.borderRadius(12).backgroundColor(COLORS.chip)
Row({ space: 4 }) {
Circle({ width: 6, height: 6 })
.fill(this.nestedMode === TabsNestedScrollMode.SELF_FIRST ? COLORS.green : COLORS.gold)
Text(`嵌套 ${modeShort(this.nestedMode)}`).fontSize(10).fontColor(COLORS.sub)
}.padding({ left: 10, right: 10, top: 6, bottom: 6 })
.borderRadius(12).backgroundColor(COLORS.chip)
Row({ space: 4 }) {
Circle({ width: 6, height: 6 }).fill(genStateColor(this.genState))
Text(`WebP ${this.genState}`).fontSize(10).fontColor(COLORS.sub)
.maxLines(1).textOverflow({ overflow: TextOverflow.Ellipsis })
}.padding({ left: 10, right: 10, top: 6, bottom: 6 })
.borderRadius(12).backgroundColor(COLORS.chip).layoutWeight(1)
}.width('100%')
}.padding({ left: 16, right: 16, top: 12, bottom: 12 })
.width('100%')
.linearGradient({
angle: 160,
colors: [[COLORS.gradA, 0], [COLORS.bg, 1]]
})
}头部 Banner 是平台的全局信息中枢，分为两行。第一行左侧是平台标题和动态副标题，副标题通过六段三元运算符链根据 currentTab 切换文案，在素材馆 Tab 还动态拼接馆藏数量。右侧是呼吸圆点，透明度随 breath 状态在 0.9 与 0.45 间交替翻转，形成"呼吸"的视觉节拍。第二行是三个状态胶囊：馆藏胶囊显示总量 1280 件，嵌套模式胶囊以色点（SELF_FIRST 苔绿 / SELF_ONLY 鎏金）和文案实时反映嵌套滚动状态，WebP 胶囊以 genStateColor 函数配色反映生成状态。整个 Banner 通过 linearGradient 以 160 度角从 gradA（朱砂）渐变到 bg（宣纸米白），形成朱砂到宣纸的自然过渡。
九、素材馆 Tab 深度分析
9.1 整体布局与朝代筛选
typescript
@Builder
tabPatterns() {
Column({ space: 10 }) {
Scroll() {
Column({ space: 10 }) {
Row() {
Text(`纹样卡片 · ${this.filteredPatterns().length} 套`)
.fontSize(13).fontWeight(FontWeight.Bold).fontColor(COLORS.title)
Blank()
Text('+ 收藏').fontSize(11).fontColor(COLORS.red)
.padding({ left: 10, right: 10, top: 5, bottom: 5 })
.borderRadius(10).backgroundColor(COLORS.chip)
.onClick(() => { this.openAdd(); })
}.width('100%')
Scroll() {
Row({ space: 8 }) {
ForEach(DYNASTY_CHIPS, (tag: string) => {
Text(tag === '全部' ? '全部' : `${tag}代`)
.fontSize(11)
.fontColor(this.activeDynasty === tag ? COLORS.onMain : COLORS.sub)
.padding({ left: 14, right: 14, top: 6, bottom: 6 })
.borderRadius(14)
.backgroundColor(this.activeDynasty === tag ? COLORS.red : COLORS.chip)
.onClick(() => { this.switchDynasty(tag); })
}, (tag: string) => `dyn_${tag}`)
}.padding({ left: 4, right: 4 })
}.scrollable(ScrollDirection.Horizontal).scrollBar(BarState.Off).width('100%')素材馆 Tab 采用 Scroll 外层纵向滚动 + Column 内容容器的布局。顶部标题行显示筛选后的纹样数量（通过 filteredPatterns().length 动态计算），右侧"+收藏"按钮触发 openAdd() 打开新建弹窗。朝代筛选区使用内嵌 Scroll 实现横向滚动，6 个 chips 分别对应"全部"、"唐代"、"宋代"、"元代"、"明代"、"清代"。选中态以朱砂底白字呈现，未选中态以米杏底驼褐字呈现。Blank() 组件在 Row 中占据弹性空间，将"+收藏"按钮推到右侧。
9.2 双列卡片布局
typescript
Column({ space: 10 }) {
ForEach(this.patternPairs(), (pair: PatternItem[], pi: number) => {
Row({ space: 10 }) {
ForEach(pair, (item: PatternItem) => {
this.patternCard(item)
}, (item: PatternItem) => `card_${item.name}_${item.score}`)
}.width('100%').alignItems(VerticalAlign.Top)
}, (pair: PatternItem[], pi: number) => `pair_${pi}_${pair[0].name}`)
}.width('100%')双列卡片布局通过 patternPairs() 方法预计算------先将筛选后的列表按两条一组切分为二维数组，再由外层 ForEach 遍历每对、内层 ForEach 遍历每对中的两个卡片。键值生成器拼接纹样名和评分保证唯一性，pair 键值额外拼接组索引和组内首项名称。alignItems(VerticalAlign.Top) 保证两列卡片顶部对齐，避免高度不一致时的错位。
9.3 纹样卡片内部结构
typescript
@Builder
patternCard(item: PatternItem) {
Column({ space: 8 }) {
Row({ space: 6 }) {
Text(item.name).fontSize(13).fontWeight(FontWeight.Bold)
.fontColor(COLORS.title).maxLines(1).layoutWeight(1)
.textOverflow({ overflow: TextOverflow.Ellipsis })
Text(item.dynasty).fontSize(9).fontWeight(FontWeight.Bold)
.fontColor(COLORS.onMain)
.padding({ left: 7, right: 7, top: 3, bottom: 3 })
.borderRadius(8).backgroundColor(COLORS.blue)
}.width('100%')
Row({ space: 6 }) {
Text(item.cat).fontSize(10).fontColor(COLORS.onMain)
.padding({ left: 7, right: 7, top: 3, bottom: 3 })
.borderRadius(8).backgroundColor(catColor(item.cat))
Text(`${scoreBadge(item.score)} ${item.score}`).fontSize(10)
.fontColor(scoreColor(item.score)).fontFamily('monospace')
}.width('100%')
Text(item.uses).fontSize(10).fontColor(COLORS.sub).maxLines(2).width('100%')
.textOverflow({ overflow: TextOverflow.Ellipsis })
Row({ space: 12 }) {
Blank()
Text('编辑').fontSize(10).fontColor(COLORS.blue)
.onClick(() => { this.openEdit(this.indexOfPattern(item)); })
Text('删除').fontSize(10).fontColor(COLORS.redD)
.onClick(() => { this.openDel(this.indexOfPattern(item)); })
}.width('100%')
}.padding(12).borderRadius(12).backgroundColor(COLORS.card)
.layoutWeight(1).alignItems(HorizontalAlign.Start)
}纹样卡片内部分为四层。第一层是纹样名加朝代徽标行------纹样名占据弹性宽度并设置 maxLines(1) 与省略号截断，朝代徽标以黛蓝底白字呈现。第二层是品类色徽加适配度评分行------品类徽标通过 catColor 函数取色，评分通过 scoreBadge 取档位文案、scoreColor 取档位配色，fontFamily('monospace') 保证数字等宽对齐。第三层是用途描述文本，maxLines(2) 允许两行显示。第四层是行内操作区，"编辑"按钮配黛蓝色调用 openEdit，"删除"按钮配深朱砂色调用 openDel，两个操作都通过 indexOfPattern 将筛选列表中的条目映射回完整列表的真实索引。
9.4 Canvas 环形图绘制方法
typescript
drawPie() {
const ctx = this.pieCtx;
const size = 210;
const cx = size / 2;
const cy = size / 2;
const r = 66 + (this.breath ? 4 : 0);
ctx.clearRect(0, 0, size, size);
ctx.globalAlpha = 0.16;
ctx.beginPath();
ctx.arc(cx, cy, r + 10, 0, Math.PI * 2);
ctx.strokeStyle = COLORS.red;
ctx.lineWidth = 2;
ctx.stroke();
ctx.globalAlpha = 1;
let start = -Math.PI / 2;
for (let i = 0; i < PIE_DATA.length; i++) {
const angle = (PIE_DATA[i].val / 100) * Math.PI * 2;
ctx.beginPath();
ctx.moveTo(cx, cy);
ctx.arc(cx, cy, r, start, start + angle);
ctx.fillStyle = PIE_COLORS[i];
ctx.fill();
const mid = start + angle / 2;
ctx.fillStyle = COLORS.onMain;
ctx.font = 'bold 10px sans-serif';
ctx.textAlign = 'center';
ctx.fillText(`${PIE_DATA[i].val}%`, cx + Math.cos(mid) * r * 0.72, cy + Math.sin(mid) * r * 0.72 + 3);
start += angle;
}
ctx.beginPath();
ctx.arc(cx, cy, r * 0.58, 0, Math.PI * 2);
ctx.fillStyle = COLORS.card;
ctx.fill();
ctx.fillStyle = COLORS.title;
ctx.font = 'bold 20px sans-serif';
ctx.textAlign = 'center';
ctx.fillText(`${PIE_TOTAL}`, cx, cy + 1);
ctx.fillStyle = COLORS.sub;
ctx.font = '10px sans-serif';
ctx.fillText('馆藏纹样件', cx, cy + 17);
}drawPie 是 Canvas 自绘环形图的核心方法。绘制流程分为五步：第一步 clearRect 清空画布。第二步绘制外圈呼吸描边------globalAlpha 设为 0.16 实现低透明度，绘制半径 r+10 的描边圆，随后立即将 globalAlpha 恢复为 1（这一"用后即复位"的模式保证了后续绘制不受透明度污染）。第三步绘制五扇区------从 -Math.PI/2（12 点方向）开始顺时针，每个扇区的角度由 PIE_DATA[i].val / 100 * 2π 计算，moveTo 移到圆心后 arc 画弧，fill 填色。扇区中心位置通过 Math.cos(mid) * r * 0.72 计算偏移量并 fillText 标注百分比。第四步绘制中心镂空圆------半径 r * 0.58，填充卡片底色，形成环形图的中心镂空效果。第五步在镂空区域中心绘制馆藏总量数字和"馆藏纹样件"标签。呼吸效果通过 r = 66 + (this.breath ? 4 : 0) 实现------每秒半径在 66 与 70 间交替，形成微妙的"呼吸"缩放。
9.5 月度柱状图卡片
typescript
@Builder
chartCard() {
Column({ space: 10 }) {
Row() {
Text('📊 纹样素材月度成交量').fontSize(13).fontWeight(FontWeight.Bold)
.fontColor(COLORS.title)
Blank()
Text('单位：件').fontSize(9).fontColor(COLORS.text3)
}.width('100%')
Row({ space: 6 }) {
ForEach(MONTH_IDX, (i: number) => {
Column({ space: 4 }) {
Text(`${DOWNLOAD_VAL[i]}`).fontSize(8).fontColor(COLORS.text3)
.fontFamily('monospace')
Column()
.width('64%')
.height(this.barHeight(i))
.borderRadius(4)
.linearGradient({
angle: 180,
colors: [[COLORS.red, 0], [COLORS.redD, 1]]
})
Text(MONTH_NAME[i]).fontSize(9).fontColor(COLORS.sub)
}.layoutWeight(1).alignItems(HorizontalAlign.Center)
}, (i: number) => `bar_${i}_${this.breath}`)
}.width('100%').alignItems(VerticalAlign.Bottom).height(132)
}.padding(14).borderRadius(12).backgroundColor(COLORS.card).width('100%')
}月度柱状图采用 Column + ForEach 的传统实现方式（非 Canvas 自绘）。每根柱子是一个 Column 容器，内部从上到下依次是数值文字、柱体和月份标签。柱体通过 height(this.barHeight(i)) 动态设置高度，并使用 linearGradient 以 180 度角从朱砂渐变到深朱砂。barHeight 方法的实现是 const wave = (i % 2 === 0) === this.breath ? 1.06 : 0.94，即奇偶柱在 breath 翻转时交替放大和缩小 6%，形成波浪般的呼吸节奏。ForEach 的键值生成器拼接了 this.breath，使得呼吸状态变化时键值改变，触发柱子重新渲染。
十、频道 Tab 深度分析
10.1 嵌套模式切换与位置指示
typescript
@Builder
tabNested() {
Column({ space: 10 }) {
Row({ space: 8 }) {
Text(`嵌套模式：${modeLabel(this.nestedMode)}`)
.fontSize(11).fontColor(COLORS.sub).layoutWeight(1)
.maxLines(1).textOverflow({ overflow: TextOverflow.Ellipsis })
ForEach([TabsNestedScrollMode.SELF_ONLY, TabsNestedScrollMode.SELF_FIRST],
(m: TabsNestedScrollMode) => {
Text(modeShort(m)).fontSize(10)
.padding({ left: 10, right: 10, top: 5, bottom: 5 }).borderRadius(12)
.fontColor(this.nestedMode === m ? COLORS.onMain : COLORS.text3)
.backgroundColor(this.nestedMode === m ? COLORS.red : COLORS.card)
.onClick(() => { this.nestedMode = m; })
}, (m: TabsNestedScrollMode) => `mode_${m}`)
}.width('100%')
Row({ space: 6 }) {
Circle({ width: 6, height: 6 }).fill(COLORS.gold)
Text(`外层 ${OUTER_CHANNELS[this.outerIndex].name}代频道`)
.fontSize(10).fontColor(COLORS.sub)
Blank()
Circle({ width: 6, height: 6 }).fill(COLORS.green)
Text(`内层 ${INNER_TABS[this.innerIndex]}（第 ${this.innerIndex + 1}/5 页）`)
.fontSize(10).fontColor(COLORS.sub)
}.width('100%')频道 Tab 顶部是嵌套模式切换区。左侧文案通过 modeLabel 显示当前模式的完整名称，右侧两个 chips 允许用户在 SELF_ONLY（仅内层）和 SELF_FIRST（先内后外）间切换。SELF_ONLY 模式下内层 Tabs 滑到边缘后不联动外层，适合在单一纹样类别内深度浏览；SELF_FIRST 模式下内层滑到边缘后继续滑动会触发外层朝代频道切换，适合跨朝代横向浏览。下方位置指示行以鎏金圆点标注外层朝代频道、苔绿圆点标注内层纹样类别，实时反映当前双层位置。
10.2 外层朝代 Tabs 与内层嵌套 Tabs
typescript
Tabs({ barPosition: BarPosition.Start }) {
ForEach(OUTER_CHANNELS, (ch: ChannelItem) => {
TabContent() {
this.innerTabs(ch)
}.tabBar(`${ch.icon} ${ch.name}`)
}, (ch: ChannelItem) => ch.name)
}
.barMode(BarMode.Scrollable)
.onChange((index: number) => {
this.swipeLogs.unshift(new SwipeLog('外层朝代', OUTER_CHANNELS[index].name,
this.outerIndex, index, modeLabel(this.nestedMode)));
this.outerIndex = index;
if (this.swipeLogs.length > 40) { this.swipeLogs.pop(); }
})
.layoutWeight(1).width('100%')外层 Tabs 以 5 个朝代频道为页签，barMode(BarMode.Scrollable) 让页签支持横向滚动。每个 TabContent 内部调用 innerTabs(ch) 渲染内层嵌套 Tabs。onChange 回调在外层翻页时触发，创建 SwipeLog 记录（层级为"外层朝代"、页名为目标朝代、起始索引为 outerIndex、目标索引为 index、模式为当前 nestedMode），unshift 置顶到日志列表，超过 40 条时 pop 裁剪尾部。
typescript
@Builder
innerTabs(channel: ChannelItem) {
Tabs({ barPosition: BarPosition.Start }) {
ForEach(INNER_TABS, (name: string) => {
TabContent() {
List({ space: 10 }) {
ForEach(innerMockData(channel, name), (item: InnerCard) => {
ListItem() {
Column({ space: 6 }) {
Row() {
Text(`${channel.icon} ${name}纹`).fontSize(13)
.fontWeight(FontWeight.Bold).fontColor(COLORS.title)
Blank()
Text(item.tag).fontSize(10).fontColor(COLORS.sub)
}.width('100%')
Text(item.title).fontSize(12).fontColor(COLORS.sub).maxLines(1)
.textOverflow({ overflow: TextOverflow.Ellipsis })
Text(item.desc).fontSize(11).fontColor(COLORS.text3).maxLines(2)
.textOverflow({ overflow: TextOverflow.Ellipsis })
Row({ space: 8 }) {
Text(`${channel.name}代频道`).fontSize(9).fontColor(COLORS.gold)
.padding({ left: 5, right: 5, top: 1, bottom: 1 }).borderRadius(4)
Text('可商用授权').fontSize(9).fontColor(COLORS.green)
.padding({ left: 5, right: 5, top: 1, bottom: 1 }).borderRadius(4)
}.width('100%')
}.width('100%').padding(12).borderRadius(10).backgroundColor(COLORS.card)
}
}, (item: InnerCard) => item.id)
}.width('100%').height('100%').scrollBar(BarState.Off)
}.tabBar(name)
}, (name: string) => name)
}
.barMode(BarMode.Scrollable)
.onChange((index: number) => {
this.swipeLogs.unshift(new SwipeLog('内层类别', INNER_TABS[index],
this.innerIndex, index, modeLabel(this.nestedMode)));
this.innerIndex = index;
if (this.swipeLogs.length > 40) { this.swipeLogs.pop(); }
})
.nestedScroll(this.nestedMode)
.layoutWeight(1).width('100%')
}内层 Tabs 是嵌套滚动的核心挂载点。.nestedScroll(this.nestedMode) 是 API 24 新增方法，它将当前 Tabs 标记为"可被外层 Tabs 接管的内层滚动容器"。当 nestedMode 为 SELF_FIRST 时，内层列表滑到边缘后继续滑动会触发外层 Tabs 的 onChange，实现"先内后外"的接力滚动；当 nestedMode 为 SELF_ONLY 时，内层滑到边缘即停止，不联动外层。每个内层 TabContent 包含一个 8 条卡片的 List，内容超过一屏以保证滚动效果可感知。卡片底部标注朝代频道（鎏金）和"可商用授权"（苔绿）两个标签。
十一、日志 Tab 深度分析
typescript
@Builder
tabLogs() {
Column({ space: 10 }) {
Row() {
Text(`已记录 ${this.swipeLogs.length} 次翻页`).fontSize(13)
.fontWeight(FontWeight.Bold).fontColor(COLORS.title)
Blank()
Button('清空日志')
.fontSize(11).height(32).borderRadius(10)
.fontColor(COLORS.sub).backgroundColor(COLORS.chip)
.enabled(this.swipeLogs.length > 0)
.onClick(() => { this.clearLogs(); })
}.width('100%')
Row({ space: 12 }) {
Row({ space: 5 }) {
Circle({ width: 6, height: 6 }).fill(COLORS.gold)
Text('外层朝代翻页').fontSize(9).fontColor(COLORS.sub)
}
Row({ space: 5 }) {
Circle({ width: 6, height: 6 }).fill(COLORS.green)
Text('内层类别翻页').fontSize(9).fontColor(COLORS.sub)
}
Blank()
Text(`当前 ${modeLabel(this.nestedMode)}`).fontSize(9).fontColor(COLORS.text3)
.maxLines(1).textOverflow({ overflow: TextOverflow.Ellipsis })
}.width('100%')日志 Tab 以时间轴形式展示频道 Tab 的翻页记录。顶部标题行显示已记录的翻页次数和清空按钮（日志为空时禁用）。图例行以鎏金圆点标注"外层朝代翻页"、苔绿圆点标注"内层类别翻页"，右侧显示当前嵌套模式完整文案。这一设计让用户在浏览日志时无需回到频道 Tab 即可了解当前模式状态。
typescript
if (this.swipeLogs.length === 0) {
Column({ space: 8 }) {
Text('📜').fontSize(30)
Text('暂无翻页记录').fontSize(12).fontColor(COLORS.sub)
Text('去「频道」页滑动外层朝代或内层纹样类别，每一次翻页都会记入时间轴')
.fontSize(10).fontColor(COLORS.text3).textAlign(TextAlign.Center)
}.width('100%').padding({ top: 40, bottom: 40 }).borderRadius(12)
.backgroundColor(COLORS.card)
} else {
List() {
ForEach(this.swipeLogs, (log: SwipeLog) => {
ListItem() {
Row() {
Column({ space: 4 }) {
Text(log.time).fontSize(10).fontWeight(FontWeight.Bold)
.fontColor(layerColor(log.layer)).fontFamily('monospace')
Text(log.layer === '外层朝代' ? '朝代' : '类别').fontSize(8)
.fontColor(COLORS.text3)
}.width(48).height('100%').justifyContent(FlexAlign.Center)
Column() {
Circle({ width: 10, height: 10 }).fill(layerColor(log.layer))
Column().width(2).layoutWeight(1).backgroundColor(COLORS.line)
}.width(14).height('100%').alignItems(HorizontalAlign.Center)
Column({ space: 4 }) {
Row({ space: 6 }) {
Text(log.tabName).fontSize(12).fontWeight(FontWeight.Bold)
.fontColor(COLORS.title)
Text(`第 ${log.fromIdx + 1} → ${log.toIdx + 1} 页`).fontSize(10)
.fontColor(COLORS.sub).fontFamily('monospace')
}.width('100%')
Text(`事发模式：${log.mode}`).fontSize(9).fontColor(COLORS.text3)
.maxLines(1).width('100%')
.textOverflow({ overflow: TextOverflow.Ellipsis })
Text(log.layer === '外层朝代' ? '外层朝代频道 TabContent 切换' : '内层纹样类别 TabContent 切换')
.fontSize(9).fontColor(COLORS.text3)
}.layoutWeight(1).height('100%').justifyContent(FlexAlign.Center)
.padding({ left: 10, right: 10, top: 8, bottom: 8 })
.borderRadius(10).backgroundColor(COLORS.card)
}.width('100%').height(72).margin({ bottom: 6 })
}
}, (log: SwipeLog) => `${log.time}_${log.tabName}_${log.toIdx}`)
}.scrollBar(BarState.Off).width('100%').layoutWeight(1)
}空态和有数据态的分支渲染保证了用户体验的完整性。空态展示引导文案，指引用户前往频道页操作。有数据态使用 List 渲染时间轴，每条日志固定行高 72vp，内部三列布局：时间列（固定宽 48vp，显示时间和层级短名）、竖线轨道列（固定宽 14vp，圆点徽标 + layoutWeight(1) 填满行高的竖线）、事件卡片列（弹性宽度，展示页名、翻页索引变化和事发模式）。竖线轨道的设计精妙之处在于使用 Column().width(2).layoutWeight(1) 让竖线在固定行高内自动填满，形成连续的时间轴视觉效果。圆点颜色通过 layerColor 函数区分层级------鎏金为外层朝代、苔绿为内层类别。
十二、工坊 Tab 深度分析
12.1 参数卡与纹理选择
typescript
@Builder
tabStudio() {
Column({ space: 10 }) {
Scroll() {
Column({ space: 10 }) {
Column({ space: 8 }) {
Text('样图参数').fontSize(12).fontWeight(FontWeight.Bold).fontColor(COLORS.title)
Row({ space: 8 }) {
this.paramChip('画布', `${CANVAS_SIZE}×${CANVAS_SIZE}`)
this.paramChip('质量', `${WEBP_QUALITY}`)
this.paramChip('纹理', TEXTURES[this.textureIdx].label)
}.width('100%')
Text('色板：朱砂 / 黛蓝 / 鎏金 / 苔绿 / 深朱砂 五色非遗色')
.fontSize(9).fontColor(COLORS.text3).width('100%')
}.padding(10).borderRadius(12).backgroundColor(COLORS.card).width('100%')
Column({ space: 8 }) {
Text('纹理五选一（像素算法 × 纹样语义）').fontSize(12)
.fontWeight(FontWeight.Bold).fontColor(COLORS.title)
Scroll() {
Row({ space: 8 }) {
ForEach(TEXTURES, (t: TextureItem, idx: number) => {
Text(`${t.label}·${t.name}`).fontSize(11)
.fontColor(this.textureIdx === idx ? COLORS.onMain : COLORS.sub)
.padding({ left: 12, right: 12, top: 7, bottom: 7 })
.borderRadius(14)
.backgroundColor(this.textureIdx === idx ? COLORS.red : COLORS.chip)
.onClick(() => { this.textureIdx = idx; })
}, (t: TextureItem) => `tex_${t.key}`)
}.padding({ left: 4, right: 4 })
}.scrollable(ScrollDirection.Horizontal).scrollBar(BarState.Off).width('100%')
Text(`${TEXTURES[this.textureIdx].label}对应「${TEXTURES[this.textureIdx].name}」：${TEXTURES[this.textureIdx].desc}`)
.fontSize(9).fontColor(COLORS.text3).width('100%')
}.padding(10).borderRadius(12).backgroundColor(COLORS.card).width('100%')工坊 Tab 顶部是参数卡，通过 paramChip Builder 渲染三个小胶囊------画布尺寸（96×96）、编码质量（90）、当前纹理标签。纹理五选一区使用横向滚动 Scroll 包裹 5 个 chips，选中态为朱砂底白字。选中纹理的寓意图文动态拼接，展示纹理标签、对应纹样名和文化寓意的完整说明。
12.2 WebP 生成链路
typescript
async genWebpFile() {
this.genState = '生成中...';
const hostCtx = this.getUIContext().getHostContext();
const dir = hostCtx ? hostCtx.filesDir : '';
if (dir === '') {
this.genState = '生成失败(无沙箱)';
this.opLogs.unshift(new MetaOpLog('生成样图', '失败：未取到宿主 Context 的 filesDir'));
return;
}
try {
const texture = TEXTURES[this.textureIdx];
const total = CANVAS_SIZE * CANVAS_SIZE;
const buf = new ArrayBuffer(total * 4);
const pixels = new Uint32Array(buf);
for (let i = 0; i < total; i++) {
const row = Math.floor(i / CANVAS_SIZE);
const col = i % CANVAS_SIZE;
pixels[i] = pixelColor(row, col, texture.key, WEBP_PALETTE);
}
const opts: image.InitializationOptions = {
size: { width: CANVAS_SIZE, height: CANVAS_SIZE },
pixelFormat: image.PixelMapFormat.RGBA_8888
};
const pm = await image.createPixelMap(buf, opts);
this.pixelMap = pm;
const packer = image.createImagePacker();
const webpBuf = await packer.packToData(pm, { format: 'image/webp', quality: WEBP_QUALITY });
await packer.release();
const path = `${dir}/pattern_sample.webp`;
const file = fileIo.openSync(path,
fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE | fileIo.OpenMode.TRUNC);
fileIo.writeSync(file.fd, webpBuf);
fileIo.closeSync(file);
this.webpPath = path;
this.genState = `已生成 ${(webpBuf.byteLength / 1024).toFixed(1)}KB`;
this.opLogs.unshift(new MetaOpLog('生成样图',
`${CANVAS_SIZE}×${CANVAS_SIZE} ${texture.label}（${texture.name}）像素画编码为 WebP 并落盘`));
} catch (e) {
const err = e as BusinessError;
this.genState = `生成失败(${err.code})`;
this.opLogs.unshift(new MetaOpLog('生成样图', `失败：code ${err.code}，${err.message}`));
}
}genWebpFile 是 WebP 样图生成的完整链路。首先通过 getUIContext().getHostContext() 获取宿主 Context 的 filesDir 沙箱目录。然后分配 CANVAS_SIZE * CANVAS_SIZE * 4 字节的 ArrayBuffer，以 Uint32Array 视图逐像素写入------通过 pixelColor 函数按纹理算法和五色非遗色板计算每个像素的 RGBA 值。接着调用 image.createPixelMap 将像素缓冲区转为 PixelMap 对象（格式为 RGBA_8888），再通过 image.createImagePacker().packToData 以 image/webp 格式和质量 90 编码为 WebP 字节流。packer 用后必须 release() 释放资源。最后通过 fileIo.openSync 以 READ_WRITE | CREATE | TRUNC 模式打开沙箱文件，writeSync 写入 WebP 字节流，closeSync 关闭文件。整个过程中任何步骤失败都会被 catch 捕获，通过 BusinessError 提取错误码和消息写入操作日志。
十三、元数据 Tab 深度分析
13.1 读取元数据
typescript
async readMeta() {
if (this.webpPath === '') {
this.opLogs.unshift(new MetaOpLog('读取元数据', '请先在「工坊」生成 WebP 样图'));
return;
}
try {
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);
await source.release();
fileIo.closeSync(file);
this.opLogs.unshift(new MetaOpLog('读取元数据',
`画布 ${this.metaSnapshot!.canvasWidth}×${this.metaSnapshot!.canvasHeight}，` +
`帧延迟 ${fmtField(this.metaSnapshot!.delayTime, 'ms')}，` +
`循环 ${fmtField(this.metaSnapshot!.loopCount, ' 次')}`));
} catch (e) {
const err = e as BusinessError;
this.opLogs.unshift(new MetaOpLog('读取元数据', `失败：code ${err.code}，${err.message}`));
}
}readMeta 通过 readImageMetadataByType 读取 WebP 元数据。首先以 READ_WRITE 模式打开沙箱文件，通过 file.fd（文件描述符）创建 ImageSource。然后声明元数据类型数组 [image.MetadataType.WEBP_METADATA]，调用 source.readImageMetadataByType(types, 0) 读取------第二个参数 0 是帧索引，静态 WebP 取 0。返回的 meta.webPMetadata 对象包含五个可选字段，全部使用 ?? -1 空值合并兜底，避免 undefined 污染后续逻辑。快照创建后 release() 释放 ImageSource 资源，closeSync 关闭文件。操作日志记录画布尺寸、帧延迟和循环次数的摘要。
13.2 写入元数据与回读校验
typescript
async writeMeta() {
if (this.webpPath === '') {
this.opLogs.unshift(new MetaOpLog('写入元数据', '请先在「工坊」生成 WebP 样图'));
return;
}
try {
const file = fileIo.openSync(this.webpPath, fileIo.OpenMode.READ_WRITE);
const source = image.createImageSource(file.fd);
const webpMeta = {
canvasWidth: CANVAS_SIZE,
canvasHeight: CANVAS_SIZE,
delayTime: this.writeDelay,
unclampedDelayTime: this.writeDelay,
loopCount: this.writeLoop
} as image.WebPMetadata;
const meta: image.ImageMetadata = { webPMetadata: webpMeta };
await source.writeImageMetadata(meta);
await source.release();
fileIo.closeSync(file);
this.opLogs.unshift(new MetaOpLog('写入元数据',
`帧延迟=${this.writeDelay}ms，循环=${this.writeLoop === 0 ? '不限' : this.writeLoop} 次`));
await this.verifyRead();
} catch (e) {
const err = e as BusinessError;
this.opLogs.unshift(new MetaOpLog('写入元数据',
`失败：code ${err.code}，${err.message}（7700202=不支持，7700204=参数非法）`));
}
}writeMeta 通过 writeImageMetadata 写回五字段元数据。写回的对象使用 as image.WebPMetadata 类型断言------这是官方样例推荐的模式，因为 WebPMetadata 的所有字段都是可选的，对象字面量可以安全断言。canvasWidth 和 canvasHeight 写入固定值 CANVAS_SIZE（96），delayTime 和 unclampedDelayTime 写入用户选择的帧延迟值，loopCount 写入用户选择的循环次数。写回后立即调用 verifyRead() 进行回读校验。错误码注释中标注了常见错误：7700202 表示格式不支持，7700204 表示参数非法。
typescript
async verifyRead() {
try {
const file = fileIo.openSync(this.webpPath, fileIo.OpenMode.READ_WRITE);
const source = image.createImageSource(file.fd);
const meta = await source.readImageMetadataByType([image.MetadataType.WEBP_METADATA], 0);
const webp = meta.webPMetadata;
this.verifySnapshot = new WebpMetaSnapshot(
webp?.canvasWidth ?? -1, webp?.canvasHeight ?? -1,
webp?.delayTime ?? -1, webp?.unclampedDelayTime ?? -1,
webp?.loopCount ?? -1);
await source.release();
fileIo.closeSync(file);
const ok = this.verifySnapshot!.delayTime === this.writeDelay
&& this.verifySnapshot!.loopCount === this.writeLoop;
this.opLogs.unshift(new MetaOpLog('回读校验',
ok ? '已生效：delayTime/loopCount 与写入值一致'
: `差异：delayTime=${fmtField(this.verifySnapshot!.delayTime, 'ms')}，` +
`loopCount=${fmtField(this.verifySnapshot!.loopCount, ' 次')}`));
} catch (e) {
const err = e as BusinessError;
this.opLogs.unshift(new MetaOpLog('回读校验', `失败：code ${err.code}，${err.message}`));
}
}verifyRead 重建 ImageSource 二次读取元数据，与写入值进行比对校验。这一步是"写回有效性验证"的关键------重新 createImageSource 打开文件，再次 readImageMetadataByType 读取，将回读的 delayTime 和 loopCount 与用户写入的值比对。如果一致则日志标记"已生效"，不一致则标记"差异"并显示回读到的实际值。这种"写入→回读→比对"的三步链路是元数据操作可靠性的终极保障。
13.3 元数据快照卡与操作日志流
typescript
@Builder
metaCard(title: string, snap: WebpMetaSnapshot, highlight: boolean) {
Column({ space: 6 }) {
Row() {
Text(title).fontSize(12).fontWeight(FontWeight.Bold).fontColor(COLORS.title)
Blank()
Text(highlight ? '回读值' : '快照值').fontSize(9)
.fontColor(highlight ? COLORS.green : COLORS.text3)
}.width('100%')
this.metaRow('canvasWidth', sizeText(snap.canvasWidth))
this.metaRow('canvasHeight', sizeText(snap.canvasHeight))
this.metaRow('delayTime', fmtField(snap.delayTime, 'ms'))
this.metaRow('unclampedDelayTime', fmtField(snap.unclampedDelayTime, 'ms'))
this.metaRow('loopCount', loopText(snap.loopCount))
}.padding(10).borderRadius(12).width('100%')
.backgroundColor(COLORS.card)
.border({ width: 1, color: highlight ? COLORS.green : COLORS.line })
}metaCard 是元数据五字段快照的通用渲染 Builder，同时服务读取快照和回读校验快照。highlight 参数控制视觉差异------回读校验卡使用苔绿色描边和高亮标签，读取快照卡使用普通灰色描边。五字段通过 metaRow 逐行渲染，字段名和值均使用 monospace 字体保证等宽对齐。值通过 sizeText（像素尺寸）、fmtField（数值带单位）和 loopText（循环次数特殊处理）三个格式化函数统一处理"未提供"兜底。
十四、我的 Tab 深度分析
typescript
@Builder
tabMine() {
Column({ space: 10 }) {
Scroll() {
Column({ space: 10 }) {
Column({ space: 12 }) {
Row({ space: 12 }) {
Text('🧧').fontSize(38)
Column({ space: 4 }) {
Text('匠纹库 · 年度守艺人').fontSize(16).fontWeight(FontWeight.Bold)
.fontColor(COLORS.onMain)
Text('LV6 金纹匠 · ID Pattern-Keeper-1223').fontSize(10)
.fontColor(COLORS.onMain).opacity(0.85)
}.alignItems(HorizontalAlign.Start).layoutWeight(1)
Circle({ width: 8, height: 8 }).fill(COLORS.gold)
.opacity(this.breath ? 0.9 : 0.45)
}.width('100%')
Row({ space: 8 }) {
this.statBig('收藏纹样', '38', '套', COLORS.onMain)
this.statBig('累计下载', '1260', '次', COLORS.gold)
this.statBig('守艺工分', '8920', '分', COLORS.green)
}.width('100%')
Text('年度共建任务 68/100 · 距离「御纹匠」还差 32 项')
.fontSize(9).fontColor(COLORS.onMain).opacity(0.85).width('100%')
}.padding(14).borderRadius(14).width('100%')
.linearGradient({
angle: 135,
colors: [[COLORS.gradA, 0], [COLORS.gradB, 1]]
})我的 Tab 以会员渐变大卡为核心。大卡使用 linearGradient 以 135 度角从朱砂渐变到深朱砂，形成浓郁的文化质感。顶部行展示会员等级标识（🧧 红包图标 + "年度守艺人"标题 + LV6 等级和 ID），右侧鎏金圆点随 breath 呼吸翻转透明度。中间三列战绩通过 statBig Builder 渲染------收藏纹样 38 套（白字）、累计下载 1260 次（鎏金字）、守艺工分 8920 分（苔绿字），三色对应三种业务语义。底部进度文案显示年度共建任务完成度（68/100）和距下一等级的差距。
typescript
Column() {
ForEach(MINE_TASKS, (task: MineTask) => {
Row({ space: 10 }) {
Text(task.icon).fontSize(16)
Column({ space: 3 }) {
Text(task.label).fontSize(12).fontColor(COLORS.title).maxLines(1).width('100%')
.textOverflow({ overflow: TextOverflow.Ellipsis })
Text(task.hint).fontSize(9).fontColor(COLORS.text3)
}.alignItems(HorizontalAlign.Start).layoutWeight(1)
Text(task.done ? '已完成' : '待办').fontSize(9)
.fontColor(COLORS.onMain)
.padding({ left: 8, right: 8, top: 3, bottom: 3 }).borderRadius(8)
.backgroundColor(task.done ? COLORS.green : COLORS.gold)
}.padding({ top: 12, bottom: 12, left: 12, right: 12 }).width('100%')
}, (task: MineTask) => task.label)
}.borderRadius(12).backgroundColor(COLORS.card).width('100%')创作任务清单以 6 行列表呈现守艺人的年度任务。每行包含任务图标、任务名和工分奖励（左列）以及完成状态标签（右列）。完成态以苔绿底白字"已完成"呈现，待办态以鎏金底白字"待办"呈现，形成与会员大卡三列战绩的色彩呼应。
十五、弹窗系统
15.1 弹窗遮罩与三态分发
typescript
@Builder
modalOverlay(onClose: () => void) {
Column() {
Column().width('100%').layoutWeight(1)
.onClick(() => { onClose(); })
if (this.addModal) {
this.panelAdd(onClose)
} else if (this.editModal) {
this.panelEdit(onClose)
} else if (this.delModal) {
this.panelDel(onClose)
}
}.width('100%').height('100%').backgroundColor(COLORS.mask)
.justifyContent(FlexAlign.End)
}modalOverlay 是弹窗系统的统一入口。Stack 层叠布局使其覆盖全页，backgroundColor 设为墨褐半透遮罩。Column 内部分为两部分：上方空白遮罩区（layoutWeight(1) 填满剩余空间，点击关闭弹窗），下方弹窗面板（通过三态 if-else 链分发到 panelAdd、panelEdit、panelDel）。justifyContent(FlexAlign.End) 将面板推到屏幕底部，形成从底部弹出的面板效果。
15.2 新建纹样收藏弹窗
typescript
@Builder
panelAdd(onClose: () => void) {
Column({ space: 12 }) {
Text('新建纹样收藏').fontSize(15).fontWeight(FontWeight.Bold)
.fontColor(COLORS.title)
Text('输入纹样名后会置顶到素材列表首位，朝代跟随当前筛选，品类默认回纹')
.fontSize(10).fontColor(COLORS.text3).width('100%')
TextInput({ placeholder: '输入纹样名，如：北魏忍冬纹' })
.fontSize(12).height(40)
.fontColor(COLORS.title)
.placeholderColor(COLORS.text3)
.backgroundColor(COLORS.chip)
.onChange((value: string) => { this.inputText = value; })
Row({ space: 10 }) {
Button('取消')
.fontSize(12).height(38).borderRadius(10)
.fontColor(COLORS.sub).backgroundColor(COLORS.chip)
.layoutWeight(1)
.onClick(() => { onClose(); })
Button('收藏')
.fontSize(12).height(38).borderRadius(10)
.fontColor(COLORS.onMain).backgroundColor(COLORS.red)
.layoutWeight(1)
.onClick(() => { this.confirmAdd(); })
}.width('100%')
}.padding(16).borderRadius({ topLeft: 16, topRight: 16 })
.backgroundColor(COLORS.card).width('100%')
}新建弹窗包含标题、说明文案、输入框和取消/收藏双按钮。TextInput 的 onChange 回调实时更新 inputText 状态。"收藏"按钮调用 confirmAdd()，该方法将输入的纹样名以 PatternItem 实例 unshift 到素材列表顶部------朝代跟随当前筛选条件（若"全部"则默认"唐"），品类默认"回纹"，评分设为 82 分。面板使用 borderRadius({ topLeft: 16, topRight: 16 }) 仅圆角顶部两角，模拟从底部滑入的面板形态。
15.3 编辑与删除弹窗
编辑弹窗 panelEdit 在打开时通过 openEdit 预填入当前纹样的用途描述到 inputText，用户修改后点击"保存"调用 confirmEdit()，将新文案赋值到 patternList[editIdx].uses。由于 PatternItem 使用 @Observed 装饰，属性赋值会自动触发绑定的素材卡片重新渲染。删除弹窗 panelDel 展示确认文案，"删除"按钮调用 confirmDel()，通过 splice 从列表中移除指定条目。删除按钮使用 COLORS.redD（深朱砂）背景以强化危险操作的视觉警示。
十六、功能模块对比表
| 功能模块 | 技术特性 | 核心接口/方法 | 数据模型 | 交互模式 | 视觉特色 |
|---|---|---|---|---|---|
| 素材馆 | Canvas 自绘 | drawPie / arc / fillText | PatternItem | 朝代筛选+双列卡片 | 环形图呼吸微动+柱状图奇偶波动 |
| 频道 | Tabs 嵌套滚动 | nestedScroll / onChange | InnerCard | 双层 Tabs 嵌套+模式切换 | 朝代×纹样矩阵+接力滚动 |
| 日志 | 时间轴渲染 | SwipeLog / layerColor | SwipeLog | 翻页事件时间轴 | 固定行高72+竖线轨道+双色徽标 |
| 工坊 | ImageKit 编码 | createPixelMap / packToData | TextureItem | 纹理五选一+生成落盘 | 像素画预览+沙箱路径展示 |
| 元数据 | ImageKit 读写 | readImageMetadataByType / writeImageMetadata | WebpMetaSnapshot | 读取→写入→回读校验 | 五字段快照卡+高亮校验描边 |
| 我的 | 渐变大卡 | statBig / linearGradient | MineTask | 会员卡+任务清单 | 朱砂渐变+三列战绩+呼吸圆点 |
| 弹窗系统 | 三态统一 | modalOverlay / panelAdd / panelEdit / panelDel | PatternItem | 底部弹出面板+遮罩关闭 | 墨褐半透遮罩+顶部圆角面板 |
深化解析：从代码结构到业务闭环
布局方式与数据流
非遗文博页面既要体现文化内容，也要维护年代、类别、来源与处理记录。素材馆或首页负责概览，地图和搜索提供空间探索，网页与下载承接外部资料，工坊和元数据页面支持数字化加工。逐段分析应关注朝代筛选、等级配色、双列卡片、地图事件和元数据日志之间的数据关系，避免只解释组件属性而忽略文化资产的流转。
页面根结构通常由头部、内容区和底部 Tab 栏组成。头部负责展示当前业务状态，内容区根据索引选择不同的 @Builder，底部导航负责修改索引。这样的结构把"当前显示什么"收敛为一个明确状态：用户点击 Tab 后先更新索引，ArkUI 再重新计算相关分支。各个 Builder 虽然共享主题色和页面级数据，却可以采用完全不同的布局方式；高密度列表适合纵向 Scroll，概览数据适合横向统计卡或双列 Flex，实时预览类组件需要独占有界高度，历史事件则适合时间轴或固定行高 List。
数据模型层承担界面与业务之间的契约。使用 @Observed 的实体保存可编辑字段，页面级 @State 数组负责驱动 ForEach。新增时创建新实体并插入数组，编辑时修改目标实体，删除时移除对应项。为了让列表差分稳定，key 应来自不会改变的唯一标识，不宜使用标题等可编辑字段。统计数字、完成比例和分类数量属于派生信息，可以从数组即时计算，避免同时维护两份状态后出现卡片已经更新、图表仍显示旧值的情况。
弹窗表单使用独立缓存是必要的。打开新增弹窗时清空缓存，打开编辑弹窗时复制目标字段，用户确认后才写回正式模型。这样点击取消不会污染列表数据。若直接把 TextInput 双向绑定到列表实体，用户尚未保存时卡片就可能跟着变化，破坏"确认提交"的交互语义。删除弹窗还需要保存目标索引或唯一标识，并在确认时再次校验目标存在，避免列表变化后误删其他项。
核心代码与状态驱动机制
@State 的价值不是简单替代普通变量，而是建立状态与界面之间的依赖关系。当前 Tab、筛选条件、动画开关、弹窗显隐、下载进度或能力状态发生变化时，只有读取这些变量的组件需要刷新。代码段中连续的修饰器调用分别控制尺寸、间距、背景、字体和事件，它们共同构成声明式描述；阅读时应从容器方向、子项分布、状态绑定和交互回调四个层面理解，而不是逐个孤立翻译属性名称。
ForEach 负责把数组映射为重复 UI。回调中的 item 提供业务字段，index 适合显示顺序，但不适合作为长期身份。列表发生新增或删除时，稳定 key 可以让框架复用未变化节点，减少重建。若直接修改对象属性后界面没有按预期刷新，可在保持实体身份的前提下替换数组引用；但不应为了刷新把所有元素都重新构造，否则会增加无意义渲染并丢失局部状态。
条件渲染体现了页面状态机。空闲时展示引导，准备中展示进度，成功时展示结果，失败时展示原因和重试入口。相比一个布尔值，四态文案更能覆盖异步能力。系统接口调用前先检查权限、设备支持和会话状态，调用后再读取结果校验。异常处理除了记录错误码，还要把可理解的反馈写入响应式状态，让用户知道失败发生在哪一步。
动画效果与颜色使用策略
呼吸动画通常由定时器周期翻转 breath，再把该状态映射为透明度、柱高或圆点半径的小幅变化。它适合表达"正在运行"或让统计图保持生命感，但幅度应克制，不能改变核心数据含义。柱状图的基础高度仍由真实数值计算，动画只能在很小范围内偏移；进度环的角度仍由完成比例决定，不能为了视觉效果显示超过真实进度的结果。页面离开时必须清理定时器，避免后台继续刷新。
颜色常量应按语义使用。主色承担选中态和主要操作，辅助色突出数据或次级动作，绿色表达完成与可用，橙色表达进行中或需要注意，红色只用于失败、逾期和删除等高风险场景。弱文本与分割线降低视觉权重，遮罩色用于聚焦弹窗。颜色不能成为唯一的状态信息，还要配合文字、图标或进度值，保证色觉差异用户也能理解。
渐变更适合头部大卡、核心指标或柱状图，不宜在每个小元素上重复使用。深色主题要检查正文与卡片背景的对比度，浅色主题则要避免辅助文字过淡。选中和未选中 Tab 除颜色差异外，还可以通过字重、图标透明度或底部指示器区分。这样既保持主题统一，又能建立清晰的信息层级。
各 Tab 之间的交互联动
各 Tab 不应只共享一个导航索引，还应围绕业务对象建立必要联动。列表页新增或编辑数据后，头部计数、图表和个人统计要同步更新；网页或地图产生的结果应写入记录模型，供下载、日志或我的页面继续展示；通知、字幕、相机等系统能力的状态应在头部胶囊或对应 Tab 中保持一致。跨 Tab 跳转时先更新必要参数，再修改当前索引，可以避免目标页面读取到旧条件。
切换离开重型组件时需要处理资源边界。相机输入、地图监听、字幕控制器、Web 下载代理和定时器都不能只创建不释放。可以在统一的 switchTab 方法中判断来源与目标，离开能力页时解除监听或停止会话；页面销毁时再执行兜底释放。释放方法应允许重复调用，并对每个资源独立判空，确保一次异常不会阻止后续清理。
交互反馈要覆盖成功与失败。按钮点击后先进入处理中状态并防止重复提交；成功后更新模型、关闭弹窗并显示结果；失败后保留用户输入，展示错误原因和重试入口。权限拒绝、能力不支持、网络失败、文件不存在和输入非法都属于正常业务分支。通过状态卡或行内提示展示这些分支，比只在控制台打印更符合完整产品体验。
边界场景与验证思路
空列表时应显示占位说明和新增入口，不能只留下空白。长标题需要限制行数并使用省略号，数字字段需要限定上下界，文本提交前要去除首尾空格。筛选后无结果应保留清除条件的入口。删除最后一项后，当前选择索引要回退到有效范围。异步搜索连续触发时，应防止较早请求晚返回后覆盖新结果。
验证数据链路时，可以依次检查新增、编辑、删除和筛选：新增后列表条数、统计数字和图表是否同时变化；编辑取消后正式数据是否保持不变；删除后 ForEach key 是否稳定；切换 Tab 再返回时必要数据是否仍在。验证系统能力时分别模拟支持、拒绝和异常，确认界面都有明确状态。验证动画时检查页面离开后是否停止，低性能设备上是否仍保持流畅。
视觉验收需要检查不同屏幕宽度、系统字体放大、深浅背景对比和长文本换行。表格中的布局方式、模型、字段数、核心操作、动画、状态颜色、数据量和特殊组件应与正文一致。Mermaid 图则需要对应真实的数据流和能力链路，节点文字加引号以避免中文或特殊字符导致解析失败。
组件化设计的进一步理解
参数化 Builder 适合抽取重复的统计格、状态行、标签和按钮组。参数只传入渲染所需数据和事件，不让子构建器直接依赖过多页面变量，可以降低耦合。业务复杂后，可把模型与系统能力封装为独立控制器，页面只负责组合 UI 和响应状态。这样既保留声明式代码的直观性，也能让权限、错误码翻译和资源释放得到集中管理。
当前单页面集中展示完整源码，便于博文逐段讲解。若演进为正式项目，可以按领域拆分组件：导航和页面框架位于容器层，列表、图表和弹窗位于展示层，数据读写和 Kit 接入位于服务层。组件之间通过参数、回调、@Link 或 @ObjectLink 传递状态，不使用全局变量代替清晰的数据流。
性能优化首先来自减少不必要刷新。派生数据不要重复存储，动画状态不要进入列表 key，长列表使用稳定标识，Canvas 只在数据或尺寸变化时重绘。其次是控制资源生命周期，页面不可见时停止高成本任务。最后才是微调阴影、渐变和绘制细节。这样的优先级能保证页面在功能增加后仍然可维护。
通过以上补充，可以看到 ArkUI 的声明式模式并非只让布局语法更简洁，它更重要的价值是把数据变化、界面刷新和交互反馈连接为可追踪链路。理解每个代码段读取什么状态、写入什么状态、影响哪些组件，才能真正掌握文章中多个 Tab、图表、弹窗和系统能力协同工作的原理。
十七、总结与展望
本文深度解析了基于 HarmonyOS ArkUI 框架构建的非遗纹样素材平台，从色彩体系设计到组件化架构，从 Canvas 自绘引擎到 Tabs 嵌套滚动，从 ImageKit WebP 元数据读写到弹窗三态系统，完整呈现了一个文化科技融合项目的工程实践。
技术层面 ，平台的三大特性形成了"可视化-交互-数据"的完整能力闭环。Canvas 自绘环形图通过 setInterval + 手动重绘实现了不依赖 @State 驱动的独立动画系统，globalAlpha 的"用后即复位"模式保证了绘制状态的隔离性。Tabs 嵌套滚动通过 nestedScroll(TabsNestedScrollMode) 实现了内外层滚动的接力传递，SELF_FIRST 与 SELF_ONLY 两种模式覆盖了深度浏览与横向浏览两种用户场景，onChange 回调的日志记录让嵌套滚动的行为变得可观测、可调试。ImageKit WebP 元数据链路展示了"生成→读取→写入→回读校验"的完整沙箱操作范式，?? -1 空值合并兜底策略和 as image.WebPMetadata 类型断言模式为处理可选字段提供了安全实践。
架构层面 ，@Observed 装饰器使得 PatternItem 的属性修改能够自动驱动卡片重渲染，@State + @Builder 的组合实现了状态与视图的声明式绑定，Stack 层叠布局让弹窗遮罩与内容区共享同一渲染树。状态变量的五分组设计（基础 UI、弹窗、素材馆业务、嵌套滚动、WebP 元数据）使得跨 Tab 数据共享与隔离达到了平衡。
文化层面，平台的色彩体系深植于中国传统美学------朱砂正色、宣纸米白、黛蓝青花、鎏金器皿、苔绿竹翠，每一色都有千年文化渊源。纹样五品类（回纹、云纹、方胜、冰裂、联珠）的像素算法映射，让冰冷的数学公式（行列取模、欧氏距离分环）承载了温暖的寓意（福寿绵长、平步青云、同心永续、破冰新生、珠联璧合）。朝代×品类的交叉矩阵构建了一个可遍历的中国纹样知识图谱。
展望未来，平台可在以下方向持续演进。其一，接入端侧 AI 模型实现纹样风格迁移------用户拍摄实物照片后，通过模型推理生成对应朝代风格的纹样变体。其二，引入 AR 展示能力------通过 ArkUI 的 XComponent 挂载 AR Engine，让纹样以三维形态叠加到实物表面预览。其三，构建纹样知识图谱------将朝代、品类、工艺载体、应用场景四个维度建模为图数据库，支持语义化检索和关联推荐。其四，开放创作者生态------将工坊的纹理算法扩展为可编程的纹样生成 DSL，让守艺人以代码定义纹样规则并生成可商用的 WebP 素材。其五，探索 NFT 数字藏品链路------将平台生成的非遗纹样 WebP 素材上链确权，为非遗传承人提供数字资产变现通道。
非遗纹样的数字化传承不是简单的图片入库，而是让千年审美密码在端侧算力上重新生长。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 将自动执行以下操作：
- 生成项目骨架（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 语法：
typescript
@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 版本编写，不同版本界面可能存在细微差异。