HarmonyOS-ArkTS-新手完整复现-含环境配置

HarmonyOS ArkTS 新手完整复现从环境配置到网络列表 App超细步骤欢迎访问开源鸿蒙 PC 开发者社区https://harmonypc.csdn.net/。摘要本文面向零基础/初学者完整讲清如何在 Windows 上配置 DevEco Studio HarmonyOS SDK 环境如何新建 Empty Ability 工程如何实现「启动自动请求 API展示前 10 条含 Loading 与错误提示」如何 Build/Run 到模拟器或真机验收。关键词HarmonyOS、DevEco Studio、ArkTS、环境配置、HTTP 请求、List、ForEach一、先决条件你需要准备什么Windows 10/1164 位稳定网络下载 SDK/组件DevEco Studio建议最新稳定版至少 20GB 可用磁盘空间可用设备二选一HarmonyOS 模拟器HarmonyOS 真机开启开发者选项与 USB 调试二、环境配置从 0 开始2.1 安装 DevEco Studio前往华为开发者官网下载安装包。安装完成后打开 DevEco Studio。首次启动会引导安装 SDK请继续下一节。2.2 安装 HarmonyOS SDK重点在 DevEco Studio 中进入 SDK 管理页面Settings/Preferences 内的 HarmonyOS SDK。建议安装以下组件按你项目版本调整API 12你目标是鸿蒙 6.0ArkTS 相关工具链Build Tools / Command Line ToolsEmulator如果要用模拟器如果后续出现SDK component missing通常是某个组件没装全或损坏回到 SDK 管理器重新勾选安装即可。2.3 配置 JDK如 IDE 未自动识别DevEco 通常自带运行时不建议新手手动乱改。若提示 JDK 问题在 DevEco 的 JDK 设置里指向 IDE 推荐路径。2.4 配置设备调试真机手机进入开发者模式。开启 USB 调试/允许调试安装。USB 连电脑后点「允许调试」。在 DevEco 设备管理里看到设备在线即完成。2.5 模拟器准备可替代真机在 Device Manager 创建模拟器实例。启动模拟器。确保 Run 目标可选中该模拟器。2.6 环境健康检查建议做新建一个最小 Empty Ability直接 Run 一次。能在设备显示默认页面说明环境基本 OK。这一步成功后再进入业务开发能少踩很多坑。2.7 Flutter 环境变量怎么确认含你这次的实际示例如果你已经git clone了 Flutter for OpenHarmony 仓库需要先确认flutter指令到底指向哪一份。以我当前机器的示例仓库根目录是D:\code_flutter。A. 先查当前 flutter 路径在 PowerShell 执行where flutter flutter--version判断标准where flutter第一条若是D:\code_flutter\bin\flutter.bat说明当前就是用这份如果不是说明 PATH 里还有其他 Flutter需要调整环境变量顺序。B. 设置用户环境变量推荐打开「编辑系统环境变量」-「环境变量」。在「用户变量」新增FLUTTER_HOME D:\code_flutter编辑用户变量Path新增%FLUTTER_HOME%\bin把%FLUTTER_HOME%\bin调整到优先位置高于旧 Flutter 路径。关闭并重新打开终端再次执行where flutter flutter--version flutter doctor-vC. 常见问题where flutter出现多个路径删除旧路径或把新路径上移修改后不生效必须重开终端必要时重启 IDE。2.8 ArkUI-X / OpenHarmony 相关环境变量按仓库 README 为准不同版本的 ArkUI-X/Flutter-OHOS 对变量名要求可能不同但通用做法如下先读所用仓库的README.md以文档里的变量名为准。常见会配置JAVA_HOMEJDK 路径OHOS_SDK_HOMEHarmonyOS SDK 路径DEVECO_SDK_HOME部分仓库会这样命名常见 Path 增补%JAVA_HOME%\bin若文档要求OHOS SDK 下工具目录配完后验证java-version flutter doctor-v注意变量名请严格以你当前 clone 的仓库文档为准不要混用其他文章里的旧变量名。三、创建工程Empty AbilityFile - New - Create Project选择Empty Ability填好项目名例如NetListDemo语言选 ArkTS创建完成后确认目录entry/src/main/module.json5entry/src/main/ets/pages/Index.etsentry/src/main/resources/base/profile/main_pages.json四、实现目标功能一步一步改步骤 1配置网络权限编辑entry/src/main/module.json5在顶层module内加入requestPermissions: [ { name: ohos.permission.INTERNET, usedScene: { abilities: [EntryAbility], when: inuse } } ]注意放在module内部若已有requestPermissions请合并不要重复键JSON5 逗号不要漏。步骤 2新建网络工具类新建entry/src/main/ets/utils/NetworkUtils.etsimporthttpfromohos.net.http;import{BusinessError}fromohos.base;/** * 封装 GET 请求将响应 body 解析为 JSON * 若 jsonplaceholder 无法访问可替换为其他可访问的 HTTPS 测试接口 */exportclassNetworkUtils{staticasyncfetchDataT(url:string):PromiseT{consthttpClienthttp.createHttp();try{constresponseawaithttpClient.request(url,{method:http.RequestMethod.GET,readTimeout:10000,connectTimeout:10000});if(response.responseCode200){returnJSON.parse(response.resultasstring)asT;}thrownewError(请求失败状态码${response.responseCode});}catch(err){consteerrasBusinessError;console.error(网络请求错误${e.code},${e.message});constmsge.messagee.message.length0?e.message:网络请求失败code${e.code};thrownewError(msg);}finally{httpClient.destroy();}}}说明ArkTS 下不要直接throw e任意类型要throw new Error(...)否则可能报arkts-limited-throw。步骤 3替换首页Index.ets编辑entry/src/main/ets/pages/Index.ets替换为import{NetworkUtils}from../utils/NetworkUtils;interfacePost{userId:number;id:number;title:string;body:string;}EntryComponentstruct Index{Stateposts:Post[][];StateisLoading:booleanfalse;Stateerror:string;aboutToAppear():void{this.fetchPosts();}// 启动后拉取帖子列表asyncfetchPosts():Promisevoid{this.isLoadingtrue;this.error;try{constdataawaitNetworkUtils.fetchDataPost[](https://jsonplaceholder.typicode.com/posts);this.postsdata.slice(0,10);}catch(err){this.error數據加載失敗請稍後重試;console.error(獲取文章列表失敗${err});}finally{this.isLoadingfalse;}}build(){Column(){Text(數據清單列表).fontSize(24).fontWeight(FontWeight.Bold).margin({bottom:20});if(this.isLoading){LoadingProgress().width(50).height(50).margin({top:50});}elseif(this.error.length0){Text(this.error).fontSize(18).fontColor(#ff0000).margin({top:50});}else{List({space:12}){ForEach(this.posts,(item:Post){ListItem(){Column(){Text(ID:${item.id}).fontSize(14).fontColor(#666666);Text(item.title).fontSize(18).fontWeight(FontWeight.Medium).margin({top:4});Text(item.body).fontSize(14).fontColor(#999999).maxLines(2).textOverflow({overflow:TextOverflow.Ellipsis}).margin({top:8});}.width(100%).padding(16).backgroundColor(#f5f5f5).borderRadius(8);}},(item:Post)item.id.toString());}.width(100%).layoutWeight(1).padding({left:16,right:16});}}.width(100%).height(100%).padding({top:20});}}步骤 4确认首页路由打开entry/src/main/resources/base/profile/main_pages.json确保{src:[pages/Index]}五、编译与运行新手验收流程5.1 Build菜单Build - Build Hap(s)/APP如果成功会显示构建完成日志。5.2 Run 到设备选择目标设备模拟器/真机。点击 Run。等待安装并自动启动应用。5.3 验收标准必须逐条过启动后先短暂显示 Loading然后出现列表前 10 条每项有 ID、标题、摘要摘要 2 行省略断网后显示红色错误提示。六、常见问题环境 代码1SDK component missing回 SDK 管理器检查 API/工具链是否完整可尝试重新安装对应 API 组件。2arkts-limited-throw不要throw e改为throw new Error(...)。3页面没变化检查是否改的是entry/src/main/...检查main_pages.json是否仍指向pages/IndexClean Project 后重建。4接口无法访问先确认设备网络正常可临时替换为其他 HTTPS 测试接口不要改 HTTP 明文。七、本文修改文件清单entry/src/main/module.json5entry/src/main/ets/utils/NetworkUtils.ets新增entry/src/main/ets/pages/Index.etsentry/src/main/resources/base/profile/main_pages.json校验八、结语这个案例为以下链接这篇文章的先导篇建议先看这篇文章再去实践https://blog.csdn.net/2401_83346278/article/details/159946061?spm1001.2014.3001.5502。