【鸿蒙征文】鸿蒙开发踩坑日记：一位前端开发者的血泪成长史

日记一：环境搭建——“Hello, World!” 前的下马威

坑点： 模拟器启动失败，报错 HAXM is not installed或 VT-x is not available。

踩坑过程：

信心满满地安装完 DevEco Studio，创建第一个 Hello World 项目，点击运行模拟器。结果，控制台报出一串红色错误，模拟器屏幕一片漆黑。心里“咯噔”一下，难道第一步就卡住了？

排查与解决：

1. 检查BIOS： 重启电脑，狂按 F2/Del 键进入 BIOS 设置。找到 Intel Virtualization Technology（或 AMD 的 SVM Mode）选项，确保其状态为 Enabled。这是最根本的原因。
2. 开启Windows功能： 在 Windows 搜索栏输入“启用或关闭 Windows 功能”，确保 Hyper-V 和 Windows 虚拟机监控平台 已被勾选。完成后需要重启电脑。
3. 选择正确的模拟器： 在 DevEco Studio 的设备管理器中，确保下载的是 API 9或更高版本的模拟器。低版本 API 的模拟器可能存在兼容性问题。

心得： 鸿蒙开发环境的搭建，第一步就是和硬件虚拟化打交道。这提醒我，移动开发生态已与 Web 开发那种“开箱即用”的体验截然不同。

日记二：UTS 类型系统 —— “像”TypeScript，但不是 TypeScript

坑点一：Map.forEach的消失

代码：

let myMap = new Map<string, number>();  
myMap.set('apple', 5);  
// 在 iOS 上运行良好，在鸿蒙上报错！  
myMap.forEach((value, key) => {  
  console.log(key, value);  
});

错误： TypeError: undefined is not callable

解决方案：

// 方案1：使用 for...of 循环  
for (let [key, value] of myMap.entries()) {  
  console.log(key, value);  
}  

// 方案2：更保险的做法，先判断平台或方法是否存在  
if (myMap.forEach) {  
  myMap.forEach((value, key) => { /* ... */ });  
} else {  
  for (let [key, value] of myMap.entries()) { /* ... */ }  
}

坑点二：隐式类型转换的终结

代码：

let data: string | null = getDataFromAPI();  
// Web 中常见的真值判断，在 UTS 中报错！  
if (data) {   
  processData(data);  
}

错误： The condition expression must be of boolean type.

解决方案：

// 必须进行显式的布尔判断  
if (data != null) {  
  processData(data);  
}  

// 或者判断字符串长度  
if (data?.length > 0) {  
  processData(data;  
}

心得： UTS 的强类型特性像一位严格的老师，逼着我写出更严谨、更少歧义的代码。虽然初期不适应，但从代码质量角度看，是件好事。

日记三：页面布局与样式 —— CSS 的“阉割版”体验

坑点一：100vh的陷阱与滚动失效

代码：

<template>  
  <view class="container">  
    <scroll-view scroll-y class="scroll-area">  
      <!-- 长内容 -->  
    </scroll-view>  
    <view class="fixed-bottom">我是一个底部固定栏</view>  
  </view>  
</template>  

<style>  
.container {  
  height: 100vh; /* 鸿蒙不支持 vh！ */  
}  
.scroll-area {  
  height: 100%; /* 继承自一个高度无效的容器，滚动失效 */  
}  
</style>

现象： 页面无法滚动，scroll-view区域高度为 0。

解决方案：

<template>  
  <!-- 关键：让 scroll-view 作为根节点或充满整个页面 -->  
  <scroll-view scroll-y class="page-root">  
    <!-- 所有内容，包括原本想固定的元素，都放在里面 -->  
    <view class="content">可滚动内容</view>  
    <view class="bottom-placeholder"></view>  
    <view class="fixed-bottom">利用 absolute 或 fixed 定位模拟固定</view>  
  </scroll-view>  
</template>  

<style>  
.page-root {  
  width: 100%;  
  height: 100%; /* 使用 100% 而不是 100vh */  
  position: relative; /* 为固定定位元素提供参考 */  
}  
.fixed-bottom {  
  position: absolute;  
  bottom: 0;  
  width: 100%;  
}  
.bottom-placeholder {  
  height: 100rpx; /* 为固定底部留出占位空间，避免内容被遮挡 */  
}

坑点二：Flex 布局的微妙差异

在 Web 中，display: flex的容器默认是 flex-direction: row。在鸿蒙的 text组件嵌套 span时，我发现 Flex 布局的表现有时与 Web 有细微差别，导致文字排版错乱。

解决方案： 尽量显式地写明 flex-direction，避免依赖默认值。对于复杂布局，多使用 align-items和 justify-content进行微调。

心得： 必须彻底抛弃 Web 的“文档流”思维，拥抱原生应用的“盒子模型”和明确的滚动容器概念。布局要更“笨拙”但更精确。

日记四：数据库操作 —— 最诡异的“数据隐身术”

坑点：查询结果对象“看起来有数据，却取不出来”

代码：

// 执行查询  
const result = db.query(‘SELECT name, count FROM ingredients’);  
const rows = result.maps;  
console.log(‘结果行数:’, rows.length); // 输出： 结果行数: 5  
console.log(‘第一行:’, JSON.stringify(rows[0])); // 输出： 第一行: {}  

// 以下代码在 iOS 上正常，在鸿蒙上为 undefined  
const name = rows[0][‘name’];

现象： 数据“幽灵”，日志显示有数据，但代码无法访问。

根源： 鸿蒙平台返回的 rows不是普通对象数组，而是 Map<string, any>[]！ JSON.stringify对 Map 序列化会得到空对象 {}。

解决方案：

// 封装一个强大的兼容性取值函数  
function getRowValue(row: any, key: string, defaultValue: any = null): any {  
  if (row == null) return defaultValue;  

  // 方法1：判断是否是 Map  
  if (row instanceof Map) {  
    return row.get(key) ?? defaultValue;  
  }  
  // 方法2：判断是否拥有 get 方法 (更通用)  
  else if (typeof row.get === ‘function’) {  
    return row.get(key) ?? defaultValue;  
  }  
  // 方法3：默认为普通对象  
  else {  
    return row[key] ?? defaultValue;  
  }  
}  

// 使用  
const name = getRowValue(rows[0], ‘name’);  
const count = getRowValue(rows[0], ‘count’, 0);

心得： 跨平台开发中，“数据序列化/反序列化”是头号隐形杀手。不能相信表面现象，必须对关键数据的实际类型进行运行时判断。

日记五：网络请求与生命周期 —— 异步世界的时序陷阱

坑点：onLoad中发起请求，在 onReady中访问数据却为 null

代码：

export default {  
  data() {  
    return {  
      recipeData: null  
    }  
  },  
  onLoad() {  
    uni.request({  
      url: ‘/api/recipe’,  
      success: (res) => {  
        this.recipeData = res.data; // 异步赋值  
      }  
    });  
  },  
  onReady() {  
    // 企图使用数据渲染视图，但 recipeData 很可能还是 null！  
    this.renderChart(this.recipeData); // 报错！  
  }  
}

解决方案：

1. 使用状态管理： 引入 Pinia，在请求成功的回调中提交 mutation 改变状态，组件通过 computed 属性响应式地获取数据。

2. 条件渲染： 在模板中根据数据是否存在进行判断。

   <template>  
    <view>  
      <chart v-if=“recipeData” :data=“recipeData”></chart>  
      <loading v-else>加载中…</loading>  
    </view>  
   </template>  

3. 使用 Promise/async-await： 确保在数据准备好后再执行后续操作。

   async onLoad() {  
    try {  
      this.recipeData = await this.fetchRecipeData();  
      // 数据获取成功后，再执行需要数据的操作  
      this.$nextTick(() => {  
        this.renderChart(this.recipeData);  
      });  
    } catch (error) {  
      console.error(‘数据加载失败:’, error);  
    }  
   }  

心得： 生命周期钩子和异步操作的配合，是前端开发永恒的课题。在鸿蒙这种更接近原生的环境中，对时序的控制要求更为严格。

总结：我的踩坑生存法则

1. 假设一切都有平台差异： 对任何 API、组件、样式属性，都抱有一丝怀疑，优先查阅鸿蒙专属文档。
2. 日志是最好（有时是唯一）的调试工具： 不仅要打印值，还要打印类型（typeof, instanceof）。
3. 封装兼容层： 将平台差异（如数据库取值、网络库）封装成统一的工具函数，是长期项目的必备架构。
4. 小步快跑，频繁测试： 每实现一个小功能，就在鸿蒙模拟器或真机上跑一遍，避免错误累积。
5. 拥抱社区： uni-app 的官方论坛、钉钉群和 GitHub issues 是解决问题的宝库，你踩的坑，大概率已经有人踩过并分享了解决方案。

踩坑虽苦，但每解决一个坑，对鸿蒙平台和跨平台开发的理解就加深一层。现在回头看，这些坑都成了我宝贵的经验财富。希望这份日记，能为你照亮前行的路，助你少走弯路！