CardHarmonyOS
CardHarmonyOS 是期货首页卡片的 HarmonyOS ArkTS 示例工程，使用 ArkUI 声明式 UI
实现 AI 观点、市场排名和 AI 选期三张业务卡片。首页入口为
entry/src/main/ets/pages/Index.ets。
环境要求
- DevEco Studio（支持 HarmonyOS API 20 及以上）
- HarmonyOS SDK 6.0.0 或更高版本
- ohpm
- HarmonyOS 手机或模拟器
项目目标 SDK 为 HarmonyOS 6.1.0（API 23），兼容 SDK 为 6.0.0（API 20）。
快速开始
- 使用 DevEco Studio 打开仓库根目录。
- 执行
ohpm install安装依赖。 - 在 File > Project Structure > Signing Configs 中配置本机调试签名。
- 选择
entry模块和defaultproduct。 - 连接设备或启动模拟器，点击 Run 构建并安装应用。
单元测试位于 entry/src/test/，设备测试位于 entry/src/ohosTest/，可在
DevEco Studio 中右键测试文件执行。
目录结构
AppScope/ 应用级配置与资源
entry/src/main/ets/
├── pages/ 首页及详情页
├── ai-view/ AI 观点卡片
├── market-ranking/ 市场排名卡片
├── ai-pick/ AI 选期卡片
└── common/ 卡片容器、数据模型及行情字段常量
entry/src/main/resources/ 文案、颜色、图片和页面配置
doc/ HTTP 与 4106 行情接口文档
业务卡片通常由 Models、DataFetcher、NodeComponent 和 Mock 数据组成。
市场排名与 AI 选期分别通过独立的 HqRequestClient 构造行情订阅参数，共享
common/HqFieldId.ets 中的 4106 字段 ID。
MarketRanking 生命周期
MarketRankingNodeComponent 出现时读取卡片配置、注册 tcpReconnect 事件监听，并在
firstPageVisible 为 true 时获取当前 Tab 的 contracts。contracts 返回后先生成占位列表，
再由 MarketRankingHqRequestClient 发起行情订阅，行情回调会整体替换 CardData。
aboutToAppear
→ 注册 TCP 重连事件
→ 获取当前 Tab 的 contracts
→ 填充合约占位列表
→ 页面可见时订阅行情
运行期间按以下规则更新：
refreshTrigger：由父组件通过@Link传入；变化后停止旧行情、重新获取 contracts， 并在可见时重新订阅。firstPageVisible：由父组件通过@Provide提供，组件通过@Consume监听，默认 为true。变为不可见时立即停止行情；恢复可见时优先使用已有 contracts 重新订阅， 没有 contracts 才重新请求。tcpReconnect：组件通过公共emitter监听。重连且页面可见时停止旧行情并重新订阅； 页面不可见时忽略，恢复可见后再订阅。- Tab 切换：停止旧行情、清空列表、获取新 Tab 的 contracts，再订阅对应行情。
aboutToDisappear 会解绑 TCP 重连监听并停止行情订阅。HTTP 请求等待期间如果页面变为
不可见，contracts 仍可更新，但不会创建行情订阅。
数据与接口
当前 HTTP Fetcher 仅构造请求参数，行情客户端也尚未连接真实客户端桥接层；页面使用 Mock 数据并以 2.5 秒间隔模拟行情更新。接入真实服务前请阅读：
不要在源码或提交中新增 Cookie、Token、证书、私钥或本机签名密码。签名材料应通过 DevEco Studio 在本机配置。
开发约定
- 使用 ArkTS 显式类型，组件采用 ArkUI 声明式写法。
- 类型和类使用 PascalCase，变量和方法使用 camelCase，常量使用 UPPER_SNAKE_CASE。
- 公共行情字段统一维护在
HqFieldId，避免在业务卡片中硬编码字段 ID。 - 新增接口或修改 4106 参数时，同步更新
doc/下对应文档。