【天体运行模拟｜10】HarmonyOS ArkTS 知识点详情实战：连接概念、公式和模拟入口

学习型应用的详情页不能只是一块更大的文本卡片。用户从“圆轨道”进入详情后理想路径应该是先理解概念再看到适用公式最后带着明确实验场景进入模拟页验证。如果详情页不知道当前知识点的稳定 ID也不知道关联哪个公式和实验那么“去做相关模拟”只能跳到默认场景知识与实践之间仍然断开。“天体运行模拟”的真实源码已经搭起基础链路KnowledgeListPage.ets内置 10 个知识点点击时把标题、分类、摘要和正文通过 ArkUIrouter.pushUrl()传给KnowledgeDetailPage.ets详情页在aboutToAppear()回读参数渲染核心概念、学习要点、学习建议三张卡片并提供一个进入ExperimentSimPage的按钮。本文复核这条真实路由和 ArkUI 页面结构并给出从“文本透传”升级到“知识点 ID 驱动”的设计让概念、公式和实验共享关联元数据。当前源码没有公式入口模拟按钮也没有携带expId因此它进入的是模拟页默认场景文章不会把建议关联能力伪装成已实现功能。唯一复核标记KNOWLEDGE-ONE13-CONCEPT-FORMULA-SIM-20260726路由只传知识点 ID详情模型集中声明公式和实验关联模拟入口必须携带明确场景参数。验证基线与真实入口本文面向 HarmonyOS 5.0 及以上版本。实际工程应用版本为1.0.0targetSdkVersion为6.0.2(22)compatibleSdkVersion为6.0.1(21)入口模块支持phone、tablet、2in1。知识点目录包含 10 条基础认知 3 条引力是什么、速度决定轨道、质量与半径。轨道探索 3 条圆轨道、椭圆轨道、逃逸轨道。多体系统 2 条三体问题、引力扰动。高级实验 2 条黑洞吞噬、星系碰撞。详情页接收 4 个可选字符串参数渲染 3 张信息卡提供 1 个模拟按钮。当前公式跳转数量为 0模拟按钮传递实验 ID 数量为 0详情页稳定知识点 ID 数量为 0。一、当前列表到详情的路由契约列表点击时执行router.pushUrl({ url: views/learning/KnowledgeDetailPage, params: { title: kp.title, category: kp.category, summary: kp.summary, content: kp.content } })详情页定义interface KnowledgeDetailParams { title?: string category?: string summary?: string content?: string }这个方案实现快、页面独立即使详情页没有访问知识目录也能显示完整内容。它适合首版静态应用。问题是路由承担了数据存储职责。摘要或正文越长路由对象越大列表和详情分别维护默认值也可能出现同一知识点两份文本不一致。二、aboutToAppear()负责接收参数源码aboutToAppear(): void { const params router.getParams() as KnowledgeDetailParams | undefined if (params?.title) { this.title params.title } if (params?.category) { this.category params.category } if (params?.summary) { this.summary params.summary } if (params?.content) { this.content params.content } }四个字段都有页面默认值所以没有参数时不会白屏。这是一种安全回退。但if (params?.content)会忽略空字符串。如果业务允许内容为空应该用params?.content ! undefined区分“未传”和“传入空值”。三、页面状态为什么全部是字符串详情页当前有State title: string 知识点 State category: string 基础认知 State summary: string 通过分类知识点快速理解对应天体概念。 State content: string 结合模拟现象、轨道图像和引力规律进行理解 可以让知识点更容易记住。路由回读后更新StateArkUI 自动重建相关Text。对于单次加载这是可用的。当模型扩展公式、实验、插图和学习进度时散落状态会越来越多。更稳的方式是维护一个可空详情对象并显式处理加载成功与未找到状态。四、三张信息卡形成学习节奏详情页依次调用this.InfoCard(核心概念, this.summary) this.InfoCard(学习要点, this.content) this.InfoCard( 学习建议, 先观察模拟现象再对应引力公式或轨道规律进行解释。 调参时重点关注质量、速度、距离和轨迹变化。 )结构对应这是什么。在模拟中看什么。应该如何学习。InfoCard使用Builder复用标题和正文布局避免复制三套样式。计算和路由逻辑没有放进 Builder保持了声明式 UI。五、Builder适合纯展示组件源码Builder InfoCard(title: string, body: string) { Column() { Text(title) Text(body) .lineHeight(22) .margin({ top: 8 }) } .width(100%) .padding(16) }这个 Builder 没有状态写入、异步操作或复杂分支非常适合复用。若卡片未来需要展开、复制或跳转可以提取成Component让交互状态由组件自己管理。六、当前“相关模拟”其实是默认模拟按钮只执行router.pushUrl({ url: views/experiment/ExperimentSimPage })模拟页没有收到expId和expName会使用自己的默认值State expId: string stable_orbit State title: string 稳定双体系统因此无论用户阅读“三体问题”还是“黑洞吞噬”都进入稳定双体默认场景。按钮文案“相关模拟”与实际关联并不完全一致。诚实的修复有两种暂时改成“进入模拟器”承认它是通用入口。建立知识点到实验 ID 的映射真正实现相关跳转。七、知识点 ID 应成为详情主键列表中的每个知识点已经有稳定 IDbasic_1 basic_2 basic_3 orbit_1 orbit_2 orbit_3 multi_1 multi_2 extreme_1 extreme_2详情路由只需传interface KnowledgeDetailParams { knowledgeId?: KnowledgePointId }router.pushUrl({ url: views/learning/KnowledgeDetailPage, params: { knowledgeId: kp.id } })详情页再从统一目录查找。标题或正文修改后不必更新路由调用方。八、统一知识目录避免页面重复定义推荐export interface KnowledgePointDetail { id: KnowledgePointId title: string category: KnowledgeCategory summary: string content: string icon: Resource formulaIds: FormulaId[] experimentIds: ExperimentId[] }目录放在模型层export const KNOWLEDGE_POINTS: readonly KnowledgePointDetail[] [ // 10 real entries ]列表页按分类过滤详情页按 ID 查找搜索和收藏也可以共享同一份内容。九、分类字符串也要收紧当前分类是普通字符串。可以定义export type KnowledgeCategory | 基础认知 | 轨道探索 | 多体系统 | 高级实验这样目录中的拼写错误会在编译期暴露。列表页的未知分类回退逻辑也可以显式处理而不是依赖任意字符串。十、知识点与公式的关联方式当前公式页包含万有引力、圆轨道速度、逃逸速度、动能、引力势能、质心和天文单位。知识点可以关联公式 IDtype FormulaId | universal_gravity | circular_orbit_speed | escape_speed | kinetic_energy | gravity_potential | center_of_mass | astronomical_unit例如{ id: orbit_1, title: 圆轨道, formulaIds: [ universal_gravity, circular_orbit_speed ] }详情页可以显示“相关公式”区域点击跳到公式详情或带筛选参数的公式页。十一、知识点与实验的关联方式实验目录已有stable_orbit elliptic_escape three_body binary_star black_hole galaxy_collision可建立明确映射知识点推荐实验引力是什么stable_orbit速度决定轨道elliptic_escape圆轨道stable_orbit椭圆轨道elliptic_escape逃逸轨道elliptic_escape三体问题three_body引力扰动three_body黑洞吞噬black_hole星系碰撞galaxy_collision“质量与半径”可进入自由宇宙或稳定双体具体由产品定义。十二、模拟跳转必须携带场景参数真实关联后private openExperiment( experimentId: ExperimentId, experimentName: string ): void { router.pushUrl({ url: views/experiment/ExperimentSimPage, params: { expId: experimentId, expName: experimentName } }) }按钮文案也应具体用“三体扰动实验”验证这比统一的“去做相关模拟”更可预测。若有多个实验可以显示列表或默认主实验加更多入口。十三、公式跳转也要传稳定 ID不要把公式字符串通过路由透传。公式显示和单位精度可能变化路由只传router.pushUrl({ url: views/learning/FormulaPage, params: { formulaId: circular_orbit_speed } })公式页加载后滚动或高亮对应项。若当前公式页尚不支持定位可先跳到筛选分类但按钮文案应与能力一致。十四、处理知识点不存在状态通过 ID 查找可能失败const point KNOWLEDGE_POINTS .find((item: KnowledgePointDetail) item.id params?.knowledgeId )不要默默展示默认“知识点”否则用户不知道链接失效。页面状态可以是type DetailState | loading | content | notFoundnotFound提供返回按钮和“回到知识列表”不显示伪内容。十五、路由参数要在页面重建后仍可恢复传 ID 的优势是页面重建时可以重新加载传完整内容则依赖路由对象仍然存在。若未来知识目录来自本地数据库或资源文件ID 仍然是稳定契约。对于纯静态目录加载是同步的对于异步仓库页面需要loading和错误状态但路由协议不变。十六、学习进度应绑定知识点 ID如果未来记录“已读”“收藏”“完成模拟”应保存interface KnowledgeProgress { knowledgeId: KnowledgePointId openedAt: number completedAt?: number relatedExperimentDone: boolean }不能用标题做键因为标题可能改文案。稳定 ID 还能支持内容版本迁移。十七、内容版本帮助处理更新建议知识点增加contentVersion: number当正文或关联实验发生重大变化时应用可决定保留已读状态。重新标记“内容已更新”。不清除用户收藏。重新计算学习完成度。当前源码没有学习进度和版本字段这属于后续演进。十八、内容与页面布局应分离详情页现在只支持文本卡片。模型可以继续扩展type KnowledgeBlock | { type: paragraph; text: string } | { type: formula; formulaId: FormulaId } | { type: tip; text: string } | { type: experiment; experimentId: ExperimentId }这比直接保存 Markdown 或 HTML 更容易保持原生 ArkUI、一致主题和离线安全。页面按 block 类型选择组件内容层不包含 UI 样式。十九、Scroll保证长内容可达源码把正文放在纵向ScrollScroll() { Column({ space: 16 }) { // cards and button } } .scrollable(ScrollDirection.Vertical) .layoutWeight(1)长标题在顶部使用单行省略正文卡片没有固定高度能够自然扩展。按钮下方还有 20vp margin。需要实测系统字体放大后按钮和最后一张卡是否仍高于底部导航安全区。二十、多设备详情布局手机使用单列卡片是合理默认。平板与 2in1 可以左侧显示概念与公式。右侧显示相关实验和学习建议。保持正文列最大宽度。支持鼠标和键盘聚焦。不要把三个卡片横向拉成三列导致正文行宽过短。内容页应优先保障连续阅读。二十一、返回与深链路顶部返回使用router.back()从列表正常进入时没有问题。若未来支持外部深链直接打开详情返回栈可能为空需要提供回到学习首页的回退策略。模拟结束后的返回路径也要设计用户是回详情继续学习还是回实验列表。可以在模拟路由携带sourceKnowledgeId但不要让模拟页依赖整个知识对象。二十二、无障碍与触控当前返回符号和按钮都是可点击元素。后续应验证返回符号有明确无障碍说明。分类标签被朗读为分类。三张卡片按视觉顺序聚焦。相关公式和实验按钮朗读具体目标。64% 宽按钮在手机和大字体下文字不截断。按钮文案具体化还能直接改善无障碍体验。二十三、关键测试矩阵场景当前或增强后预期不传参数进入详情当前显示默认内容从列表进入标题、分类、摘要、正文一致长标题顶栏单行省略点击返回回到上一页点击模拟当前进入默认稳定双体ID 模型增强后详情按知识点 ID 加载圆轨道详情关联圆轨道速度与稳定双体三体问题详情关联质心或引力内容与三体实验黑洞吞噬详情进入black_hole未知 ID显示 notFound不伪造默认详情大字体卡片和按钮不重叠平板/2in1保持合适正文行宽二十四、启动时关联校验function validateKnowledgeLinks( points: readonly KnowledgePointDetail[], formulaIds: ReadonlySetstring, experimentIds: ReadonlySetstring ): string[] { const errors: string[] [] points.forEach((point: KnowledgePointDetail) { point.formulaIds.forEach((id: FormulaId) { if (!formulaIds.has(id)) { errors.push( ${point.id}: unknown formula ${id} ) } }) point.experimentIds.forEach( (id: ExperimentId) { if (!experimentIds.has(id)) { errors.push( ${point.id}: unknown experiment ${id} ) } } ) }) return errors }这样公式或实验改 ID 时知识目录不会留下静默失效链接。二十五、发布前检查详情路由优先传稳定知识点 ID。列表与详情读取同一知识目录。分类由联合类型约束。相关公式使用公式 ID。相关实验使用真实实验 ID。模拟按钮文案与实际目标一致。未知 ID 有 notFound 状态。默认内容不掩盖路由错误。内容版本与学习进度分离。长文、长标题和大字体可滚动。手机、平板、2in1 保持阅读行宽。返回和深链路都有明确目的地。二十六、总结现有KnowledgeDetailPage.ets已完成一条可复核的基础链路知识列表透传四个文本参数详情页在aboutToAppear()接收并更新状态三个InfoCard组织概念、要点和建议纵向 Scroll 保证内容可达按钮进入模拟页。要真正连接概念、公式和模拟关键是把路由从“传完整文案”收紧为“传稳定 ID”再由统一知识目录声明公式 ID 和实验 ID。这样“三体问题”才能进入三体实验“圆轨道”才能定位圆轨道速度公式页面文案变化也不会破坏路由。知识详情不再是孤立文本页而会成为学习闭环的调度中心。说明本文基于真实 HarmonyOS/ArkTS 源码进行整理部分文字与示例由 AI 辅助生成所有现有能力与建议改造已明确区分。