鸿蒙ArkTs开发规范简要总结

小白学鸿蒙

已于 2025-03-13 00:31:34 修改

阅读量2.6k

点赞数 22

分类专栏： HarmonyOS开发者百宝箱 HarmonyOS从入门到头秃鸿蒙开发杂谈文章标签： harmonyos 华为鸿蒙鸿蒙系统 arkts arkui

于 2024-04-16 00:29:47 首次发布

本文链接：https://blog.csdn.net/qq_44160056/article/details/137800818

版权

HarmonyOS从入门到头秃同时被 3 个专栏收录

18 篇文章

订阅专栏

HarmonyOS开发者百宝箱

11 篇文章

订阅专栏

鸿蒙开发杂谈

5 篇文章

订阅专栏

本文档围绕ArkTS编程规范展开，规则分为“要求”和“建议”两个级别。“要求”原则上应遵从，“建议”属于最佳实践，可按需采用。下面按不同级别对规范内容进行整理：

要求

多个变量定义和赋值语句：每个语句只声明一个变量，便于添加变量声明和调试。
- 反例：let maxCount = 10, isCompleted = false;
- 正例：let maxCount = 10; let isCompleted = false;
判断变量是否为Number.NaN：必须使用Number.isNaN()方法。
- 反例：if(foo == Number.NaN) {... }
- 正例：if(Number.isNaN(foo)) {... }
数组遍历：优先使用Array对象方法，如forEach()、map()等。
- 反例：通过for循环遍历数组创建新数组。
- 正例：const numbers = [1,2,3,4,5]; const increasedByOne:number[] = numbers.map(num => num + 1);
控制性条件表达式：禁止在控制性条件表达式中执行赋值操作。
- 反例：if(isFoo = false) {... }
- 正例：const isFoo = someBoolean; if(isFoo) {... }
finally代码块：finally代码块中，不得使用return、break、continue或抛出异常，防止代码块非正常结束。
- 反例：

function foo() {
    try{
        //...
        return 1;
    }catch(err) {
        //...
        return 2;
    }finally{
        return 3;
    }
}

- **正例**：

function foo() {
    try{
        //...
        return 1;
    }catch(err) {
        //...
        return 2;
    }finally{
        console.log('XXX!');
    }
}

建议

命名风格：类名、枚举名、命名空间名采用UpperCamelCase风格；变量名、方法名、参数名采用lowerCamelCase风格；常量名、枚举值名全部大写，单词间用下划线隔开。避免使用否定的布尔变量名，布尔型局部变量或方法加表达是非意义的前缀。
- 类名正例：class User { username:string; constructor(username:string) { this.username = username; } sayHi() { console.log('hi'+ this.username); } }
- 变量名正例：let msg = 'Hello world'; function sendMsg(msg:string){ // todo send message }
- 常量名正例：const MAX_USER_SIZE = 10000;
- 布尔变量名反例：let isNoError = true;
- 布尔变量名正例：let isError = false;
缩进与空格：使用空格缩进，大部分场景用2个空格，换行缩进用4个空格，禁止使用tab字符；合理使用空格突出关键字和重要信息，避免不必要空格。
- 缩进正例：

class DataSource{
    id:number = 0
    title:string = ''
    content:string = ''
}

- **空格正例**：`if (isJedi) { fight(); } function fight(): void { console.log('Swooosh!'); }`

代码布局：行宽不超过120个字符；条件语句和循环语句的执行体必须使用大括号；switch语句的case和default需缩进一层；表达式换行时运算符放在行末；字符串建议使用单引号；对象字面量属性超过4个时需换行；把else/catch放在if/try代码块关闭括号的同一行；大括号和语句在同一行。
- 行宽正例：代码行尽量控制在120字符内。
- 条件语句正例：if(condition) { console.log('success'); }
- switch语句正例：

switch(condition) {
    case 0: {
        doSomething();
        break;
    }
    case 1: {
        doOtherthing();
        break;
    }
    default:
        break;
}

- **表达式换行正例**：`if (userCount > MAX_USER_COUNT || userCount < MIN_USER_COUNT) { doSomething(); }`
- **字符串正例**：`let message = 'world';`
- **对象字面量正例**：

interface I{
    name:string
    age:number
    value:number
    sum:number
    foo:boolean
    bar:boolean
}
let obj:I = {
    name:'tom',
    age:16,
    value:1,
    sum:2,
    foo:true,
    bar:false
}

- **else/catch位置正例**：`if (isOk) { doThing1(); doThing2(); } else { doThing3(); }`
- **大括号位置正例**：`function foo(){ //... }`

编程实践：添加类属性的可访问修饰符；不省略浮点数小数点前后的0；避免使用ESObject；使用T[]表示数组类型。
- 类属性修饰符正例：

class C{
    private count: number = 0
    public getCount(): number {
        return this.count
    }
}

- **浮点数正例**：`const num = 0.5; const num = 2.0; const num = -0.7;`
- **ESObject反例**：`let obj:ESObject = getObject(123);`
- **ESObject正例**：`let obj:I = getObject(123);`
- **数组类型正例**：`let x:number[] = [1,2,3]; let y:string[] = ['a','b','c'];`

其他补充

所有文件，包括自动生成的编译文件package.json都要格式化（IDE快捷键Ctrl+Alt+L）；
函数命名，C++大驼峰，TS、JS小驼峰，函数命名注意动宾结构；
静态常量需使用全大写，文件目录使用全小写（不建议包含特殊字符如"-“和”_"等）；
类名使用大驼峰，函数的参数、全局变量和局部变量都使用小驼峰，命名要规范化，见名知意；
if语句后必须跟“{”，哪怕只有一行代码；
有break或return的条件，先break或return再走其他的逻辑；
条件判断，当一个分支达成条件时及时返回，不需要再走其他分支；
代码中避免出现魔鬼数字，需补上注释，或者用符合语义的名词常量代替，如下：

  // One minute has 60 seconds.
  let time = 60

  const ONE_MINUTE = 60
  let time = ONE_MINUTE

字符串拼接使用模板字符串；
组件使用，除了宽高属性可以在一行，其他的属性必须换行；
TS、JS中关于是否添加";“的问题，风格要统一，建议添加”;"；
字符串和图片资源等的使用，支持" $r " 使用的，全部使用 "$ r"引用；
新增文件注意开源协议、版权检查；
截图要使用真机效果图；
readme中使用“.”，不要用“、”，检查错别字；
异步方法中需要返回方法的返回值，不用声明变量，直接return，如下：

  return await this.mediaTest.getFileAssets(fetchOp)

方法中的参数需要类型声明；
import 文件顺序，同类型放一起；
string.json中description要写简要描述，zh下要用中文；
TS、JS语言缩进为2格，C++语言缩进为4格；
涉及应用截图时，图片不能包含人物、关键信息、网络等有侵权风险的资源；
工程中不要配置签名信息，禁止上传local.properties和package-lock.json等系统自动生成的文件；
规范日志格式，统一用[Sample_包名]开头，如时钟日志，使用[Sample_Clock]，日志打印需要使用Hilog接口，建议封装单独的Logger类，示例如下：

import hilog from '@ohos.hilog'
...
class Logger {
  private domain: number = 0xFF00
  private prefix: string = '[Sample_Clock]'
  private format: string = '%{public}, %{public}'
  ...
  debug(...args: any[]) {
    hilog.debug(this.domain, this.prefix, this.format, args)
  }
  ...
}

注释“//”后要加一个空格；如果注释跟在代码后面，则“//”前要加一个空格；

  // 正确示例
  let a = 10

  let a = 10 // 正确示例

代码中避免出现中文字符，要使用资源代替，符合国际化开发标准；
应用包名统一使用“com.samples.xxx”，“xxx”为特性名称；
建议字符串使用单引号较为约定俗成，单引号优于双引号。
判断变量是否为Number.NaN时必须使用Number.isNaN()方法

参考链接: 社区共建Sample合入要求