Требования к интеграции образца (Sample)

1. Новые функции Sample не должны дублировать уже существующие функции;
2. Для разработки нового Sample рекомендуется использовать язык программирования ArkTS;
3. Для разработки нового Sample рекомендуется использовать модель Stage;
4. Новый Sample должен содержать сценарии автоматизации пользовательского интерфейса (UI) в ohosTest модуле, охватывающие основные функциональные сценарии;
5. Новый Sample должен соответствовать следующим стандартам:
   • код (см. раздел 1);
   • ReadMe (см. раздел 2);
   • структура проекта (см. раздел 3);
   • сценарии автоматизации UI (см. раздел 4);
   • формат PR (см. раздел 5);
   • руководство по включению двоичных файлов (см. раздел 6).
6. Дизайн UX нового Sample должен соответствовать требованиям стандарта для мультиустройственных приложений (см. https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/key-features/multi-device-app-dev/Readme-CN.md);
7. При разработке нового Sample рекомендуется использовать последнюю версию IDE и SDK;
8. При интеграции нового Sample необходимо предоставить отчёт о тестовых сценариях (см. пример в ohosTestTemplate.md), включая описание сценариев, шаги выполнения и результаты тестирования. Отчёт можно приложить к PR.

Стандарты кода

1. Все файлы, включая автоматически сгенерированные файлы package.json, должны быть отформатированы (используйте сочетание клавиш Ctrl+Alt+L в IDE);
2. Имена функций должны следовать правилам именования: C++ — верблюжий регистр, TS и JS — стиль именования со строчными буквами для первого символа и последующих слов с заглавными буквами, с учётом структуры «существительное-глагол»;
3. Статические константы должны быть написаны заглавными буквами, а имена каталогов — строчными (не рекомендуется использовать специальные символы, такие как «-» и «_»);
4. Классы должны использовать верблюжий регистр, параметры функций, глобальные и локальные переменные — строчный регистр. Именование должно быть понятным и логичным;
5. После if всегда должна стоять открывающая фигурная скобка {, даже если есть только одна строка кода;
6. Если есть условие break или return, сначала выполняется оно, затем продолжается выполнение остальной логики;
7. В условиях ветвления, когда условие выполнено, следует немедленно вернуться, не переходя к другим ветвям;
8. Избегать использования магических чисел в коде. Вместо этого используйте понятные имена констант или комментарии. Пример:

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

  const ONE_MINUTE = 60
  let time = ONE_MINUTE

9. Использовать шаблонные строки для объединения строк;
10. При использовании компонентов, кроме свойств width и height, которые могут быть указаны в одной строке, остальные свойства должны быть перенесены на новую строку;
11. В TS и JS относительно добавления точки с запятой (;) стиль должен быть унифицирован, рекомендуется добавлять точку с запятой;
12. При использовании ресурсов, таких как изображения, использовать $r для ссылки на них;
13. Обратить внимание на открытые лицензии и авторские права при добавлении новых файлов;
14. При создании скриншотов использовать реальные устройства для получения изображений;
15. В файлах ReadMe использовать точку (.), избегать использования запятых (,), проверять наличие опечаток;
16. В асинхронных методах возвращать значение метода напрямую, без объявления переменной. Пример:

  return await this.mediaTest.getFileAssets(fetchOp)

17. Указывать типы параметров методов;
18. Организовать импорт файлов по категориям;
19. В файле string.json описание должно быть кратким, на китайском языке;
20. В TS и JS отступ должен составлять 2 пробела, в C++ — 4 пробела;
21. При создании снимков экрана избегать включения людей, конфиденциальной информации, сетевых ресурсов и других материалов, нарушающих авторские права;
22. Не настраивать информацию о подписи в проекте, запрещено загружать local.properties и package-lock.json и другие файлы, автоматически генерируемые системой;
23. Унифицировать формат журналов, начинать с префикса [Sample_пакет], например, для журналов часов использовать [Sample_Clock]. Для печати журналов рекомендуется использовать Hilog API и создать отдельный класс 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)
  }
  ...
}

24. После комментариев // должен стоять пробел, если комментарий находится после кода, перед ним должен стоять пробел;

  // 正确示例
  let a = 10

  let a = 10 // 正确示例

25. Избегать использования китайских символов в коде, заменять их ресурсами, соответствующими международным стандартам разработки;
26. Использовать стандартное имя пакета приложения в формате «com.samples.xxx», где «xxx» — название функции. Увеличение файлов, удаление файлов, поиск файлов определённого типа и предварительный просмотр изображений: интерфейсы функций, упакованные в MediaLibraryManager.

• Используйте mediaLibrary.getMediaLibrary для получения объекта MediaLibrary;
• Считывайте данные каждого файла: используйте MediaLibrary.getFileAssets для считывания коллекции файлов FetchFileResult, удовлетворяющих условиям, затем вызовите FetchFileResult.getFirstObject();
• Создайте имитированный файл: используйте MediaLibrary.getPublicDirectory() для получения каталога, заданного системой, затем используйте MediaLibrary.createAsset();
• Удалите файл по указанному пути: используйте MediaLibrary.deleteAsset();
• Получите предварительный просмотр изображения: используйте image.createImageSource() для создания указанного ресурса ImageSource, затем вызовите ImageSource.createPixelMap(), см. интерфейс @ohos.multimedia.image.

В модуле Library через FileManager предоставляются внешние функциональные интерфейсы, такие как MediaLibraryManager.getPixelMapByFileAsset().

• Например, для предварительного просмотра изображений, считывайте файлы определённого типа: в FileList.ets вызовите FileManager.getFileAssets();
• Создайте имитацию файла: в FileList.ets вызовите FileManager.createTxtFileAsset();
• Удалите файлы по указанному пути: в FileList.ets вызовите FileManager.deleteFileAsset();
• Получите миниатюру: в ThumbnailImage.ets вызовите FileManager.getThumbnail();
• Для предварительного просмотра изображения, получите предварительный просмотр изображения: в ImagePreview.ets вызовите FileManager.getPixelMapByFileAsset().

Далее идёт текст, который не удалось перевести из-за отсутствия контекста. Структура проекта

// Общие инструменты или модули Library/src/main/ets/ // Характеристики интерфейса упакованы в модуле Library, могут быть независимо скомпилированы в har-пакет для повторного использования. |---filemanager // Упаковка классов, связанных с характеристиками | |---components // Классы пользовательского интерфейса, связанные с характеристиками, которые необходимо открыть (некоторые характеристики связаны с предоставлением повторно используемых компонентов пользовательского интерфейса) | | |---FileImage.ets | |---fileio // Упаковка интерфейсов, связанных с характеристиками. Если существует несколько модулей, поместите их в несколько каталогов, таких как fileio, medialibrary, userfilemanager, не открывайте их внешнему миру | | |---FileIoManager.ts | |---medialibrary | |---userfilemanager | |---FileManager.ts // Интерфейс характеристик, открытый внешнему миру, без конкретной реализации (реализация находится в модулях fileio, medialibrary и т. д.) |---mock // Имитация данных |---utils // Инструменты, связанные с характеристиками

Правила написания сценариев автоматизации пользовательского интерфейса

1. Правила именования сценариев: «Имя пакета_Тестируемая функция_Номер», например, MyApp_StartAbility_001, номер обозначает первый сценарий тестирования функции StartAbility;
2. В начале и в конце сценария должен быть журнал печати;
3. Печать должна включать ключевые слова имени сценария, перед каждой строкой утверждения в сценарии необходимо добавить журнал, распечатать информацию о параметрах;
4. DOMAIN установлен на 0xF811;
5. Имя сценария и журнал должны использовать отдельные константы для представления имени пакета, что удобно для изменения имени пакета;
6. Перед каждым сценарием необходимо добавить комментарий;

import hilog from '@ohos.hilog';
...
const TAG = '[Sample_MyApp]'
const DOMAIN = 0xF811
const BUNDLE = 'MyApp_'
...

/**
 * Введение в функциональность и сценарии использования тестовых случаев
 */
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

Пример:

IssueNo: #I56EH7: Связанная проблема
Description: Описание проблемы.
Sig: sig-systemapplications
Feature or Bugfix: Bugfix
Binary Source: Нет

Signed-off-by: jiangwensai <jiangwensai@huawei.com>

1. IssueNo управляет информацией о проблемах;
2. Description описывает содержание изменений;
3. Sig использует SIG_Sample единообразно;
4. Feature или Bugfix, если это требование, выберите Feature, если это проблема, выберите Bugfix;
5. Signed-off-by, укажите учётную запись разработчика и адрес электронной почты;

Стандарты интеграции двоичных файлов

Когда код, который будет отправлен, включает двоичные файлы (изображения, видео, сжатые пакеты, пакеты hap/har и т.д.), необходимо установить фильтр файлов в OTA.xml:

1. Найдите фильтр с именем «binaryFileTypePolicyFilter»:

<filefilter name="binaryFileTypePolicyFilter" desc="Filters for binary file policies">

2. Добавьте строку в фильтр:

<fileteritem type="filepath" name="Здесь введите путь к двоичному файлу" desc="Предоставлено путём к источнику двоичного файла (если источником является сам образец, просто введите текущий путь образца)">

Например: При загрузке двоичного файла ohos-notification-1.0.0.tgz в Sample code/Solutions/Shopping/OrangeShopping добавьте строку следующим образом:

<filteritem type="filepath" name="code/Solutions/Shopping/OrangeShopping/libs/ohos-notification-1.0.0.tgz" desc="Provided by Notification/CustomEmitter">