欢迎大家加入[开源鸿蒙跨平台开发者社区](https://openharmonycrossplatform.csdn.net)，一起共建开源鸿蒙跨平台生态。

目录

0. 总体页面结构（上下两区）

1. 数据层设计（GitCode OpenAPI）

1.1 目录树接口

1.2 单路径内容接口（用于点击进入某目录/文件）

2. 目录树模型与渲染（上部区域）

2.1 数据模型

2.2 原生 Tree 渲染两种做法

2.3 点击交互

3. README Markdown 原生渲染（下部区域）

3.1 README 获取策略

3.2 Markdown 原生解析/渲染方案

4. 层级导航与内容展示

4.1 状态管理

4.2 目录点击流程（无刷新）

4.3 文件点击流程（新页）

5. 代码高亮（加分项）

5.1 最容易落地的方式

5.2 原生高亮渲染思路

6. 性能与工程化要点（别踩坑）

0. 总体页面结构（上下两区）

页面=上部目录区 + 下部内容区

• 上部（目录树+当前层文件列表）

  • 左侧：可折叠多级目录树（Tree）

  • 右侧/下方：当前目录下的文件/子目录列表（List）

• 下部（README 渲染区）

  • 显示仓库根目录（或当前目录）下 README.md 的 Markdown 原生渲染结果

  • 下拉可滚动

• 交互与状态同步：

  • 目录树节点选中 → 更新“当前路径”状态

  • 当前路径变化 → 更新文件列表、更新 README（优先根目录 README，或你定义的策略）

这样能对标经典代码托管网页的“树 + README”上下布局，但全部原生实现。

---

1. 数据层设计（GitCode OpenAPI）

1.1 目录树接口

GitCode 获取仓库 Tree 的接口为：
GET /api/v5/repos/{owner}/{repo}/git/trees/{sha}，sha 可以是分支名（main/master）、commit sha 或目录 tree sha。(docs.gitcode.com)

关键点：

• sha=main（或默认分支名）可拿到根目录 tree

• 返回树结构数组（每项含 path / type(tree|blob) / sha / size / url ...）

1.2 单路径内容接口（用于点击进入某目录/文件）

GET /api/v5/repos/{owner}/{repo}/contents/{path}?ref=main

• 目录：返回该目录下的 items

• 文件：返回文件元数据 + base64 内容 content。(docs.gitcode.com)

你可以两种策略二选一或组合：

策略A（推荐）：

• 首次用 git/trees/main?recursive=1(如果 GitCode 支持) 一次性拉全树

• 本地构建树模型 + 本地路径索引

• 点击展开不再请求（极快）

策略B：

• 只拉根 tree

• 用户展开某目录时用该目录的 sha 再调用 git/trees/{sha}

• 懒加载，初始更轻

如果 recursive 参数 GitCode 没公开写，优先用策略B，稳妥。

---

2. 目录树模型与渲染（上部区域）

2.1 数据模型

把 API 的扁平 tree 转成真正的层级结构：

type TreeNode = {
  name: string
  path: string
  type: 'dir' | 'file'
  sha?: string
  children?: TreeNode[]
  isExpanded?: boolean
}

构建逻辑（扁平 → 树）：

1. 按 / 分割每个 item.path

2. 逐层插入 map

3. 最后得到根节点 children

2.2 原生 Tree 渲染两种做法

做法1：递归组件渲染（简单直接）

• TreeNodeView(node, depth)

  • 行：缩进(depth)、icon、name、展开箭头

  • 若 isExpanded → 递归渲染 children

做法2：扁平化列表 + 展开状态（更高性能）

• 把“可视节点”维护成一个数组 visibleNodes

• 展开/收起只重算 visibleNodes

• 列表用虚拟化能力（Recycler/List/ForEach）渲染

多层目录 + 大仓库时建议做法2。

2.3 点击交互

• 点击文件夹：

  • toggle isExpanded

  • setCurrentPath(node.path)

  • 触发文件列表刷新（或用本地索引）

• 点击文件：

  • navigate 到 FileContentPage(path, sha)

---

3. README Markdown 原生渲染（下部区域）

3.1 README 获取策略

优先尝试从根目录取：

1. contents/README.md

2. contents/README.MD

3. contents/readme.md
   拿到后 base64 decode 成 markdown 字符串。(docs.gitcode.com)

失败就显示占位：No README found

3.2 Markdown 原生解析/渲染方案

你要的是 “Markdown → 原生 UI”，不是 Web 渲染。

可选库（按你技术栈挑）：

• React Native / RN-OpenHarmony

  • react-native-markdown-display：完全用原生组件渲染，不用 WebView。(GitHub)

  • react-native-simple-markdown（GitCode/Gitee 上也有维护）。(GitCode)

• 如果是 OpenHarmony ArkUI(ArkTS)

  • 用 markdown-it/remark 做解析 → AST

  • 自己写一个 AST → ArkUI 组件映射层

  • 标题/段落/列表/引用/代码块分别映射到 Text / Column / Row / List 等

AST 渲染映射例子：

• heading → Text(fontSize/weight)

• paragraph → Text + margin

• list → Column(for items)

• code_block → Scroll + Text(mono font) + 高亮

---

4. 层级导航与内容展示

4.1 状态管理

全局 store（或页面共享状态）：

state = {
  owner, repo, ref,      // 仓库标识
  treeRoot,              // 目录树
  currentPath,           // 当前浏览路径
  currentListItems,      // 当前目录列表
  readmeContent,         // README markdown
  cache: Map<path, data> // 可选缓存
}

4.2 目录点击流程（无刷新）

1. update currentPath

2. 若有 cache[path] → 直接用

3. 否则 contents/{path}?ref=main 拿目录 items

4. 更新 currentListItems

4.3 文件点击流程（新页）

新页面做：

1. contents/{filePath}?ref=main

2. base64 decode 得到文本

3. 判断文件类型：

   • markdown → 用 MarkdownRenderer

   • code/text → CodeView

   • 二进制（图片等）→ 原生 Image / 下载提示

---

5. 代码高亮（加分项）

5.1 最容易落地的方式

• 解析器/高亮库输出 token → 你再映射成原生 Text Span

• RN 可用 prismjs / highlight.js（只用它们做 tokenize，不渲 HTML）

• 其他原生栈同理：只取 token/AST，不用 Web。

5.2 原生高亮渲染思路

1. 根据文件扩展名选 language

2. highlight(code) → tokens = [{content, color, fontStyle}]

3. 用 RichText / TextSpan（或多段 Text）拼接渲染

4. 外面包一个横向 Scroll（防止长行截断）

重点是：你渲染的是 token 结果，不是 HTML DOM，就不算套壳。

---

6. 性能与工程化要点（别踩坑）

1. 本地缓存

   • treeRoot 缓存在内存/磁盘

   • path→contents 也缓存（LRU）

2. 分页/虚拟列表

   • 大目录一定要虚拟化列表

3. 并发与取消

   • 快速切目录时取消旧请求，避免乱序覆盖

4. 错误处理

   • 404/鉴权失败/限流都要有 UI 提示

5. 数据解码

   • GitCode 文件 content 为 base64，需要 UTF-8 decode。(docs.gitcode.com)

---

总结

本文摘要： 本文介绍了基于GitCode API实现的代码仓库浏览界面设计方案。系统采用上下分区的页面结构：上部为目录树和文件列表区，支持多级目录展示和点击交互；下部为README渲染区，实现Markdown原生解析渲染。文章详细阐述了数据层设计（GitCode API调用策略）、目录树模型构建与渲染方案、README获取与渲染技术选型、状态管理与交互流程，并提供了代码高亮实现思路。系统采用本地缓存优化性能，支持无刷新导航，同时考虑了工程化实施中的错误处理和数据解码等关键问题。该设计对标主流代码托管平台界面