HarmonyOS 开发文档——入门

应用开发导读

本开发文档指导开发者借助 HarmonyOS SDK 开放能力进行应用开发，建议先通过知识地图了解完整开发旅程，文档核心包含四部分内容：

入门：讲解应用开发基础方法，助力开发者快速搭建首个 HarmonyOS 应用，掌握包结构、资源文件使用及 ArkTS 核心知识，夯实开发基础；
开发：从 HarmonyOS NEXT API 11 起，SDK 以 Kit 为维度提供应用框架、系统、媒体、图形、应用服务、AI 六大领域开放能力，并针对重点能力提供专属开发指导；
工具：介绍 HarmonyOS 开发推荐 IDE——DevEco Studio 的完整用法，涵盖工程创建、签名、调试、安装运行等操作指导；
API 参考：提供各 Kit 开放能力的全量组件与接口说明，方便开发者快速查询接口描述及调用方法。

快速入门

开发准备

本文档面向 HarmonyOS 应用开发初学者，通过构建带页面跳转 / 返回功能的简单应用，帮助快速了解工程目录文件、熟悉开发流程。开始前需掌握两类基础概念，并完成工具准备：基本概念：①UI 框架：HarmonyOS 提供 ArkUI 框架，含组件、布局等 UI 开发能力，支持声明式（ArkTS、适配复杂应用 / 系统开发人员）和类 Web（JS、适配简单界面 / Web 前端人员）两种开发范式；②应用模型：HarmonyOS 抽象提炼的应用能力体系，分已不主推的 FA 模型（API 7 起支持）和当前主推的 Stage 模型（API 9 起新增），快速入门以 Stage 模型为例。工具准备：下载安装最新版 DevEco Studio，完成后可参照 “构建第一个 HarmonyOS 应用（ArkTS）” 上手实践。

构建第一个HarmonyOS应用（ArkTS）

这篇文档将具体带你创建一个最基本的鸿蒙应用，包含两个页面，可以点击按钮在两个页面之间切换。如下图：

下图是模拟器nova 15 Pro的运行界面：

在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/start-with-ets-stage

开发基础知识——应用程序包基础知识

应用程序包概述

应用与应用程序包

应用：为用户提供特定服务的程序。
应用程序包：应用对应的软件包。系统提供包的全生命周期管理，并屏蔽芯片平台差异（x86/ARM，32/64位），确保跨平台运行。

应用的多Module设计机制

模块化开发：将功能划分为独立Module（含代码、资源、库等），各Module可独立编译，便于开发、维护和扩展。
多设备适配：Module可标注支持的设备类型（如平板），应用市场可根据设备类型精准分发适配的包。

Module类型

1. Ability类型Module

实现应用功能，编译生成 HAP包（Harmony Ability Package），是应用安装的基本单位，分为：

entry类型HAP：主模块（含入口界面、图标等），同一设备类型仅能有一个或不含。
feature类型HAP：动态特性模块，可含零到多个。

2. Library类型Module

实现代码和资源共享，分为：

Static Library：编译生成 HAR包（Harmony Archive），静态共享库。
Shared Library：编译生成 HSP包（Harmony Shared Package），动态共享库。

HAR与HSP区别

类型	编译运行方式	发布引用方式
HAR	代码资源随使用方编译，多份拷贝	支持应用内引用，也可发布至OHPM仓供其他应用使用
HSP	独立编译，运行时仅一份拷贝	一般随应用打包，支持应用内引用（集成态HSP可跨应用引用）

包类型选择建议

Module类型	包类型	适用场景
Ability	HAP	应用功能模块，可独立安装运行
Static Library	HAR	静态共享，作为二方/三方库发布，复用代码资源（但多包引用会导致重复拷贝）
Shared Library	HSP	动态共享，多包依赖同一共享包时使用，可避免重复拷贝，减小包体积

规格对比（√支持，×不支持）

规格	HAP	HAR	HSP
声明UIAbility/ExtensionAbility组件	√	√	√
声明pages页面	√	×	√
含资源与.so文件	√	√	√
依赖其他HAR/HSP	√	√	√
独立安装运行	√	×	×

说明：

HAR不支持声明pages页面（避免路径冲突），但可含pages并通过Navigation跳转。

若HAR依赖HSP，则仅限应用内使用，不可发布至外部仓。

HAR/HSP均不支持循环依赖与依赖传递。

开发基础知识——应用程序包基础知识——应用程序包结构

Stage模型应用程序包结构

Stage模型应用包在不同阶段呈现不同结构：开发态下，工程包含AppScope目录（存放全局配置与资源）及各Module目录（含配置文件、ArkTS源码、资源文件等）；编译态时，Module会编译为HAP/HAR/HSP文件，依赖的HAR会直接打包进HAP/HSP中；发布态则将所有HAP和HSP文件打包为.app格式的App Pack（含描述文件pack.info），作为应用市场上架和安装分发的基本单元。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-package-structure-stage

FA模型应用程序包结构

FA模型应用程序包结构主要由配置文件config.json与assets资源文件夹构成。在assets文件夹内，entry子目录存放resources资源文件及其索引表resources.index，js子目录则存放编译后的代码文件。整个Bundle包在构建时会自动生成pack.info文件以描述各HAP包的属性。需注意，FA模型为旧版架构（API 8及更早），当前建议使用Stage模型进行开发。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-package-structure-fa

开发基础知识——应用程序包基础知识——应用程序包开发与使用

HAP

HAP（Harmony Ability Package）是HarmonyOS应用安装与运行的基本模块包，分为entry（主模块，应用入口）和feature（动态特性模块，按需安装）两种类型。应用可由单个entry包或“entry+多个feature包”组成。开发时可在DevEco Studio中创建Module并添加Ability/Page，支持引用HAR/HSP共享包；调试可通过DevEco Studio或hdc/bm命令行工具安装、更新HAP进行。需注意：HAP不支持对外导出接口和组件；多HAP场景下同一设备类型只能有一个entry包，且所有HAP/HSP的签名必须一致。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hap-package

HAR

HAR（Harmony Archive）是HarmonyOS静态共享包，包含代码、C++库、资源和配置文件，用于在模块或应用间共享ArkUI组件和代码。它支持应用内共享，也可作为二方/三方库发布到OHPM仓供其他应用使用。HAR不支持独立安装运行，需被HAP/HSP依赖引用；从API 14开始支持声明UIAbility组件，API 18起支持声明ExtensionAbility组件，但不支持声明pages页面（可通过Navigation跳转）。开发时通过Index.ets文件导出ArkUI组件、类方法、native方法和资源；引用时需在oh-package.json5中配置依赖。需注意：HAR依赖HSP时仅限应用内使用；多包引用同一HAR会导致代码资源重复拷贝；不支持循环依赖和依赖传递；构建时可开启混淆以保护代码。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/har-package

HSP

HSP（Harmony Shared Package）是HarmonyOS动态共享包，包含代码、C++库、资源和配置文件，用于在应用内或多个应用间（集成态HSP）共享代码资源。它随宿主应用包一同发布，与宿主同进程且包名一致。HSP不支持独立安装/运行，需被HAP或其他HSP依赖；从API 14起支持声明UIAbility（不支持入口类型），API 18起支持声明ExtensionAbility（不支持入口类型）。开发时通过Index.ets导出ArkUI组件、类方法、native方法及资源（推荐通过资源管理类封装导出）；引用时需在oh-package.json5中配置依赖，并可通过页面路由实现HSP内页面的跳转。需注意：HSP不支持循环依赖和依赖传递；多HAP/HSP共用同一HSP可避免代码重复拷贝，有效控制包体积。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/in-app-hsp

开发基础知识——应用程序包基础知识——应用程序包安装卸载与更新

应用安装卸载与更新开发指导

应用安装、卸载与更新开发流程如下：开发者可使用bm命令行工具进行调试安装（install）和卸载（uninstall）；应用上架市场后，终端用户可通过应用市场进行安装与卸载。应用更新时，开发者需先修改app.json5中的versionCode版本号，然后重新打包发布；终端用户可通过两种方式更新：一是接收应用市场推送通知并升级，二是在应用内通过集成检测更新功能弹出升级对话框完成更新。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-package-install-uninstall

应用安装与更新一致性校验

应用在多模块安装或更新时，系统会对签名证书和配置文件进行一致性校验以保障安全合法性。签名证书校验字段包括：appId/appIdentifier（更新时任一相同即可）、appDistributionType、appProvisionType和apl（同版本更新时需校验）。配置文件校验字段包括：bundleName、versionCode、targetBundleName、targetPriority、bundleType和installationFree（始终校验）；apiReleaseType（仅更新时校验）；debug（仅安装时校验）。此外，同版本更新时entry类型的moduleName不可修改，且使用打包工具会进行前置合法性校验。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/install-and-update-consistency-verification

开发基础知识——应用配置文件（Stage模型）

应用配置文件概述（Stage模型）

在Stage模型应用项目中，app.json5文件用于定义应用的全局配置（如Bundle名称、厂商、版本号及设备类型配置），而每个Module则通过module.json5文件配置其基本信息（名称、类型、描述、支持的设备类型）、UIAbility与ExtensionAbility组件描述以及运行所需权限。这些配置文件为编译工具、操作系统和应用市场提供了必要信息，且在编译后，每个模块的app.json5与module.json5内容会合并生成最终的module.json文件。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-configuration-file-overview-stage

app.json5配置文件

app.json5是Stage模型应用中的全局配置文件，位于工程名/AppScope/目录下，用于向编译工具、操作系统和应用市场提供应用的基本信息。其核心内容包括：应用的Bundle名称（bundleName）、厂商（vendor）、版本号（versionCode和versionName）、图标（icon）、名称标签（label）、最小与目标API版本（minAPIVersion和targetAPIVersion）等基础配置；同时支持针对不同设备类型（如tablet、car等）进行差异化设置（如独立的最小API版本）。配置文件还可定义应用环境变量（appEnvironments）、多开模式（multiAppMode）、字体跟随系统配置（configuration）等高级特性。编译时，该文件内容会与模块的module.json5合并生成最终的module.json。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-configuration-file

module.json5配置文件

module.json5是Stage模型中每个模块的配置文件，位于工程名/模块名/src/main/目录下，用于定义模块的基本信息、组件配置及运行所需权限。其核心内容包括：模块名称（name）与类型（type，如entry、feature、har、shared）、支持的设备类型（deviceTypes）、是否随应用安装（deliveryWithInstall）及免安装支持（installationFree）等基础配置；同时详细定义了UIAbility组件（abilities）与ExtensionAbility组件（extensionAbilities）的属性和能力（如启动模式、图标、权限、技能等）、应用运行时需申请的权限（requestPermissions）、页面路由配置（pages和routerMap）、以及元数据（metadata）等。该配置文件为编译工具、操作系统和应用市场提供了模块的详细规格信息，编译后其内容会与app.json5合并生成最终的module.json文件。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/module-configuration-file

开发基础知识——应用配置文件（FA模型）

应用配置文件概述（FA模型）

FA模型的应用配置文件config.json是应用项目的必备文件，用于向编译工具、操作系统和应用市场提供应用的基本信息。该文件由三个必需部分组成：app（定义应用的全局配置，如厂商、Bundle名称和版本号）、deviceConfig（定义应用在具体设备上的配置信息）和module（定义当前HAP包的配置，包括主Ability、设备类型支持、Ability组件详情、分发设置及JS/ETS页面配置等）。该配置文件完整描述了应用的包结构、组件能力及设备适配信息。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-configuration-file-overview-fa

app对象内部结构

在FA模型的config.json配置文件中，app对象定义了应用的全局配置信息。其核心属性包括：bundleName（应用的唯一标识，采用反向域名形式，长度7-128字节，不可缺省）、vendor（开发厂商描述，可缺省）、version（版本信息对象，包含展示给用户的name和管理用的code，均不可缺省）以及apiVersion（标识应用依赖的API版本，包含最低兼容版本compatible、目标版本target和发布类型releaseType，由DevEco Studio在构建时自动填充）。此外，还包含用于模拟器调试的smartWindowSize/smartWindowDeviceType及用于内存检测的asanEnabled等可选字段。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-structure

deviceConfig内部结构

在FA模型的config.json配置文件中，deviceConfig对象用于定义应用在不同设备类型（如phone、tablet、tv、car、wearable等）上的特有配置。其核心属性包括：process（指定应用或Ability的进程名）、keepAlive（仅系统应用可配置为true以保持常驻运行）、supportBackup（是否支持备份恢复）、compressNativeLibs（控制libs库的压缩存储与安装解压行为）以及network（网络安全配置，可设置是否允许明文流量cleartextTraffic并可通过securityConfig的domainSettings针对特定域名进行细粒度控制）。该对象允许为不同设备类型提供差异化配置，若未指定则采用默认值。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/deviceconfig-structure

module对象内部结构

在FA模型的config.json配置文件中，module对象定义了HAP包的配置信息。其核心属性包括：package（HAP包名，采用反向域名格式，不可缺省）、deviceType（支持的设备类型数组，不可缺省）、distro（分发描述对象，包含模块名称、类型、是否免安装及随应用安装等，不可缺省）、abilities（Ability组件数组，定义各Ability的名称、类型、图标、技能等）、js（定义JS/ETS模块的页面、窗口及开发模式）。此外，还包含mainAbility（主Ability）、name（类名）、metadata（元数据）、reqPermissions（权限申请）、shortcuts（快捷方式）、commonEvents（公共事件静态订阅）及distroFilter（设备分发过滤策略）等可选字段。该对象完整描述了HAP的功能结构、设备适配及分发规则。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/module-structure

开发基础知识——典型场景的开发指导

创建应用静态快捷方式

静态快捷方式允许用户长按应用图标快速直达特定功能（如地图导航到“公司”、便签“新建”）。配置方法：首先在string.json中定义快捷方式标签；然后在模块的/resources/base/profile/目录下创建shortcuts_config.json文件，通过shortcutId、label、icon及目标组件的wants参数定义每个快捷方式；最后在module.json5的对应Ability的metadata中添加name为”ohos.ability.shortcuts”、resource指向快捷方式配置文件的条目。安装后，长按应用图标即可显示并触发这些快捷方式。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/typical-scenario-configuration

创建应用分身

应用分身功能允许在同一设备上安装多个相同应用的独立副本（如社交或游戏账号双开），实现数据隔离且互不影响。配置时，只需在AppScope/app.json5文件的app对象内添加multiAppMode字段，设置multiAppModeType为”appClone”并指定maxCount（最大分身数量）。编译安装后，用户在系统设置的“应用分身”中即可创建分身；桌面上分身应用图标会带有角标标识。需注意：主应用与分身共享应用本体（更新同步），但数据与配置彼此独立；主应用卸载会连带删除所有分身，而卸载分身不影响主应用；输入法应用不支持此功能。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-clone

创建应用多实例

应用多实例功能允许在2in1设备上同时运行同一应用的多个独立进程（如社交或游戏多账号登录），各进程数据共享但运行彼此独立。配置方法：在App/app.json5的app对象中添加multiAppMode字段，设置multiAppModeType为”multiInstance”并指定maxCount（最大实例数）。安装后，用户通过右键点击桌面应用图标并选择“打开”即可启动新的独立实例。需注意：所有实例图标相同、共享文件数据，且仅支持2in1设备。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/multiinstance

配置应用图标和名称

应用图标和名称用于在桌面、通知栏等场景展示应用。配置优先级：若HAP包含UIAbility且其skills中配置了entity.system.home与ohos.want.action.home，则优先使用module.json5中该Ability的icon和label（多个时以mainElement为准）；否则使用app.json5中的配置。若HAP无UIAbility，则直接使用app.json5的配置。

配置方法：

单层图标：在app.json5或module.json5的icon字段引用图片资源（如$media:app_icon），label字段引用字符串资源。

分层图标：需创建前景/背景图片及对应的分层图标JSON描述文件（如layered_image.json），然后在配置中引用该JSON文件作为icon。无论单层或分层图标，若通过module.json5配置，还需在对应Ability的skills中添加entity.system.home和ohos.want.action.home以确保图标在桌面显示。编译时，AppScope目录下的资源会覆盖模块内同名资源。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/layered-image

HAR转HSP指导

将HAR转换为HSP的步骤如下：首先在HAR模块的module.json5中将type改为”shared”，并添加deliveryWithInstall: true及pages配置（指向main_pages.json）。接着在resources/base/profile/下创建main_pages.json定义页面路由，并在ets/pages/下创建对应的页面文件（如PageIndex.ets）。然后删除build-profile.json5中的consumerFiles字段，将hvigorfile.ts内容替换为HSP专用任务（hspTasks），并在oh-package.json5中增加”packageType”: “InterfaceHar”。最后在项目根目录的build-profile.json5中为HSP模块配置targets。转换后需注意HSP与HAR在组件使用上的差异。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/har-to-hsp

HSP转HAR指导

将HSP转换为HAR的步骤如下：首先在HSP模块的module.json5中将type改为”har”，并删除deliveryWithInstall和pages字段。接着删除resource/base/profile/下的main_pages.json文件。然后将hvigorfile.ts内容替换为HAR专用任务（harTasks），并在oh-package.json5中移除packageType配置。最后在项目根目录的build-profile.json5中删除该模块的targets配置。转换后需注意HAR与HSP在组件使用上的差异。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hsp-to-har

HAP转HAR指导

将HAP转换为HAR的步骤如下：首先在HAP模块的module.json5中将type改为”har”，并删除mainElement、deliveryWithInstall、installationFree和pages字段；同时根据API版本限制，若版本不兼容需删除extensionAbilities（API 18前或非支持类型）或abilities（API 13及以前）标签及相关组件。接着删除src/main/resources/base/profile/下的main_pages.json文件。然后将hvigorfile.ts内容替换为HAR编译任务（harTasks）。随后在模块根目录创建Index.ets作为导出入口，并在oh-package.json5的main字段中配置该文件。最后在项目根目录的build-profile.json5中删除该模块的targets配置。转换后需注意HAR与HAP在组件使用上的差异。在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hap-to-har

集成态HSP

集成态HSP是应用内HSP的中间编译产物，用于解耦使用方bundleName与签名的强依赖，允许多个不同bundleName的应用共享同一动态共享包（如集团内多应用共用基建HSP）。仅支持Stage模型且需API 12及以上版本。

配置流程：

创建方：在工程级build-profile.json5中设置useNormalizedOHMUrl: true；在HSP模块的build-profile.json5中设置integratedHsp: true；最后对模块进行签名并打包为tgz文件。

使用方：将tgz包放入entry/libs/目录，在主模块的oh-package.json5中添加文件依赖（如”file:./libs/library-default.tgz”），并在工程级build-profile.json5中同样设置useNormalizedOHMUrl: true。使用前需用自身签名对集成态HSP重新签名并优先安装。

在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/integrated-hsp

开发基础知识

应用程序包常见问题

常见问题如下：

如何获取签名指纹
什么是appIdentifier
如何获取appIdentifier
什么是appId
如何获取appId

在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/common-problem-of-application

应用程序包术语

在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-package-glossary

入门——基础入门

资源分类与访问

资源分为应用资源（开发者自定义）和系统资源（系统提供）。应用资源按目录管理：

base目录：默认目录，存放基础元素（字符串、颜色等）及媒体、配置文件，编译为二进制并分配资源ID。
限定词目录：按场景/设备特征（如语言zh_CN、颜色模式dark、屏幕密度ldpi）组合命名，存放适配资源，编译为二进制并分配资源ID。
rawfile/resfile目录：存放原始文件（如图片、音频），不编译、无资源ID，通过文件路径访问。

资源组目录包括element（JSON格式的基础元素）、media（图片、音视频）和profile（自定义JSON配置）。

资源访问：

单HAP包：通过$r('app.type.name')访问编译资源（如$r('app.string.hello')），通过$rawfile('filename')访问原始文件。
跨HAP/HSP包：相同bundle内跨模块访问需创建模块上下文获取ResourceManager，或使用$r('[模块名].type.name')直接引用。
系统资源：通过$r('sys.type.name')访问（如$r('sys.color.ohos_id_color_emphasize')）。

资源匹配：系统根据设备状态（语言、横竖屏、颜色模式等）按优先级匹配限定词目录，未匹配时回退到base目录。rawfile/resfile不参与匹配。

高级特性：

可翻译特性：element目录下的字符串资源可通过attr属性标记翻译状态。
指定配置资源：通过getOverrideResourceManager()获取特定语言/配置的资源。
overlay机制：通过静态配置或动态加载overlay资源包实现资源替换，支持界面风格定制。

开发步骤：在resources目录下按需创建限定词目录及资源组目录，添加对应JSON或媒体文件后，通过上述方式访问。

在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/resource-categories-and-access

学习ArkTS语言

初识ArkTS语言

ArkTS是HarmonyOS默认开发语言，在TypeScript基础上强化静态检查与分析，以提升程序稳定性与性能。主要特点包括：

强制使用静态类型，优化编译检查与运行性能；
禁止运行时改变对象布局；
限制运算符语义，如一元加法仅用于数字；
暂不支持Structural typing；
兼容TS/JS生态，便于复用代码。
未来ArkTS将持续演进，增强并发能力、系统类型及分布式开发等特性。

在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-get-started

ArkTS语言介绍

ArkTS是一种专为构建高性能应用设计的编程语言，在TypeScript语法基础上优化，提升运行效率和开发体验。

核心特点

高性能设计：针对移动设备优化，减少运行时开销，支持高效编译与低功耗运行。
TypeScript兼容：保留TypeScript大部分语法，便于开发者快速上手，支持与TypeScript/JavaScript代码无缝集成。
静态类型与空安全：默认禁止空值，需通过联合类型（如 T | null）显式声明可空变量，增强代码安全性。
精简动态特性：限制动态类型，提升执行效率与应用启动速度。

基础语法示例

变量与常量

let name: string='ArkTS';

const version: number=1.0;

类型系统支持基本类型（number、string、boolean）、联合类型、数组、枚举等：
```
typeID=number|string;
```
```
let list:number[]=[1,2,3];
```
```
enum Color { Red, Green, Blue }
```
函数与类支持可选参数、箭头函数、类继承及泛型：

classPerson{

constructor(public name:string){}

greet(){return`Hello, ${this.name}`;}

}

const sum =(a:number, b:number):number=> a + b;

进阶特性

空安全操作：可选链（?.）、空值合并（??）与非空断言（!）。
模块化：通过 export/import 管理代码依赖，支持静态与动态导入。
ArkUI支持：提供声明式GUI编程能力，适用于HarmonyOS应用开发。

总结ArkTS通过强化类型安全、优化运行时性能，并兼容现有TypeScript生态，助力开发者高效构建可靠的移动应用。详细指南可参考官方文档与DevEco Studio工具。

在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/introduction-to-arkts

ArkTS编程规范

一、基本信息

目标：提供编码指南，提升代码规范性、安全性与性能
适用范围：ArkTS开发场景
规则级别：

要求：必须遵守
建议：推荐最佳实践

二、代码风格规范

1. 命名规范

类/枚举/命名空间：UpperCamelCase（例：User、UserType）
变量/方法/参数：lowerCamelCase（例：userName、findUser()）
常量/枚举值：大写+下划线（例：MAX_USER_SIZE）
布尔变量：添加is/has/can前缀，避免否定词（例：isError而非isNoError）

2. 格式规范

缩进：使用空格（建议2空格），禁用Tab
行宽：≤120字符
大括号：

条件/循环语句必须使用{}
左大括号与语句同行
else/catch与右大括号同行

空格规则：

关键字与左括号间加空格（if (）
函数名与左括号间不加空格（foo()）
二元/三元运算符前后加空格

引号：建议使用单引号
对象字面量：属性超过4个时换行显示
变量声明：每行只声明一个变量

三、编程实践规范

1. 声明与类型

类属性：建议显式添加访问修饰符（private/public）
数组类型：建议使用T[]而非Array<T>
浮点数：避免省略小数点前后的0（0.5而非.5）

2. 数据操作

NaN判断：必须使用Number.isNaN()，禁止直接比较
数组遍历：优先使用map()、filter()等数组方法
ESObject：避免非跨语言场景使用，防止性能损耗

3. 流程控制

条件赋值：禁止在条件表达式中赋值（if (isFoo = false)）
finally块：禁止使用return/break/throw，确保正常结束

4. 其他

switch语句：case/default缩进一层
表达式换行：运算符置于行末

核心原则：代码应清晰表达意图，遵循一致性，兼顾可读性与性能优化。

在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-coding-style-guide

学习ArkTS语言——从TypeScript到ArkTS的适配指导

ArkTS语法适配背景

ArkTS适配核心要点

ArkTS在TS基础上强化静态检查，旨在提升代码稳定性和运行性能。

一、稳定性提升

强制静态类型，严格类型验证。
要求类属性显式初始化，避免未定义错误。
精确类型标注（如string | undefined），编译时拦截潜在问题。

二、性能优化

编译为方舟字节码，减少运行时类型检查。
强制空安全（Null Safety），禁止非常值传入，提升执行效率。

三、兼容性规则

API 10+为标准模式：.ets文件需严格遵循ArkTS语法，否则编译失败。
API 10前为兼容模式：语法违规显示警告，仍可编译。

四、与TS/JS交互

支持互操作，但动态类型对象可能绕过静态检查，需注意类型安全。

五、运行时限制

强制严格模式，禁止eval、with、字符串创建函数、循环依赖。
支持科学计数法（如2.e3），与标准TS/JS不同。

总结：适配ArkTS可提高代码健壮性和性能，需遵循其严格类型规则，并注意兼容性要求。

在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-migration-background

从TypeScript到ArkTS的适配规则

核心约束原则

静态类型优先：禁止 any/unknown，需明确类型
对象布局固定：禁止运行时增删属性/方法
类型严格匹配：不支持 Structural Typing
运算符语义限定：如 + 仅用于数值

关键限制项

类型系统

❌ 禁止 any、unknown、条件类型
❌ 禁止索引签名、映射类型
❌ 禁止 #私有字段（用 private）
❌ 禁止对象字面量作类型声明

对象与变量

✅ 用 let 替换 var
❌ 禁止 Symbol()（除 Symbol.iterator）
❌ 禁止 delete、in 运算符
❌ 禁止解构赋值/声明

函数与类

✅ 用箭头函数替换函数表达式
❌ 禁止函数内声明函数
❌ 禁止类表达式
❌ 禁止修改对象方法
❌ 类不可被 implements

语法特性

❌ 禁止 JSX、with、for...in
❌ 禁止 as const 断言
❌ 禁止生成器函数
⚠️ 限制展开运算符使用场景

模块与导入

❌ 禁止 .ts/.js 导入 .ets
❌ import 语句必须前置
❌ 禁止 require、export =

强制检查项

始终启用严格类型检查
禁止 @ts-ignore/@ts-nocheck
catch 子句不能标注类型

级别说明：

错误：必须修改，否则编译失败
警告：推荐修改，未来可能升级为错误

在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/typescript-to-arkts-migration-guide

适配指导案例

详细案例请见在线文档。

在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-more-cases

学习ArkTS语言——ArkTS高性能编程实践

ArkTS高性能编程实践

提供性能敏感场景下的编程建议，帮助编写高性能应用。

声明与表达式

用const声明不变变量const index = 10000;
number类型避免整型/浮点型混用初始化后勿改变数据类型。
避免数值计算溢出加法、乘法等操作避免数值超出INT32范围。
循环中提取常量将循环内不变值移至外部，减少属性访问。

函数

使用参数传递外部变量避免闭包开销。
避免可选参数改用默认参数或必选参数。

数组

数值计算推荐TypedArrayInt8Array等性能更优。
避免稀疏数组勿直接分配超大数组或跳跃赋值。
避免联合类型数组同一数组只存同类型数据。

异常

避免频繁抛出异常循环内优先用条件判断替代try-catch。

核心原则

保持数据类型一致
减少运行时动态开销
预提取重复计算

在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-high-performance-programming

学习ArkTS语言——面向其他语言的ArkTS迁移指导

从Java到ArkTS的迁移指导

在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/getting-started-with-arkts-for-java-programmers

从Swift到ArkTS的迁移指导

在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/getting-started-with-arkts-for-swift-programmers

HarmonyOS术语

在线文档：

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/glossary

HarmonyOS 开发文档——入门

应用与应用程序包

应用的多Module设计机制

Module类型

1. Ability类型Module

2. Library类型Module

HAR与HSP区别

包类型选择建议

规格对比（√支持，×不支持）

一、基本信息

二、代码风格规范

1. 命名规范

2. 格式规范

三、编程实践规范

1. 声明与类型

2. 数据操作

3. 流程控制

4. 其他

核心约束原则

关键限制项

类型系统

对象与变量

函数与类

语法特性

模块与导入

强制检查项

HarmonyOS术语

wang

猜你喜欢

评论抢沙发

应用与应用程序包

应用的多Module设计机制

Module类型

1. Ability类型Module

2. Library类型Module

HAR与HSP区别

包类型选择建议

规格对比（√支持，×不支持）

一、基本信息

二、代码风格规范

1. 命名规范

2. 格式规范

三、编程实践规范

1. 声明与类型

2. 数据操作

3. 流程控制

4. 其他

核心约束原则

关键限制项

类型系统

对象与变量

函数与类

语法特性

模块与导入

强制检查项

HarmonyOS术语

wang

猜你喜欢

评论 抢沙发

评论抢沙发