从零到一：使用 uni-app x 开发鸿蒙 GitCode 目录树生成器

┌─────────────────────────────────────┐
│          应用层 (Application)        │
│    GitCodeTree - 目录树生成器        │
└─────────────────────────────────────┘
                 ↓
┌─────────────────────────────────────┐
│          框架层 (Framework)          │
│   uni-app x + Vue 3 + TypeScript    │
└─────────────────────────────────────┘
                 ↓
┌─────────────────────────────────────┐
│          API 层 (API Service)        │
│        GitCode REST API v5          │
└─────────────────────────────────────┘
                 ↓
┌─────────────────────────────────────┐
│          平台层 (Platform)           │
│  iOS / Android / HarmonyOS          │
└─────────────────────────────────────┘

pages/
└── gittree/
    └── gittree.uvue          # 主页面组件
        ├── Template          # 视图层
        ├── Script            # 逻辑层
        └── Style             # 样式层

用户输入
  ↓
输入验证
  ↓
解析项目信息 (owner/repo)
  ↓
API 请求
  ├── 获取项目信息
  └── 递归获取目录结构
      ↓
数据处理
  ├── 过滤 (仅文件夹/完整)
  ├── 深度控制 (1-5层/全部)
  └── 格式化 (树形文本)
      ↓
UI 渲染
  ├── 项目信息卡片
  └── 目录树展示
      ↓
用户操作
  ├── 复制到剪贴板
  └── 下载/分享

<GitTreePage>
│
├── <Header>                  # 顶部导航
│   ├── Logo
│   └── 主题切换按钮
│
├── <TokenSection>            # Token 配置区
│   ├── 输入框
│   ├── 保存按钮
│   └── 提示信息
│
├── <MainSection>             # 主功能区
│   ├── 项目输入框
│   ├── 历史记录列表 (新)
│   ├── 高级选项
│   │   ├── 深度选择器
│   │   └── 视图类型选择器
│   ├── 生成按钮
│   └── 测试按钮
│
├── <ProjectInfo>             # 项目信息卡片
│   ├── 项目名称
│   ├── 描述
│   └── 统计信息
│
└── <DirectoryTree>           # 目录树展示
    ├── 树形文本
    └── 复制按钮

// API 请求头配置
const headers = {
  'Authorization': `Bearer ${this.token}`,
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}

async getProjectInfo(owner: string, repo: string) {
returnnewPromise((resolve, reject) => {
    uni.request({
      url: `https://api.gitcode.com/api/v5/repos/${owner}/${repo}`,
      method: 'GET',
      header: {
        'Authorization': `Bearer ${this.token}`,
        'Accept': 'application/json'
      },
      success: (res) => {
        if (res.statusCode === 200) {
          resolve(res.data)
        } else {
          reject(newError(this.getErrorMessage(res.statusCode)))
        }
      },
      fail: (err) => {
        reject(newError('网络连接失败，请检查网络设置'))
      }
    })
  })
}

getErrorMessage(statusCode: number): string {
  const errorMap: Record<number, string> = {
    400: '请求参数错误',
    401: '访问令牌无效或已过期，请重新配置',
    403: '没有访问权限，请检查令牌权限设置',
    404: '项目不存在，请检查项目路径',
    429: '请求过于频繁，请稍后再试',
    500: 'GitCode 服务器错误',
    503: 'GitCode 服务暂时不可用'
  }
  return errorMap[statusCode] || `请求失败 (${statusCode})`
}

async getProjectDirectory(
  owner: string,
  repo: string,
  path: string = '',
  currentDepth: number = 0,
  maxDepth: number = 0
): Promise<any[]> {
// 深度限制检查
if (maxDepth > 0 && currentDepth >= maxDepth) {
    return []
  }

try {
    // 获取当前目录内容
    const data: any = awaitthis.fetchDirectoryContent(owner, repo, path)

    if (!Array.isArray(data)) {
      return []
    }

    // 并行处理所有子目录
    const promises = data.map(async (item: any) => {
      if (item.type === 'dir') {
        item.children = awaitthis.getProjectDirectory(
          owner,
          repo,
          item.path,
          currentDepth + 1,
          maxDepth
        )
      }
      return item
    })

    returnawaitPromise.all(promises)
  } catch (error) {
    console.error(`获取目录失败: ${path}`, error)
    return []
  }
}

generateTreeText(
  items: any[],
  prefix: string = '',
  isRoot: boolean = true,
  viewType: string = 'all'
): string {
let text = ''

// 过滤项目（如果只显示文件夹）
const filteredItems = viewType === 'folders'
    ? items.filter(item => item.type === 'dir')
    : items

  filteredItems.forEach((item, index) => {
    const isLast = index === filteredItems.length - 1
    const connector = isLast ? '└── ' : '├── '
    const icon = item.type === 'dir' ? '📁' : '📄'

    // 构建当前行
    text += `${prefix}${connector}${icon} ${item.name}\n`

    // 递归处理子目录
    if (item.type === 'dir' && item.children?.length > 0) {
      const newPrefix = prefix + (isLast ? '    ' : '│   ')
      text += this.generateTreeText(
        item.children,
        newPrefix,
        false,
        viewType
      )
    }
  })

return text
}

📁 项目名称
├── 📁 src
│   ├── 📁 components
│   │   ├── 📄 Button.vue
│   │   └── 📄 Input.vue
│   ├── 📁 pages
│   │   └── 📄 Home.vue
│   └── 📄 main.ts
├── 📁 static
│   └── 📄 logo.png
└── 📄 package.json

// 保存 Token
saveToken() {
if (!this.token.trim()) {
    this.showError('请输入访问令牌')
    return
  }

try {
    uni.setStorageSync('gitcode_token', this.token)
    this.isTokenSaved = true
    this.showSuccess('访问令牌已保存')
  } catch (error) {
    this.showError('保存失败，请重试')
  }
}

// 加载 Token
loadToken() {
try {
    const savedToken = uni.getStorageSync('gitcode_token')
    if (savedToken) {
      this.token = savedToken
      this.isTokenSaved = true
    }
  } catch (error) {
    console.error('加载 Token 失败', error)
  }
}

// 保存主题设置
saveTheme() {
  uni.setStorageSync('theme', this.isDarkMode ? 'dark' : 'light')
}

// 加载主题设置
loadTheme() {
const savedTheme = uni.getStorageSync('theme')
this.isDarkMode = savedTheme === 'dark'
}

LocalStorage
├── gitcode_token        # GitCode 访问令牌
├── theme               # 主题设置 (light/dark)
├── project_history     # 项目历史记录 (新增)
└── favorites           # 收藏项目 (计划中)

// 错误提示
showError(message: string) {
  uni.showToast({
    title: message,
    icon: 'error',
    duration: 3000
  })
  uni.vibrateShort() // 震动反馈
}

// 成功提示
showSuccess(message: string) {
  uni.showToast({
    title: message,
    icon: 'success',
    duration: 2000
  })
  uni.vibrateShort()
}

// 数据结构
data() {
return {
    projectHistory: [] asstring[],  // 历史记录列表
    showHistory: false                // 控制显示
  }
}

// 添加到历史
addToHistory(project: string) {
// 移除重复项
const index = this.projectHistory.indexOf(project)
if (index !== -1) {
    this.projectHistory.splice(index, 1)
  }

// 添加到最前面
this.projectHistory.unshift(project)

// 限制最多 10 条
if (this.projectHistory.length > 10) {
    this.projectHistory.pop()
  }

this.saveHistory()
}

// 选择历史项
selectHistoryItem(item: string) {
this.projectInput = item
this.showHistory = false
}

// 复制成功
copyTree() {
  uni.setClipboardData({
    data: this.directoryTree,
    success: () => {
      this.showSuccess('已复制到剪贴板')
      uni.vibrateShort({ type: 'light' }) // 轻震动
    }
  })
}

// 生成完成
async generateTree() {
// ... 生成逻辑 ...

this.showSuccess('生成成功')
  uni.vibrateShort({ type: 'medium' }) // 中等震动
}

// ❌ 串行方式 (慢)
for (let item of items) {
if (item.type === 'dir') {
    item.children = await getDirectory(item.path)
  }
}

// ✅ 并行方式 (快)
const promises = items.map(async (item) => {
if (item.type === 'dir') {
    item.children = await getDirectory(item.path)
  }
return item
})
awaitPromise.all(promises)

const depthOptions = [
  { label: '1层', value: 1 },
  { label: '2层', value: 2 },
  { label: '3层（推荐）', value: 3 },
  { label: '4层', value: 4 },
  { label: '5层', value: 5 },
  { label: '全部', value: 0 }
]

// 只渲染可见区域的节点
<scroll-view
  scroll-y
  :scroll-into-view="scrollIntoView"
  @scroll="onScroll"
>
  <view v-for="item in visibleItems" :key="item.id">
    {{ item.content }}
  </view>
</scroll-view>

// 分块渲染，避免卡顿
async renderTree() {
const chunkSize = 100
let index = 0

while (index < this.treeLines.length) {
    const chunk = this.treeLines.slice(index, index + chunkSize)
    this.displayedTree += chunk.join('\n')
    index += chunkSize

    // 让出主线程，避免阻塞 UI
    awaitnewPromise(resolve => setTimeout(resolve, 0))
  }
}

/* 主色调 - 渐变紫色 */
--primary-gradient: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
--primary-color: #667eea;
--primary-dark: #764ba2;

/* 功能色 */
--success-color: #10b981;  /* 成功/正面 */
--error-color: #ef4444;    /* 错误/危险 */
--warning-color: #f59e0b;  /* 警告 */
--info-color: #3b82f6;     /* 信息 */

/* 中性色 */
--text-primary: #1a202c;   /* 主要文字 */
--text-secondary: #718096; /* 次要文字 */
--bg-primary: #ffffff;     /* 主背景 */
--bg-secondary: #f8fafc;   /* 次背景 */
--border-color: #e2e8f0;   /* 边框 */

/* 基础单位 rpx (responsive pixel) */
/* 1rpx = 屏幕宽度 / 750 */

.card {
margin: 20rpx 30rpx;
padding: 40rpx;
border-radius: 20rpx;
}

.input-field {
width: 100%;
height: 80rpx;
padding: 030rpx;
font-size: 28rpx;
}

/* 适配不同屏幕 */
@media (max-width:375px) {
.card {
    margin: 15rpx 20rpx;
    padding: 30rpx;
  }
}

/* 按钮按下效果 */
.btn:active {
transform: scale(0.98);
opacity: 0.9;
}

/* 卡片展开动画 */
.card-content {
transition: all 0.3scubic-bezier(0.4, 0, 0.2, 1);
max-height: 0;
overflow: hidden;
}

.card-content.show {
max-height: 1000rpx;
}

/* 加载动画 */
@keyframes spin {
from { transform: rotate(0deg); }
to { transform: rotate(360deg); }
}

.loading-icon {
animation: spin 1s linear infinite;
}

<!-- ❌ 错误写法 -->
<view class="container">
  <!-- 大量内容 -->
</view>

<!-- ✅ 正确写法 -->
<scroll-view class="page" scroll-y="true">
  <view class="container">
    <!-- 大量内容 -->
  </view>
</scroll-view>

.page {
  width: 100%;
  height: 100vh;  /* 必须设置高度 */
  background-color: #f8fafc;
}

// ❌ 错误写法
async getProjectInfo(owner, repo) {
const res = await uni.request({ /* ... */ })
return res.data
}

// ✅ 正确写法
async getProjectInfo(owner, repo) {
returnnewPromise((resolve, reject) => {
    uni.request({
      url: `...`,
      success: (res) => {
        if (res.statusCode === 200) {
          resolve(res.data)
        } else {
          reject(newError(this.getErrorMessage(res.statusCode)))
        }
      },
      fail: (err) => {
        reject(newError('网络连接失败'))
      }
    })
  })
}

// 调用时使用 try-catch
try {
const info = awaitthis.getProjectInfo(owner, repo)
// 处理成功
} catch (error) {
this.showError(error.message)
}

// 定义扩展类型
interface UniRequestResponse {
  statusCode: number
  data: any
  header: Record<string, any>
  cookies: string[]
}

// 使用类型断言
const res = await uni.request({ /* ... */ }) as UniRequestResponse

// 或定义全局类型
declare global {
interface Uni {
    request(options: UniRequestOptions): Promise<UniRequestResponse>
  }
}

// ❌ 错误写法
saveHistory() {
  uni.setStorage({
    key: 'history',
    data: this.history
  })
}

// ✅ 正确写法（同步）
saveHistory() {
try {
    uni.setStorageSync('history', JSON.stringify(this.history))
  } catch (error) {
    console.error('保存失败', error)
  }
}

// ✅ 或使用异步 + 防抖
let saveTimer: number | null = null

saveHistory() {
if (saveTimer) clearTimeout(saveTimer)

  saveTimer = setTimeout(() => {
    uni.setStorage({
      key: 'history',
      data: JSON.stringify(this.history),
      success: () =>console.log('保存成功'),
      fail: (err) =>console.error('保存失败', err)
    })
  }, 500)
}

// 添加深度限制和超时控制
async getProjectDirectory(
  owner: string,
  repo: string,
  path: string = '',
  currentDepth: number = 0,
  maxDepth: number = 5,  // 默认限制
  timeout: number = 30000// 30秒超时
) {
// 深度检查
if (maxDepth > 0 && currentDepth >= maxDepth) {
    return []
  }

// 超时控制
const timeoutPromise = newPromise((_, reject) => {
    setTimeout(() => reject(newError('请求超时')), timeout)
  })

const fetchPromise = this.fetchDirectoryContent(owner, repo, path)

try {
    const data = awaitPromise.race([fetchPromise, timeoutPromise])
    // 继续处理...
  } catch (error) {
    if (error.message === '请求超时') {
      this.showError('获取目录超时，请尝试减小深度')
    }
    return []
  }
}

// ❌ 错误写法
{
"pages": [
    // 这是首页
    {
      "path": "pages/index/index"
    }
  ]
}

// ✅ 正确写法
{
"pages": [
    {
      "path": "pages/index/index"
    }
  ]
}

// 使用 uni.storage 本地加密存储
uni.setStorageSync('gitcode_token', this.token)

// 未来计划：使用设备密钥加密
import crypto from'crypto'

function encryptToken(token: string, key: string): string {
const cipher = crypto.createCipher('aes-256-cbc', key)
let encrypted = cipher.update(token, 'utf8', 'hex')
  encrypted += cipher.final('hex')
return encrypted
}

// ✅ 良好的代码结构
exportdefault {
  data() {
    // 1. 基础数据
    // 2. UI 状态
    // 3. 业务数据
  },

  onLoad() {
    // 页面加载时的初始化
  },

  methods: {
    // 1. 用户交互方法
    // 2. API 请求方法
    // 3. 数据处理方法
    // 4. 工具方法
  }
}

// ✅ 完善的错误处理
try {
const result = awaitthis.apiCall()
this.handleSuccess(result)
} catch (error) {
// 记录错误
console.error('操作失败:', error)

// 用户友好的提示
this.showError(this.getUserFriendlyMessage(error))

// 恢复 UI 状态
this.resetUIState()
}

// ✅ 完整的用户反馈流程
async performAction() {
// 1. 显示加载状态
this.isLoading = true

try {
    // 2. 执行操作
    const result = awaitthis.doSomething()

    // 3. 成功反馈
    this.showSuccess('操作成功')
    uni.vibrateShort()

    // 4. 更新 UI
    this.updateUI(result)
  } catch (error) {
    // 5. 错误反馈
    this.showError(error.message)
  } finally {
    // 6. 清理状态
    this.isLoading = false
  }
}

// ✅ 性能优化技巧

// 1. 防抖
const debouncedSearch = debounce(this.search, 300)

// 2. 节流
const throttledScroll = throttle(this.onScroll, 100)

// 3. 懒加载
const lazyLoadImages = () => {
// 仅加载可见区域图片
}

// 4. 缓存
const cache = new Map()
asyncfunction fetchWithCache(key) {
if (cache.has(key)) {
    return cache.get(key)
  }
const data = await fetch(key)
  cache.set(key, data)
return data
}