代碼規(guī)范

1. 所有文件，包括自動(dòng)生成的編譯文件package.json都要格式化（IDE快捷鍵Ctrl+Alt+L）；
2. 函數(shù)命名，C++大駝峰，TS、JS小駝峰，函數(shù)命名注意動(dòng)賓結(jié)構(gòu)；
3. 靜態(tài)常量需使用全大寫，文件目錄使用全小寫（不建議包含特殊字符如"-“和”_"等）；
4. 類名使用大駝峰，函數(shù)的參數(shù)、全局變量和局部變量都使用小駝峰，命名要規(guī)范化，見名知意；
5. if語(yǔ)句后必須跟“{”，哪怕只有一行代碼；
6. 有break或return的條件，先break或return再走其他的邏輯；
7. 條件判斷，當(dāng)一個(gè)分支達(dá)成條件時(shí)及時(shí)返回，不需要再走其他分支；
8. 代碼中避免出現(xiàn)魔鬼數(shù)字，需補(bǔ)上注釋，或者用符合語(yǔ)義的名詞常量代替，如下：

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

9. 字符串拼接使用模板字符串；
10. 組件使用，除了寬高屬性可以在一行，其他的屬性必須換行；
11. TS、JS中關(guān)于是否添加";“的問題，風(fēng)格要統(tǒng)一，建議添加”;"；
12. 字符串和圖片資源等的使用，支持"$r"使用的，全部使用"$r"引用；
13. 新增文件注意開源協(xié)議、版權(quán)檢查；
14. 截圖要使用真機(jī)效果圖；
15. readme中使用“.”，不要用“、”，檢查錯(cuò)別字；
16. 異步方法中需要返回方法的返回值，不用聲明變量，直接return，如下：

  return await this.mediaTest.getFileAssets(fetchOp)

17. 方法中的參數(shù)需要類型聲明；
18. import 文件順序，同類型放一起；
19. string.json中description要寫簡(jiǎn)要描述，zh下要用中文；
20. TS、JS語(yǔ)言縮進(jìn)為2格，C++語(yǔ)言縮進(jìn)為4格；
21. 涉及應(yīng)用截圖時(shí)，圖片不能包含人物、關(guān)鍵信息、網(wǎng)絡(luò)等有侵權(quán)風(fēng)險(xiǎn)的資源；
22. 工程中不要配置簽名信息，禁止上傳local.properties和package-lock.json等系統(tǒng)自動(dòng)生成的文件；
23. 規(guī)范日志格式，統(tǒng)一用[Sample_包名]開頭，如時(shí)鐘日志，使用[Sample_Clock]，日志打印需要使用Hilog接口，建議封裝單獨(dú)的Logger類 ，示例如下：

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

24. 注釋“//”后要加一個(gè)空格；如果注釋跟在代碼后面，則“//”前要加一個(gè)空格；

  // 正確示例let a = 10let a = 10 // 正確示例

25. 代碼中避免出現(xiàn)中文字符，要使用資源代替，符合國(guó)際化開發(fā)標(biāo)準(zhǔn)；
26. 應(yīng)用包名統(tǒng)一使用“com.samples.xxx”，“xxx”為特性名稱；

ReadMe編寫規(guī)范

1. 標(biāo)題：以特性名稱命名；

2. 介紹：介紹sample用了哪些包，具有哪些功能，給出完整包名并附上鏈接；

3. 效果預(yù)覽：屏幕截屏或者視頻，文件不超過(guò)4個(gè)；

   3.1 使用說(shuō)明：介紹應(yīng)用的使用說(shuō)明，具體的操作步驟和用法信息，示例如下：

   1. 在主界面，可以點(diǎn)擊圖片、視頻、文檔、音頻等按鈕進(jìn)入對(duì)應(yīng)目錄的文件列表瀏覽界面；
   2. 在文件列表瀏覽界面，點(diǎn)擊“+”按鈕，可以添加文件；
   3. 在文件列表瀏覽界面，長(zhǎng)按列表項(xiàng)會(huì)出現(xiàn)刪除圖片，點(diǎn)擊刪除圖標(biāo)可以刪除文件；
   4. 在圖片文件列表界面，點(diǎn)擊圖片可以進(jìn)入圖片預(yù)覽界面。

4. 工程目錄：給出項(xiàng)目中關(guān)鍵的目錄結(jié)構(gòu)并描述它們的作用，示例如下：

   entry/src/main/ets/
   |---Application
   |---filemanager
   |   |---data
   |   |   |---FileDataSource.ets             // 懶加載數(shù)據(jù)格式
   |   |---pages
   |   |   |---audio
   |   |   |   |---AudioFileList.ets          // 音頻列表頁(yè)面
   |   |   |---common
   |   |   |   |---FileList.ets               // 同類型文件列表展示頁(yè)面，接收文件類型，展示特定類型的文件列表
   |   |   |---document
   |   |   |   |---DocumentFileList.ets       // 文檔列表頁(yè)面
   |   |   |---image
   |   |   |   |---ImageFileList.ets          // 圖片列表頁(yè)面
   |   |   |   |---ImagePreview.ets           // 圖片預(yù)覽頁(yè)面
   |   |   |---video
   |   |   |   |---VideoFileList.ets          // 視頻列表頁(yè)面
   |   |   |---FileManagerHome.ets            // 首頁(yè)主體內(nèi)容
   |---MainAbility
   |---pages
   |   |---index.ets                          // 首頁(yè)
   Library/src/main/ets/
   |---filemanager
   |   |---components
   |   |   |---ThumbnailImage.ets             // 縮略圖組件
   |   |---fileio
   |   |   |---FileIoManager.ts               // 文件管理，待開發(fā)
   |   |---medialibrary
   |   |   |---MediaLibraryManager.ts         // 主要封裝了mediaLibrary庫(kù)相關(guān)的接口，實(shí)現(xiàn)相關(guān)功能，如：對(duì)文件的增、刪、查和圖片預(yù)覽功能
   |   |---userfilemanager
   |   |   |---UserFileManager.ts             // 封裝userFileManager庫(kù)相關(guān)的接口
   |   |---FileManager.ts                     // 文件管理接口，統(tǒng)一封裝了各模塊對(duì)外提供的功能接口
   |---mock                                   // 本地?cái)?shù)據(jù)
   |---utils                                  // 日志工具
   

5. 具體實(shí)現(xiàn)：
   先描述功能都在哪個(gè)模塊，再具體描述如何實(shí)現(xiàn)這些功能的，以及在哪里使用他們，附上文件鏈接；示例如下：

   • 增添文件、刪除文件、查找指定類型文件文件和預(yù)覽圖片的功能接口封裝在MediaLibraryManager，源碼參考：MediaLibraryManager.ts

     • 使用mediaLibrary.getMediaLibrary來(lái)獲取MediaLibrary對(duì)象;
     • 讀取每個(gè)文件的數(shù)據(jù)：使用MediaLibrary.getFileAssets讀取滿足條件的文件集合FetchFileResult，然后調(diào)用FetchFileResult.getFirstObject();
     • 創(chuàng)建模擬文件：使用MediaLibrary.getPublicDirectory()獲取系統(tǒng)預(yù)定的目錄，然后使用MediaLibrary.createAsset();
     • 刪除指定路徑的文件：使用MediaLibrary.deleteAsset();
     • 獲取預(yù)覽圖：使用image.createImageSource()創(chuàng)建指定的文件資源ImageSource，然后調(diào)用ImageSource.createPixelMap()，接口參考：@ohos.multimedia.image 。

   • 在Library模塊中通過(guò)封裝FileManager向外提供功能接口，如MediaLibraryManager.getPixelMapByFileAsset()，源碼參考：FileManager.ts

     • 如效果預(yù)覽中的圖片列表，讀取指定類型的文件：在FileList.ets
       中調(diào)用FileManager.getFileAssets()；
     • 創(chuàng)建模擬文件：在FileList.ets
       中調(diào)用FileManager.createTxtFileAsset()；
     • 刪除指定路徑的文件：在FileList.ets
       中調(diào)用FileManager.deleteFileAsset()；
     • 獲取縮略圖：在ThumbnailImage.ets 中調(diào)用FileManager.getThumbnail()；
     • 如效果預(yù)覽中的圖片預(yù)覽，獲取預(yù)覽圖：在ImagePreview.ets 中調(diào)用FileManager.getPixelMapByFileAsset()。

6. 相關(guān)權(quán)限：介紹應(yīng)用的使用權(quán)限，附上鏈接；

7. 依賴： 介紹對(duì)其他sample的依賴，附上sample鏈接；

8. 約束與限制：

   6.1 支持應(yīng)用運(yùn)行的操作系統(tǒng)版本和設(shè)備，示例如下：

    本示例僅支持標(biāo)準(zhǔn)系統(tǒng)上運(yùn)行，支持設(shè)備：RK3568;
   

   6.2 API版本、SDK版本（如果依賴Full SDK，附上替換鏈接），示例如下：

    本示例僅支持APIXX版本SDK，版本號(hào)：3.X.X.X；（如果涉及Full SDK還需加上：本涉及涉及使用系統(tǒng)接口：XXX，需要手動(dòng)替換Full SDK才能編譯通過(guò)，具體操作可參考[替換指南]。）
   

   6.3 支持的IDE版本，示例如下：

    本示例需要使用DevEco Studio 3.0 Beta4 (Build Version: 3.0.0.992, built on July 14, 2022)才可編譯運(yùn)行；
   

   6.4 高等級(jí)APL特殊簽名說(shuō)明，示例如下：

    本示例涉及[相關(guān)權(quán)限]為system_basic(或者system_core)級(jí)別（相關(guān)權(quán)限級(jí)別可通過(guò)[權(quán)限定義列表]查看），需要配置高權(quán)限簽名，可參考[特殊權(quán)限配置方法]；
   

9. 下載：給出單獨(dú)下載本工程的命令，在代碼中替換工程目錄并以/結(jié)尾，如下面示例中的 FileManager/FileManager，示例如下：

   如需單獨(dú)下載本工程，執(zhí)行如下命令：

   git init
   git config core.sparsecheckout true
   echo FileManager/FileManager/ > .git/info/sparse-checkout
   git remote add origin https://gitee.com/openharmony/applications_app_samples.git
   git pull origin master
   

ReadMe模板鏈接

工程結(jié)構(gòu)規(guī)范

Sample工程，應(yīng)該區(qū)分開場(chǎng)景業(yè)務(wù)邏輯和特性相關(guān)封裝接口，規(guī)則如下：

1. 包名命名規(guī)則為"com.samples.特性名"，工程名命名規(guī)則為特性名稱，與Readme標(biāo)題保持一致；
2. 特性接口封裝放在Library模塊下，能夠獨(dú)立編譯成har包復(fù)用；
3. 場(chǎng)景業(yè)務(wù)邏輯，展示Library模塊中特性接口的使用，放在entry目錄中；
4. entry/src/main/ets/目錄下的pages目錄中，只放一個(gè)Index.ets，作為入口頁(yè)面；
5. entry/src/main/ets/目錄下創(chuàng)建場(chǎng)景業(yè)務(wù)目錄，存放該場(chǎng)景相關(guān)的業(yè)務(wù)邏輯和頁(yè)面代碼；
6. Library/src/main/ets/目錄下創(chuàng)建特性目錄，目錄下包括components（對(duì)外開放的控件目錄）、feature（特性封裝邏輯目錄）、Feature.ts（對(duì)外開放的特性接口）等；

以FileManager特性為例，工程示例結(jié)構(gòu)如下：

entry/src/main/ets/ 		// 場(chǎng)景業(yè)務(wù)邏輯放在entry目錄下
|---Application 			// 應(yīng)用級(jí)邏輯
|---MainAbility 			// 元能力組件
|---filemanager 			// 場(chǎng)景業(yè)務(wù)功能（如果存在多個(gè)場(chǎng)景，則放在同級(jí)目錄下）
|   |---data 				// 場(chǎng)景業(yè)務(wù)邏輯相關(guān)類或數(shù)據(jù)
|   |---pages 				// 場(chǎng)景業(yè)務(wù)邏輯相關(guān)頁(yè)面
|---pages 					// UI頁(yè)面
|   |---Index.ets 			// pages下只保留一個(gè)Index.ets，作為入口頁(yè)面
|---utils 					// 共用的工具類或者模塊
Library/src/main/ets/ 		// 特性接口封裝放在Library模塊下，能夠獨(dú)立編譯成har包復(fù)用
|---filemanager 			// 特性相關(guān)封裝類
|   |---components 			// 特性相關(guān)UI控件類，需要對(duì)外開放（部分特性涉及對(duì)外提供復(fù)用UI控件）
|   |   |---FileImage.ets
|   |---fileio 				// 封裝了特性相關(guān)接口，如果存在多個(gè)模塊，放在多個(gè)目錄下如fileio、medialibrary、userfilemanager，不對(duì)外開放
|   |   |---FileIoManager.ts
|   |---medialibrary
|   |---userfilemanager
|   |---FileManager.ts 		// 對(duì)外開放的特性接口，無(wú)具體實(shí)現(xiàn)（實(shí)現(xiàn)在fileio、medialibrary等模塊中）
|---mock 					// 模擬數(shù)據(jù)
|---utils 					// 特性相關(guān)工具類

UI自動(dòng)化用例編寫規(guī)范

1. 用例命名規(guī)范為：“包名_測(cè)試功能_序號(hào)”，如“MyApp_StartAbility_001”，序號(hào)表示測(cè)試StartAbility功能的第1個(gè)用例;
2. 用例的開頭和結(jié)尾都需要有日志打印；
3. 打印必須包括用例名稱的關(guān)鍵字，用例中每條斷言語(yǔ)句前必須添加日志，打印參數(shù)信息；
4. DOMAIN設(shè)置為0xF811；
5. 用例名稱中的包名和日志中的包名單獨(dú)用常量表示，方便包名變更整改；
6. 每條用例前需要添加注釋；

  import hilog from '@ohos.hilog';...const TAG = '[Sample_MyApp]'const DOMAIN = 0xF811const BUNDLE = 'MyApp_'.../*** 介紹用例測(cè)試的功能和場(chǎng)景等信息*/it(BUNDLE + 'StartAbility_001', function() {hilog.info(DOMAIN, TAG, BUNDLE + "StartAbility_001, begin")...// 介紹單一步驟的功能hilog.info(DOMAIN, TAG, BUNDLE + "StartAbility_001, code:" + code)expect(0).asserEqual(code)...hilog.info(DOMAIN, TAG, BUNDLE + "StartAbility_001, end")})

PR提交格式規(guī)范

示例如下：

IssueNo: #I56EH7:關(guān)聯(lián)問題
Description: 描述問題.
Sig: sig-systemapplications
Feature or Bugfix: Bugfix
Binary Source: NoSigned-off-by: jiangwensai <jiangwensai@huawei.com>

1. IssueNo管理issue信息；
2. Description描述修改變更內(nèi)容；
3. Sig統(tǒng)一使用SIG_Sample；
4. Feature or Bugfix，如果是需求選擇Feature，問題選擇Bugfix；
5. Signed-off-by，注明開發(fā)者賬號(hào)和郵箱；