【观止·诗史汇 HarmonyOS 实战系列 07】兴替明鉴：四维总览与六类分析的朝代洞察模型

【观止·诗史汇 HarmonyOS 实战系列 07】兴替明鉴：四维总览与六类分析的朝代洞察模型

前六篇已经把《观止·诗史汇》的两条主线铺出来了：前四篇解决工程骨架、首页和诗文内容包，第五篇把一首诗的详情页拆成正文、译注、简析、作者、朗读、收藏、笔记和统计，第六篇把历史事件放进时间轴，让用户能顺着朝代顺序理解关键节点。

第七篇继续往“史”的一侧推进。时间轴解决的是“先后顺序”，但只知道一个朝代从哪一年到哪一年还不够。学习者真正需要的是：这个朝代为什么兴起，为什么衰落，政治、经济、文化、科技和对外关系分别扮演什么角色，关键事件又如何把这些判断落到具体节点上。

这就是兴替明鉴模块要解决的问题。它不是朝代表的详情页，也不是一段朝代介绍文案，而是一个朝代洞察页：顶部可以切换朝代，中间有基础信息和跨模块入口，主体用六类详细分析解释兴衰，再用关键节点把抽象分析接回事件详情。

上图来自本机 DevEco 模拟器中打开《观止·诗史汇》的“兴替明鉴”模块。第七篇的截图重点不是首页入口，而是DynastyInsightPage本体：朝代选择、基础信息、古今地理/朝代详情跳转、六类详细分析和后续关键节点。

本篇要解决什么问题

兴替明鉴至少要回答六个工程问题：

这几个点决定了兴替明鉴的定位：它不是孤立页面，而是时间轴、朝代详情、古今地理、事件详情之间的解释层。

源码对象总览

这篇文章会重点拆DynastyInsightPage和DynastyAnalysisService，再补充它与DynastyOverviewPage、事件详情和地理详情的关系。

页面不是从文案开始，而是从状态模型开始

DynastyInsightPage的状态定义比较克制：

interface InsightState { loading: boolean; dynasties: Dynasty[]; current: Dynasty | null; overview: DynastyOverview | null; detail: DynastyDetail | null; modules: DynModule[]; nodes: KeyNodeRow[]; }

这组状态可以分成三层：

这种拆法有两个好处。

第一，页面不会把全部内容都塞进一个巨大对象。朝代本体仍然来自DynastyService，深度分析来自DynastyAnalysisService，事件节点来自EventService。

第二，页面可以清晰处理内容缺口。比如overview当前为空，页面可以隐藏“四维总览”；detail不存在，六类分析就显示空态；事件没有摘要，也不影响朝代基础信息展示。

默认朝代与路由参数

兴替明鉴既可以从首页直接打开，也可以从时间轴、文脉、地理等模块带着dynastyId打开。因此它不能假设入口唯一。

async aboutToAppear() { const dyn: Dynasty[] = await this.dynastySvc.list(); const params: NavigateParams = Navigator.getParams(); let target: string = params.dynastyId ?? DEFAULT_DYNASTY; if (!dyn.some((d: Dynasty) => d.id === target)) { target = dyn.length > 0 ? dyn[0].id : DEFAULT_DYNASTY; } this.state = { loading: true, dynasties: dyn, current: null, overview: null, detail: null, modules: [], nodes: [] }; await this.loadDynasty(target); }

这里有一个小但重要的防御：如果传入的dynastyId不存在，页面会回退到列表中的第一个朝代，而不是直接空白或崩溃。

对一个内容型 App 来说，路由参数不可靠是常态。用户可能从收藏回跳，可能从旧版本笔记进入，也可能从未来新增的文脉入口进入。页面先校验参数，再加载内容，是比“入口保证正确”更稳的做法。

loadDynasty：一次装配四类信息

loadDynasty(id)是这个页面最核心的方法。它不是只加载一个朝代，而是把四类信息装成页面可渲染状态：

1. 当前朝代cur
2. 四维总览ov
3. 六类详细分析dt
4. 关键节点nodes

async loadDynasty(id: string) { const cur: Dynasty | null = await this.dynastySvc.getById(id); const ov: DynastyOverview | null = await this.analysisSvc.getOverview(id); const dt: DynastyDetail | null = await this.analysisSvc.getDetail(id); const allEvents: HistoryEvent[] = await this.eventSvc.list(); const evs: HistoryEvent[] = allEvents .filter((e: HistoryEvent) => e.dynastyId === id && e.nodeType && e.nodeType.length > 0) .sort((a: HistoryEvent, b: HistoryEvent) => a.year - b.year); }

这一段有两个选择很值得注意。

第一，关键节点不取所有事件，而是只取nodeType存在的事件。也就是说，不是每条史事都适合出现在兴衰节点里。nodeType把事件分成建立、兴盛、转折、危机、衰亡等类型，让页面可以从“事件列表”升级为“兴衰结构”。

第二，事件按year排序。兴替分析不是按录入顺序展示，而是回到历史时间顺序。这和第六篇时间轴的设计是同一条原则：历史内容的第一秩序是时间。

六类详细分析：固定字段比自由标题更稳定

当前DynastyDetail不是一个自由数组，而是固定六个字段：

const modules: DynModule[] = dt ? [ { key: `${id}_gaikuo`, title: '兴衰关键', body: dt.gaikuo }, { key: `${id}_zhengzhi`, title: '政治', body: dt.zhengzhi }, { key: `${id}_jingji`, title: '经济', body: dt.jingji }, { key: `${id}_wenhua`, title: '文化', body: dt.wenhua }, { key: `${id}_keji`, title: '科技', body: dt.keji }, { key: `${id}_duiwai`, title: '对外交流', body: dt.duiwai } ] : [];

这比“后端给一个标题数组，页面照着渲染”更朴素，但更适合当前项目。

原因是本项目仍处于本地内容包阶段，内容结构需要稳定。六类字段固定后，写文章、写数据、写 UI、做验收都能对齐同一套口径：

对读者来说，这种结构也更容易横向比较。看完秦、汉、唐、宋、明、清之后，用户自然会意识到每个朝代都可以从同一组维度观察。

空内容过滤：不要为了完整而展示空壳

HistoryAnalysis.ets里有些朝代的gaikuo可能为空。页面没有强行展示空卡片，而是做了过滤：

const nonEmptyModules: DynModule[] = modules.filter((m: DynModule) => m.body && m.body.length > 0);

这个细节很像内容产品里的“温柔退让”：数据还没有补齐时，页面不要把空白暴露给用户。模块是否出现，由内容决定，而不是由模板强行撑出来。

这也解释了为什么当前截图里直接从“六类详细分析”的政治、经济等模块开始。页面不是漏了内容，而是尊重了当前内容包状态。

DynastyAnalysisService：服务层负责 ID 兼容

朝代分析服务很短，但它承担了一个重要职责：把历史遗留 ID 差异收束在服务层。

export class DynastyAnalysisService { getOverview(dynastyId: string): Promise<DynastyOverview | null> { const o: DynastyOverview | undefined = EXTRA_OVERVIEWS.find((it: DynastyOverview) => it.dynastyId === dynastyId); return Promise.resolve(o ?? null); } getDetail(dynastyId: string): Promise<DynastyDetail | null> { const normalizedId: string = normalizeDynastyAnalysisId(dynastyId); const d: DynastyDetail | undefined = EXTRA_DETAILS.find((it: DynastyDetail) => it.dynastyId === normalizedId); return Promise.resolve(d ?? null); } }

兼容函数如下：

function normalizeDynastyAnalysisId(dynastyId: string): string { if (dynastyId === 'd_w_han') { return 'd_west_han'; } if (dynastyId === 'd_three') { return 'd_sanguo'; } return dynastyId; }

为什么不在页面里写兼容？

因为页面不应该知道d_w_han和d_west_han是历史包 ID 差异，也不应该到处出现if dynastyId === ...。页面只关心“我要某个朝代的分析”，服务层负责把不同数据源的 ID 归一。

这是内容工程里非常常见的小问题：一开始几个文档、几个 mock、几个页面各自命名，后来统一时如果没有服务层兜住，就会出现页面分支蔓延。越早把归一逻辑放到 service，后面越省心。

四维总览当前为什么为空

HistoryAnalysis.ets顶部有一段说明：

/** * - EXTRA_OVERVIEWS：四维总览（文治/商业/科技/积弱）。当前按产品需求留空， * 页面在无数据时会自动隐藏 "四维总览" 区块。 * - EXTRA_DETAILS：六模块详细分析，但按最新产品口径将首模块 `gaikuo` * 改为承载 "兴衰关键" 叙事段，其余五项对应政治 / 经济 / 文化 / 科技 / 对外。 */ export const EXTRA_OVERVIEWS: DynastyOverview[] = [];

这说明当前产品口径发生过一次调整：四维总览的模型还在，但数据暂时留空；重点先落在六类详细分析上。

这不是坏事。工程上保留overview的状态和 UI 分支，意味着未来要恢复四维卡片时，不需要重写页面结构。只要补齐EXTRA_OVERVIEWS，页面就会自动出现“四维总览”。

关键节点：从事件、转折点和 keyEvents 合成

兴替明鉴的关键节点不是单一来源。页面会先读取事件列表中已经带nodeType的事件：

const nodes: KeyNodeRow[] = evs.map((e: HistoryEvent) => { const r: KeyNodeRow = { id: e.id, eventId: e.id, year: e.year, title: e.title, nodeType: e.nodeType ?? '', summary: this.eventContent(e), hasContent: this.hasEventContent(e) }; return r; });

接着又把Dynasty.turningPoints并入：

if (cur && cur.turningPoints) { for (let i = 0; i < cur.turningPoints.length; i++) { const tp: DynastyTurningPoint = cur.turningPoints[i]; const related: HistoryEvent | null = this.findRelatedEvent(tp.title, evs); const r: KeyNodeRow = { id: `${id}_turning_${i}`, eventId: related ? related.id : '', year: related ? related.year : cur.startYear, title: tp.title, nodeType: related && related.nodeType ? related.nodeType : this.turningPointType(i, cur.turningPoints.length), summary: related ? this.eventContent(related) : '', hasContent: related ? this.hasEventContent(related) : false }; nodes.push(r); } }

最后还会把keyEvents兜底合进去。

这种做法的价值在于：兴替明鉴可以尽量利用已有内容包。事件详情足够完整时，节点点击后可以进入TimelineEventDetailPage；事件详情还没补齐时，转折点仍然可以在页面上作为简要节点出现。

标题匹配：用 normalizeEventTitle 做轻量关联

turningPoints和HistoryEvent之间没有强绑定 ID，页面通过标题做近似匹配：

private findRelatedEvent(title: string, events: HistoryEvent[]): HistoryEvent | null { const key: string = this.normalizeEventTitle(title); for (let i = 0; i < events.length; i++) { const eventKey: string = this.normalizeEventTitle(events[i].title); if (key === eventKey || key.indexOf(eventKey) >= 0 || eventKey.indexOf(key) >= 0) { return events[i]; } } return null; }

归一函数会去掉括号、数字、公元年、标点和一些常见差异：

private normalizeEventTitle(title: string): string { return title .replace(/（[^）]*）/g, '') .replace(/\([^)]*\)/g, '') .replace(/[0-9]/g, '') .replace(/[前后约公元年\s·、，。]/g, '') .replace(/之变/g, '') .replace(/之耻/g, '') .replace(/首下/g, '下') .replace(/开创科举制/g, '科举') .replace(/开创科举/g, '科举') .replace(/开科举设进士/g, '科举') .replace(/修建大运河/g, '大运河') .replace(/开凿大运河/g, '大运河'); }

这不是一个完美的语义匹配算法，但在本地内容包阶段足够实用。它解决的是“同一件事在不同文档里写法略不同”的现实问题。

后续如果内容包继续扩大，更稳的方案是给turningPoints增加eventId字段，让内容编辑阶段就建立显式关联。当前的标题归一可以作为过渡层。

节点类型：让历史事件带上结构意义

nodeType的渲染逻辑很直接：

private nodeLabel(t: DynastyNodeType): string { if (t === 'found') return '建立'; if (t === 'prosper') return '兴盛'; if (t === 'turn') return '转折'; if (t === 'crisis') return '危机'; if (t === 'fall') return '衰亡'; return ''; }

配套颜色也按语义分组：

private nodeColor(t: DynastyNodeType): ResourceColor { if (t === 'found') return AppColors.accent; if (t === 'prosper') return AppColors.success; if (t === 'turn') return AppColors.warning; if (t === 'crisis') return AppColors.warning; if (t === 'fall') return AppColors.danger; return AppColors.textTertiary; }

这让关键节点不只是列表。用户能一眼看出这件事是在“建立”“兴盛”“转折”“危机”还是“衰亡”阶段。对于历史学习来说，这种类型提示很有价值，因为它把事件放回王朝生命线里。

与古今地理的关系

兴替明鉴里有一个“古今地理”入口：

Text(`${this.state.current!.name}·古今地理`) .onClick(() => { const p: NavigateParams = { dynastyId: this.state.current!.id }; Navigator.push(AppRoutes.GEO_DETAIL, p); })

这个入口带的是dynastyId，不是geoId。也就是说，它打开的不是某一个地名详情，而是古今地理列表，并按当前朝代筛选。

这和第八篇要讲的GeoPage正好衔接：地理模块既可以作为一级入口展示全部地名，也可以从某个朝代进入，只展示该朝代相关的古今地理。

与朝代详情的关系

兴替明鉴也能跳到朝代详情：

Text(`${this.state.current!.name}·朝代详情`) .onClick(() => { const p: NavigateParams = { dynastyId: this.state.current!.id }; Navigator.push(AppRoutes.DYNASTY_OVERVIEW, p); })

DynastyOverviewPage更像资料页：时期概述、重大事件、著名人物、发明创造、历史转折点，以及收藏和笔记。

兴替明鉴则更像分析页：围绕兴衰逻辑展开六类解释，并用节点把分析接回事件。

两者分工可以这样理解：

这也是系列文章里要特别强调的工程设计：不要把所有朝代信息都堆在一个页面里。资料页和分析页分开，用户路径会更清楚。

当前实现的边界

这个模块已经完成了兴替分析的核心链路，但还有几个边界值得记录。

第一，EXTRA_OVERVIEWS当前为空。页面保留了四维总览能力，但数据还没有填充。后续如果恢复“文治昌明、商业繁荣、科技发达、积赏积弱”的四维卡片，需要优先补内容包，而不是改页面。

第二，关键节点存在重复风险。因为HistoryEvent、turningPoints、keyEvents会合并到同一个nodes数组，如果标题匹配没有命中，就可能出现语义相近的节点重复。后续可以用规范化标题做去重。

第三，事件标题匹配是启发式的。它能处理“科举”“大运河”等常见差异，但不能替代显式 ID。长期看，内容包应该把turningPoints与eventId绑定起来。

第四，六类分析当前是纯文本。未来如果要做高亮、引用、图表、参考出处或折叠展开，DynastyDetail可能需要从字符串升级为结构化段落数组。

本地验收命令

本篇使用真实模拟器截图，不使用封面加工图作为正文图。基本验收路径如下：

git status --short & "D:\Program Files\HuaWei\DevEco Studio\sdk\default\openharmony\toolchains\hdc.exe" list targets & "D:\Program Files\HuaWei\DevEco Studio\sdk\default\openharmony\toolchains\hdc.exe" shell aa start -a EntryAbility -b com.example.app_project02 & "D:\Program Files\HuaWei\DevEco Studio\sdk\default\openharmony\toolchains\hdc.exe" shell snapshot_display -i 0 -f /data/local/tmp/guanzhi_07_dynasty_insight.png -w 1080 -h 2400 -t png & "D:\Program Files\HuaWei\DevEco Studio\sdk\default\openharmony\toolchains\hdc.exe" file recv /data/local/tmp/guanzhi_07_dynasty_insight.png .\screenshots\07_dynasty_insight_emulator.png

页面人工验收重点：

• 首页点击“兴替明鉴”可以进入DynastyInsightPage。
• 顶部朝代 chip 可以横向切换。
• 当前朝代基础信息显示正确。
• “古今地理”“朝代详情”能带dynastyId跳转。
• 六类详细分析不展示空模块。
• 关键节点点击后能进入事件详情。

常见问题复盘

1. 为什么不把兴替明鉴做成时间轴的一部分？

时间轴负责“顺序”，兴替明鉴负责“解释”。如果把六类分析塞进时间轴，时间轴会变成很长的知识百科，失去快速浏览朝代顺序的能力。两个页面分开后，用户可以先看顺序，再进入某个朝代深读。

2. 为什么六类分析不用动态标题？

因为当前阶段更需要统一口径。固定的政治、经济、文化、科技、对外和兴衰关键，方便横向比较，也方便内容包补齐。等内容更丰富后，再考虑让部分朝代出现特有模块。

3. 为什么 ID 归一要放在服务层？

页面不应该知道数据历史包的命名差异。d_w_han和d_west_han是内容层的兼容问题，放在DynastyAnalysisService更稳。

4. 为什么关键节点要有 nodeType？

因为历史事件本身不等于兴衰节点。nodeType让事件具备结构意义：建立、兴盛、转折、危机、衰亡。用户看到的就不是散点，而是一条朝代生命线。

5. 为什么现在四维总览为空也保留代码？

这是一个可扩展位。当前产品口径先落六类详细分析，四维总览暂不展示；但保留overview状态和 UI 分支，后续补内容时成本很低。

本章小结

第七篇的核心是：兴替明鉴不是“朝代介绍页”，而是把朝代数据、深度分析、历史节点、地理入口和朝代详情页串起来的解释层。

从工程角度看，这个模块最值得借鉴的地方有三点：

• 页面状态按朝代上下文、分析内容、关键节点拆开。
• 服务层吸收历史 ID 差异，页面只面向稳定接口。
• 六类分析和节点类型让历史内容具备可比较、可跳转、可扩展的结构。

下一篇会顺着兴替明鉴里的“古今地理”入口继续拆解：一个地名如何同时关联朝代、事件和诗文，为什么GeoPlace应该先稳定关系模型，再考虑地图展示。