Loren_Wang

Loren_Wang

关注
发信
关注(28)粉丝(399)

鸿蒙App语法/结构/注意

注意

.1、权限申请使用流程

https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/accesstoken-overview-0000001544703857-V3#ZH-CN_TOPIC_0000001574088913__%E6%9D%83%E9%99%90%E7%94%B3%E8%AF%B7%E4%BD%BF%E7%94%A8%E7%9A%84%E5%B7%A5%E4%BD%9C%E6%B5%81%E7%A8%8B

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

https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/application-configuration-file-overview-stage-0000001428061460-V3
在基于Stage模型开发的应用项目代码下，都存在一个app.json5及一个或多个module.json5这两种配置文件。

app.json5主要包含以下内容：

  • 应用的全局配置信息，包含应用的包名、开发厂商、版本号等基本信息。
  • 特定设备类型的配置信息

module.json5主要包含以下内容：

  • Module的基本配置信息，例如Module名称、类型、描述、支持的设备类型等基本信息。
  • 应用组件信息，包含UIAbility组件和ExtensionAbility组件的描述信息。
  • 应用运行过程中所需的权限信息。

.1、app.json5配置文件

https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/app-configuration-file-0000001427584584-V3

.1.1、bundleName—标识应用的Bundle名称，用于标识应用的唯一性(该标签不可缺省)

标签的值命名规则 ：

  • 字符串以字母、数字、下划线和符号“.”组成。
  • 以字母开头。
  • 最小长度7个字节，最大长度127个字节。

推荐采用反域名形式命名（如com.example.demo，建议第一级为域名后缀com，第二级为厂商/个人名，第三级为应用名，也可以多级）。

.1.2、bundleType—标识应用的Bundle类型，用于区分应用或者原子化服务(该标签可以缺省，缺省为app)

该标签可选值为app和atomicService ：

  • app：当前Bundle为普通应用。
  • atomicService：当前Bundle为元服务。

.1.3、debug—标识应用是否可调试，该标签由IDE编译构建时生成(该标签可以缺省，缺省为false)

  • true：可调试。
  • false：不可调试。

.1.4、icon—标识应用的图标，标签值为图标资源文件的索引(该标签不可缺省)

.1.5、label—标识应用的名称，标签值为字符串资源的索引(该标签不可缺省)

.1.6、description—标识应用的描述信息，标签值是字符串类型（最大255个字节）或对描述内容的字符串资源索引（该标签可以缺省，缺省为空）

.1.7、vendor—标识对应用开发厂商的描述。该标签的值是字符串类型（最大255个字节）（该标签可以缺省，缺省为空）

.1.8、versionCode—标识应用的版本号，该标签值为32位非负整数(该标签不可缺省)

此数字仅用于确定某个版本是否比另一个版本更新，数值越大表示版本越高。开发者可以将该值设置为任何正整数，但是必须确保应用的新版本都使用比旧版本更大的值。该标签不可缺省，versionCode值应小于2^31次方。

.1.9、versionName—标识应用版本号的文字描述，用于向用户展示(该标签不可缺省)

该标签仅由数字和点构成，推荐采用“A.B.C.D”四段式的形式。四段式推荐的含义如下所示。
第一段：主版本号/Major，范围0-99，重大修改的版本，如实现新的大功能或重大变化。
第二段：次版本号/Minor，范围0-99，表示实现较突出的特点，如新功能添加或大问题修复。
第三段：特性版本号/Feature，范围0-99，标识规划的新版本特性。
第四段：修订版本号/Patch，范围0-999，表示维护版本，修复bug。
标签最大字节长度为127。

.1.10、minCompatibleVersionCode—标识应用能够兼容的最低历史版本号，用于跨设备兼容性判断(该标签可缺省，缺省值等于versionCode标签值)

.1.11、minAPIVersion—标识应用运行需要的SDK的API最小版本(由build-profile.json5中的compatibleSdkVersion生成)

.1.12、targetAPIVersion—标识应用运行需要的API目标版本(由build-profile.json5中的compatibleSdkVersion生成)

.1.13、apiReleaseType—标识应用运行需要的API目标版本的类型，采用字符串类型表示(该标签可缺省，由IDE生成并覆盖)

取值为“CanaryN”、“BetaN”或者“Release”，其中，N代表大于零的整数。

  • Canary：受限发布的版本。
  • Beta：公开发布的Beta版本。
  • Release：公开发布的正式版本。

该字段由DevEco Studio读取当前使用的SDK的Stage来生成。

.1.14、multiProjects—标识当前工程是否支持多个工程的联合开发(可缺省，缺省值为false)

  • true：当前工程支持多个工程的联合开发。
  • false：当前工程不支持多个工程的联合开发。

多工程开发可以参考文档：多工程构建。

.1.15、tablet—标识对tablet设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion、distributedNotificationEnabled(该标签可缺省，缺省时tablet设备使用app.json5公共区域配置的属性值)

如果使用该属性对tablet设备做了特殊配置，则应用在tablet设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值

.1.16、tv—标识对tv设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion、distributedNotificationEnabled(该标签可缺省，缺省时tv设备使用app.json5公共区域配置的属性值)

如果使用该属性对tv设备做了特殊配置，则应用在tv设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。

.1.17、wearable—标识对wearable设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion、distributedNotificationEnabled(该标签可缺省，缺省时wearable设备使用app.json5公共区域配置的属性值)

如果使用该属性对wearable设备做了特殊配置，则应用在wearable设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。

.1.18、car—标识对car设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion、distributedNotificationEnabled(该标签可缺省，缺省时car设备使用app.json5公共区域配置的属性值)

如果使用该属性对car设备做了特殊配置，则应用在car设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。

.1.19、phone—标识对phone设备做的特殊配置，可以配置的属性字段有上文提到的：minAPIVersion、distributedNotificationEnabled(该标签可缺省，缺省时phone设备使用app.json5公共区域配置的属性值)

如果使用该属性对phone设备做了特殊配置，则应用在phone设备中会采用此处配置的属性值，并忽略在app.json5公共区域配置的属性值。

{
  "app": {
    "bundleName": "com.application.myapplication",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name",
    "description": "$string:description_application",
    "minAPIVersion": 9,
    "targetAPIVersion": 9,
    "apiReleaseType": "Release",
    "debug": false,
    "car": {
      "minAPIVersion": 8,
    }
  },
}

.2、module.json5配置文件

.2.1、name—标识当前Module的名称(该标签不可缺省)

标签值采用字符串表示（最大长度31个字节），该名称在整个应用要唯一，仅支持英文字符。

.2.2、type—标识当前Module的类型(该标签不可缺省)

类型有两种，分别：

  • entry：应用的主模块。
  • feature：应用的动态特性模块。

.2.3、srcEntry—标识当前Module所对应的代码路径(该标签可缺省，缺省值为空)

标签值为字符串（最长为127字节）

.2.4、description—标识当前Module的描述信息(该标签可缺省，缺省值为空)

标签值是字符串类型（最长255字节）或对描述内容的字符串资源索引。

.2.5、process—标识当前Module的进程名(可缺省，缺省为app.json5文件下app标签下的bundleName)

标签值为字符串类型（最长为31个字节）。如果在HAP标签下配置了process，该应用的所有UIAbility、DataShareExtensionAbility、ServiceExtensionAbility都运行在该进程中。

说明：

  • 仅支持系统应用配置，三方应用配置不生效。

.2.6、mainElement—标识当前Module的入口UIAbility名称或者ExtensionAbility名称(该标签可缺省，缺省值为空)

标签最大字节长度为255。

.2.7、deviceTypes—标识当前Module可以运行在哪类设备上(该标签不可缺省)

标签值采用字符串数组的表示。

.2.7.1、tablet—平板
.2.7.2、tv—智慧屏
.2.7.3、wearable—智能手表(系统能力较丰富的手表，具备电话功能)
.2.7.4、car—车机
.2.7.5、phone—手机

.2.8、deliveryWithInstall—标识当前Module是否在用户主动安装的时候安装(该标签不可缺省)

表示该Module对应的HAP是否跟随应用一起安装。

  • true：主动安装时安装。
  • false：主动安装时不安装。

.2.9、installationFree—标识当前Module是否支持免安装特性(该标签不可缺省)

  • true：表示支持免安装特性，且符合免安装约束。
  • false：表示不支持免安装特性。

说明：

  • 当应用的entry类型Module的该字段配置为true时，该应用的feature类型的该字段也需要配置为true。
  • 当应用的entry类型Module的该字段配置为false时，该应用的feature类型的该字段根据业务需求配置true或false。

.2.10、virtualMachine—标识当前Module运行的目标虚拟机类型，供云端分发使用，如应用市场和分发中心(该标签由IDE构建HAP的时候自动插入)

该标签值为字符串。如果目标虚拟机类型为ArkTS引擎，则其值为“ark+版本号”

.2.11、pages—标识当前Module的profile资源，用于列举每个页面信息(在有UIAbility的场景下，该标签不可缺省)

该标签最大长度为255个字节。该标签是一个profile文件资源，用于指定描述页面信息的配置文件。
在开发视图的resources/base/profile下面定义配置文件main_pages.json，其中文件名(main_pages)可自定义，需要和前文中pages标签指定的信息对应，配置文件中列举了当前应用组件中的页面信息。

.2.11.1、src—描述有关JavaScript模块中所有页面的路由信息，包括页面路径和页面名称。该值是一个字符串数组，其中每个元素表示一个页面(该标签不可缺省)
.2.11.2、window—用于定义与显示窗口相关的配置(该标签可缺省，缺省值为空)
.2.11.2.1、designWidth—标识页面设计基准宽度。以此为基准，根据实际设备宽度来缩放元素大小(可缺省，缺省值为720px)
.2.11.2.2、autoDesignWidth—标识页面设计基准宽度是否自动计算。当配置为true时，designWidth将会被忽略，设计基准宽度由设备宽度与屏幕密度计算得出(可缺省，缺省值为false)

.2.12、metadata—标识当前Module的自定义元信息，标签值为数组类型，只对当前Module、UIAbility、ExtensionAbility生效(该标签可缺省，缺省值为空)

.2.12.1、name—该标签标识数据项的键名称(该标签可缺省，缺省值为空)

字符串类型（最大长度255字节）

.2.12.2、value—该标签标识数据项的值(该标签可缺省，缺省值为空)

标签值为字符串（最大长度255字节）。

.2.13.2、resource—该标签标识定义用户自定义数据格式(该标签可缺省，缺省值为空)

标签值为标识该数据的资源的索引值。该标签最大字节长度为255字节。

.2.14、abilities—标识当前Module中UIAbility的配置信息，标签值为数组类型，只对当前UIAbility生效(该标签可缺省，缺省值为空)

abilities标签描述UIAbility组件的配置信息，标签值为数组类型，该标签下的配置只对当前UIAbility生效。

.2.14.1、name—标识当前UIAbility组件的名称(该标签不可缺省)

该名称在整个应用要唯一，标签值采用字符串表示（最大长度127个字节），仅支持英文字符。

.2.14.2、srcEntry—该标签标识入口UIAbility的代码路径(该标签不可缺省)

标签值为字符串（最长为127字节）

.2.14.3、launchType—标识当前UIAbility组件的启动模式(可缺省，该标签缺省为“singleton”)

可选标签值：

  • multiton：多实例模式，每次启动创建一个新的实例。
  • singleton：单实例模式，仅第一次启动创建新实例。
  • specified：指定实例模式，运行时由开发者决定是否创建新实例。
.2.14.4、description—标识当前UIAbility组件的描述信息(该标签可缺省，缺省值为空)

标签值是字符串类型（最长255字节）或对描述内容的资源索引，要求采用资源索引方式，以支持多语言。

.2.14.5、icon—标识当前UIAbility组件的图标(该标签可缺省，缺省值为空。如果UIAbility被配置为MainElement，该标签必须配置)

标签值为图标资源文件的索引。

.2.14.6、label—标识当前UIAbility组件对用户显示的名称(该标签不可缺省)

标签值配置为该名称的资源索引以支持多语言。
如果UIAbility被配置当前Module的mainElement时，该标签必须配置，且应用内唯一。

.2.14.7、permissions—标识当前UIAbility组件自定义的权限信息(该标签可缺省，缺省值为空)

当其他应用访问该UIAbility时，需要申请相应的权限信息。
一个数组元素为一个权限名称。通常采用反向域名格式（最大255字节），取值为系统预定义的权限。

.2.14.8、metadata—标识当前UIAbility组件的元信息(该标签可缺省，缺省值为空)
.2.14.9、exported—标识当前UIAbility组件是否可以被其他应用调用(该标签可缺省，缺省值为false)
  • true：表示可以被其他应用调用。
  • false：表示不可以被其他应用调用。
.2.14.10、continuable—标识当前UIAbility组件是否可以迁移(该标签可缺省，缺省值为空)
  • true：表示可以被迁移。
  • false：表示不可以被迁移。
.2.14.11、skills—标识当前UIAbility组件或ExtensionAbility组件能够接收的Want的特征集，为数组格式(该标签可缺省，缺省值为空)

配置规则：

  • 对于Entry类型的HAP，应用可以配置多个具有入口能力的skills标签（即配置了ohos.want.action.home和entity.system.home）。
  • 对于Feature类型的HAP，只有应用可以配置具有入口能力的skills标签，服务不允许配置。
.2.14.11.1、actions—标识能够接收的Want的Action值的集合，取值通常为系统预定义的action值，也允许自定义(可缺省，缺省值为空)
.2.14.11.2、entities—标识能够接收Want的Entity值的集合(可缺省，缺省值为空)
.2.14.11.3、uris—标识与Want中URI（Uniform Resource Identifier）相匹配的集合可缺省，缺省值为空)
.2.14.11.4、scheme—标识URI的协议名部分，常见的有http、https、file、ftp等(uris中仅配置type时可以缺省，缺省值为空，否则不可缺省)
.2.14.11.5、host—标识URI的主机地址部分，该字段要在schema存在时才有意义(可缺省，缺省值为空)

常见的方式：

  • 域名方式，如example.com。
  • IP地址方式，如10.10.10.1。
.2.14.11.6、port—标识URI的端口部分(可缺省，缺省值为空)

如http默认端口为80，https默认端口是443，ftp默认端口是21。该字段要在schema和host都存在时才有意义。

.2.14.11.7、path | pathStartWith | pathRegex—标识URI的路径部分，path、pathStartWith和pathRegex配置时三选一(可缺省，缺省值为空)

path标识URI与want中的路径部分全匹配，pathStartWith标识URI与want中的路径部分允许前缀匹配，pathRegex标识URI与want中的路径部分允许正则匹配。该字段要在schema和host都存在时才有意义。

.2.14.11.8、type—标识与Want相匹配的数据类型(可缺省，缺省值为空)

使用MIME（Multipurpose Internet Mail Extensions）类型规范。可与schema同时配置，也可以单独配置。

.2.14.12、backgroundModes—标识当前UIAbility组件的长时任务集合(该标签可缺省，缺省值为空)

指定用于满足特定类型的长时任务。

长时任务类型有如下：

  • dataTransfer：通过网络/对端设备进行数据下载、备份、分享、传输等业务。
  • audioPlayback：音频输出业务。
  • audioRecording：音频输入业务。
  • location：定位、导航业务。
  • bluetoothInteraction：蓝牙扫描、连接、传输业务（穿戴）。
  • multiDeviceConnection：多设备互联业务。
  • wifiInteraction：Wi-Fi扫描、连接、传输业务（克隆多屏）。
  • voip：音视频电话，VoIP业务。
  • taskKeeping：计算业务。
.2.14.13、startWindowIcon—标识当前UIAbility组件启动页面图标资源文件的索引(不可缺省)

取值示例：$media:icon。该标签最大字节长度为255

.2.14.14、startWindowBackground—标识当前UIAbility组件启动页面背景颜色资源文件的索引(不可缺省)

取值示例：$color:red。该标签最大字节长度为255

.2.14.15、removeMissionAfterTerminate—标识当前UIAbility组件销毁后是否从任务列表中移除任务(该标签可缺省，缺省值为false)

为布尔类型：

  • true表示销毁后移除任务。
  • false表示销毁后不移除任务
.2.14.15、orientation—标识当前UIAbility组件启动时的方向(该标签可缺省，缺省值为unspecified)

该方向的取值范围包括：

  • unspecified：未指定方向，由系统自动判断显示方向。
  • landscape：横屏。
  • portrait：竖屏。
  • landscape_inverted：反向横屏。
  • portrait_inverted：反向竖屏。
  • auto_rotation：随传感器旋转。
  • auto_rotation_landscape：传感器横屏旋转，包括了横屏和反向横屏。
  • auto_rotation_portrait：传感器竖屏旋转，包括了竖屏和反向竖屏。
  • auto_rotation_restricted：传感器开关打开，方向可随传感器旋转。
  • auto_rotation_landscape_restricted：传感器开关打开，方向可随传感器旋转为横屏， 包括了横屏和反向横屏。
  • auto_rotation_portrait_restricted：传感器开关打开，方向随可传感器旋转为竖屏， 包括了竖屏和反向竖屏。
  • locked：传感器开关关闭，方向锁定。
.2.14.16、supportWindowMode—标识当前UIAbility组件所支持的窗口模式(该标签可缺省，缺省值为[“fullscreen”, “split”, “floating”])

包含：

  • fullscreen：全屏模式。
  • split：分屏模式。
  • floating：悬浮窗模式。
.2.14.17、priority—标识当前UIAbility组件的优先级，仅支持系统应用配置，三方应用配置不生效(该标签可缺省，缺省值为0)

隐式查询时，优先级越高，UIAbility在返回列表越靠前。该标签取值为integer类型，取值范围0-10。数值越大，优先级越高

.2.14.18、maxWindowRatio—标识当前UIAbility组件支持的最大的宽高比(该标签可缺省，缺省值为平台支持的最大的宽高比)

该标签最小取值为0。

.2.14.19、minWindowRatio—标识当前UIAbility组件支持的最小的宽高比(该标签可缺省，缺省值为平台支持的最小的宽高比)

该标签最小取值为0

.2.14.20、maxWindowWidth—标识当前UIAbility组件支持的最大的窗口宽度，宽度单位为vp(该标签可缺省，缺省值为平台支持的最大的窗口宽度)

该标签最小取值为0。

.2.14.21、minWindowWidth—标识当前UIAbility组件支持的最小的窗口宽度, 宽度单位为vp(该标签可缺省，缺省值为平台支持的最小的窗口宽度)

该标签最小取值为0

.2.14.22、maxWindowHeight—标识当前UIAbility组件支持的最大的窗口高度, 高度单位为vp(该标签可缺省，缺省值为平台支持的最大的窗口高度)

该标签最小取值为0

.2.14.23、minWindowHeight—标识当前UIAbility组件支持的最小的窗口高度, 高度单位为vp(该标签可缺省，缺省值为平台支持的最小的窗口高度)

该标签最小取值为0

.2.14.24、excludeFromMissions—标识当前UIAbility组件是否在最近任务列表中显示(该标签可缺省，缺省值为false)
  • true：表示不在任务列表中显示。
  • false：表示在任务列表中显示。

说明：

  • 仅支持系统应用配置，三方应用配置不生效。

.2.15、extensionAbilities—标识当前Module中ExtensionAbility的配置信息，标签值为数组类型，只对当前ExtensionAbility生效(该标签可缺省，缺省值为空)

.2.15.1、name—标识当前ExtensionAbility组件的名称(该标签不可缺省)

标签值最大长度为127个字节，该名称在整个应用要唯一。

.2.15.2、srcEntry—标识当前ExtensionAbility组件所对应的代码路径(该标签不可缺省)

标签值最大长度为127字节

.2.15.3、description—标识当前ExtensionAbility组件的描述(该标签可缺省，缺省值为空)

标签值最大长度为255字节，标签也可以是描述内容的资源索引，用于支持多语言。

.2.15.4、icon—标识当前ExtensionAbility组件的图标(该标签可缺省，缺省值为空)

标签值为资源文件的索引。如果ExtensionAbility组件被配置为MainElement，该标签必须配置。

.2.15.5、label—标识当前ExtensionAbility组件对用户显示的名称(该标签不可缺省)

标签值配置为该名称的资源索引以支持多语言。
说明：

  • 如果ExtensionAbility被配置当前Module的mainElement时，该标签必须配置，且应用内唯一。
.2.15.6、type—标识当前ExtensionAbility组件的类型(该标签不可缺省)

取值为：

  • form：卡片的ExtensionAbility。
  • workScheduler：延时任务的ExtensionAbility。
  • inputMethod：输入法的ExtensionAbility。
  • service：后台运行的service组件。
  • accessibility：辅助能力的ExtensionAbility。
  • dataShare：数据共享的ExtensionAbility。
  • fileShare：文件共享的ExtensionAbility。
  • staticSubscriber：静态广播的ExtensionAbility。
  • wallpaper：壁纸的ExtensionAbility。
  • backup：数据备份的ExtensionAbility。
  • window：该ExtensionAbility会在启动过程中创建一个window，为开发者提供界面开发。开发者开发出来的界面将通过abilityComponent控件组合到其他应用的窗口中。
  • thumbnail：获取文件缩略图的ExtensionAbility，开发者可以对自定义文件类型的文件提供缩略。
  • preview：该ExtensionAbility会将文件解析后在一个窗口中显示，开发者可以通过将此窗口组合到其他应用窗口中。

说明：

  • 其中service和dataShare类型，仅支持系统应用配置，三方应用配置不生效。
.2.15.7、permissions—标识当前ExtensionAbility组件自定义的权限信息(该标签可缺省，缺省值为空)

当其他应用访问该ExtensionAbility时，需要申请相应的权限信息。

一个数组元素为一个权限名称。通常采用反向域名格式（最大255字节），可以是系统预定义的权限，也可以是该应用自定义的权限。如果是后者，需与defPermissions标签中定义的某个权限的name标签值一致。

.2.15.8、uri—标识当前ExtensionAbility组件提供的数据URI(该标签可缺省，缺省值为空)

为字符数组类型（最大长度255），用反向域名的格式表示。

说明：

  • 该标签在type为dataShare类型的ExtensionAbility时，不可缺省。
.2.15.9、skills—标识当前ExtensionAbility组件能够接收的Want的特征集，为数组格式(该标签可缺省，缺省值为空)

配置规则：entry包可以配置多个具有入口能力的skills标签（配置了ohos.want.action.home和entity.system.home）的ExtensionAbility，其中第一个配置了skills标签的ExtensionAbility中的label和icon作为应用或服务的label和icon。

说明：

  • 应用的Feature包可以配置具有入口能力的skills标签。
  • 服务的Feature包不能配置具有入口能力的skills标签。
.2.15.10、metadata—标识当前ExtensionAbility组件的元信息(该标签可缺省，缺省值为空)
.2.15.11、exported—标识当前ExtensionAbility组件是否可以被其他应用调用(该标签可缺省，缺省值为false)

为布尔类型。

  • true：表示可以被其他应用调用。
  • false：表示不可以被其他应用调用。

.2.16、requestPermissions—标识当前应用运行时需向系统申请的权限集合(该标签可缺省，缺省值为空)

.2.16.1、name—必须，填写需要使用的权限名称
.2.16.2、reason—可选，当申请的权限为user_grant权限时此字段必填，用于描述申请权限的原因

说明：

  • 当申请的权限为user_grant权限时，如果未填写该字段则不允许在应用市场上架，并且需要进行多语种适配。
.2.16.3、usedScene—可选，当申请的权限为user_grant权限时此字段必填(abilities：空。when：空。)

描述权限使用的场景由abilities和when组成。其中abilities可以配置为多个UIAbility组件，when表示调用时机。

说明：

  • 默认为可选，当申请的权限为user_grant权限时，abilities标签必填，when标签可选。

.2.17、testRunner—标识当前Module用于支持对测试框架的配置(该标签可缺省，缺省值为空)

.2.17.1、name—标识测试框架对象名称(不可缺省)

该标签最大字节长度为255个字节。

.2.17.2、srcPath—标识测试框架代码路径(不可缺省)

该标签最大字节长度为255个字节。

.2.18、shortcuts—标识应用的快捷方式信息

标签值为数组，最多可以配置四个快捷方式。其包含四个子标签shortcutId、label、icon、wants。

.2.18.1、shortcutId—标识快捷方式的ID。字符串的最大长度为63字节(该标签不可缺省)
.2.18.2、label—标识快捷方式的标签信息，即快捷方式对外显示的文字描述信息(该标签可缺省，缺省值为空)

取值可以是描述性内容，也可以是标识label的资源索引。字符串最大长度为255字节。

.2.18.3、icon—标识快捷方式的图标，标签值为资源文件的索引(该标签可缺省，缺省值为空)
.2.18.4、wants—标识快捷方式内定义的目标wants信息集合(该标签可缺省，缺省为空)

每个wants可配置bundleName和abilityName两个子标签。

  • bundleName：表示快捷方式的目标Bundle名称，字符串类型。
  • abilityName：表示快捷方式的目标组件名，字符串类型。

.2.19、distroFilter—该标签下的子标签均为可选字段，在应用市场云端分发时使用

distroFilter标签用于定义HAP对应的细分设备规格的分发策略，以便在应用市场进行云端分发应用包时做精准匹配。该标签可配置的分发策略维度包括API Version、屏幕形状、屏幕尺寸、屏幕分辨率，设备的国家与地区码。在进行分发时，通过deviceType与这五个属性的匹配关系，唯一确定一个用于分发到设备的HAP。

该标签需要配置在/resource/profile资源目录下，并在模块的metadata的resource字段中引用。

.2.19.1、apiVersion—标识支持的apiVersion范围(该标签可缺省，缺省值为空)
.2.19.2、screenShape—标识屏幕形状的支持策略(该标签可缺省，缺省值为空)
.2.19.2.1、policy—标识该子属性取值规则(该标签不可缺省)

配置为“exclude”或“include”。

  • exclude：表示需要排除的value属性。
  • include：表示需要包含的value属性。
.2.19.2.2、value—支持的取值为circle（圆形）、rect（矩形）(该标签不可缺省)

场景示例：针对智能穿戴设备，可为圆形表盘和矩形表盘分别提供不同的HAP。

.2.19.3、screenWindow—标识应用运行时窗口的分辨率支持策略(该标签可缺省，缺省值为空)

该字段仅支持对轻量级智能穿戴设备进行配置。

.2.19.3.1、policy—标识该子属性取值规则(该标签不可缺省)

配置为“exclude”或“include”。

  • exclude：表示该字段取值不包含value枚举值匹配规则的匹配该属性。
  • include：表示该字段取值满足value枚举值匹配规则的匹配该属性。
.2.19.3.2、value—单个字符串的取值格式为“宽 * 高”(该标签不可缺省)

取值为整数像素值，例如“454 * 454”。

.2.19.4、screenDensity—标识屏幕的像素密度（dpi：Dot Per Inch）(该标签可缺省，缺省值为空)
.2.19.4.1、policy—标识该子属性取值规则(该标签不可缺省)

配置为“exclude”或“include”。

  • exclude：表示需要排除的value属性。
  • include：表示需要包含的value属性。
.2.19.4.2、value—该标签标识屏幕的像素密度（dpi :Dot Per Inch）(该标签不可缺省)

该标签为字符串数组，字符串范围如下。

  • sdpi：表示小规模的屏幕密度（Small-scale Dots per Inch），适用于dpi取值为(0,120]的设备。
  • mdpi：表示中规模的屏幕密度（Medium-scale Dots Per Inch），适用于dpi取值为(120,160]的设备。
  • ldpi：表示大规模的屏幕密度（Large-scale Dots Per Inch），适用于dpi取值为(160,240]的设备。
  • xldpi：表示大规模的屏幕密度（Extra Large-scale Dots Per Inch），适用于dpi取值为(240,320]的设备。
  • xxldpi：表示大规模的屏幕密度（Extra Extra Large-scale Dots Per Inch），适用于dpi取值为(320，480]的设备。
  • xxxldpi：表示大规模的屏幕密度（Extra Extra Extra Large-scale Dots Per Inch），适用于dpi取值为(480, 640]的设备。
.2.19.5、countryCode—表示应用需要分发的国家地区码(该标签可缺省，缺省值为空)

具体值以ISO-3166-1标准为准。支持多个国家和地区枚举定义。

.2.19.5.1、policy—标识该子属性取值规则(该标签不可缺省)

配置为“exclude”或“include”。

  • exclude：表示需要排除的value属性。
  • include：表示需要包含的value属性。
.2.19.5.2、value—标识应用需要分发的国家地区码(该标签不可缺省)

取值为整数像素值，例如“454 * 454”。

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "tv",
      "tablet"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "virtualMachine": "ark",
    "metadata": [
      {
        "name": "string",
        "value": "string",
        "resource": "$profile:distributionFilter_config"
      }
    ],
    "abilities": [
      {
         "name": "EntryAbility",
    "srcEntry": "./ets/entryability/EntryAbility.ts",
    "launchType":"singleton",
    "description": "$string:description_main_ability",
    "icon": "$media:icon",
    "label": "Login",
    "permissions": [],
    "metadata": [],
    "exported": true,
    "continuable": true,
    "skills": [{
          "actions": [
            "ohos.want.action.home"
          ],
          "entities": [
            "entity.system.home"
          ],
          "uris": [
            {
              "scheme":"http",
              "host":"example.com",
              "port":"80",
              "path":"path",
              "type": "text/*"
            }
          ]
        }],
    "backgroundModes": [
      "dataTransfer",
      "audioPlayback",
      "audioRecording",
      "location",
      "bluetoothInteraction",
      "multiDeviceConnection",
      "wifiInteraction",
      "voip",
      "taskKeeping"
    ],
    "startWindowIcon": "$media:icon",
    "startWindowBackground": "$color:red",
    "removeMissionAfterTerminate": true,
    "orientation": " ",
    "supportWindowMode": ["fullscreen", "split", "floating"],
    "maxWindowRatio": 3.5,
    "minWindowRatio": 0.5,
    "maxWindowWidth": 2560,
    "minWindowWidth": 1400,
    "maxWindowHeight": 300,
    "minWindowHeight": 200,
    "excludeFromMissions": false
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.abilitydemo.permission.PROVIDER",
        "reason": "$string:reason",
        "usedScene": {
          "abilities": [
            "FormAbility"
          ],
          "when": "inuse"
        }
      }
    ],
    "extensionAbilities": [
    {
      "name": "FormName",
      "srcEntry": "./form/MyForm.ts",
      "icon": "$media:icon",
      "label" : "$string:extension_name",
      "description": "$string:form_description",
      "type": "form", 
      "permissions": ["ohos.abilitydemo.permission.PROVIDER"],
      "readPermission": "",
      "writePermission": "",
      "exported": true,
      "uri":"scheme://authority/path/query",
      "skills": [{
        "actions": [],
        "entities": [],
        "uris": []
      }],
      "metadata": [
        {
          "name": "ohos.extension.form",
          "resource": "$profile:form_config", 
        }
      ]
    }
  ],
  "shortcuts": [
    {
      "shortcutId": "id_test1",
      "label": "$string:shortcut",
      "icon": "$media:aa_icon",
      "wants": [
        {
          "bundleName": "com.ohos.hello",
          "abilityName": "EntryAbility"
        }
      ]
    }
  ],
  "distroFilter": {
    "screenShape": {
      "policy": "include",
      "value": [
        "circle",
        "rect"
      ]
    },
    "screenWindow": {
      "policy": "include",
      "value": [
        "454*454",
        "466*466"
      ]
    },
    "screenDensity": {
      "policy": "exclude",
      "value": [
        "ldpi",
        "xldpi"
      ]
    },
    "countryCode": { // 支持中国和香港地区分发
      "policy": "include",
      "value": [
        "CN",
        "HK"
      ]
    }
  },
  "testRunner": {
      "name": "myTestRunnerName",
      "srcPath": "etc/test/TestRunner.ts"
    }
  }
}

语法

ArkTS是HarmonyOS优选的主力应用开发语言。ArkTS围绕应用开发在TypeScript（简称TS）生态基础上做了进一步扩展，继承了TS的所有特性，是TS的超集。因此，在学习ArkTS语言之前，建议开发者具备TS语言开发能力。

当前，ArkTS在TS的基础上主要扩展了如下能力：

  • 基本语法：ArkTS定义了声明式UI描述、自定义组件和动态扩展UI元素的能力，再配合ArkUI开发框架中的系统组件及其相关的事件方法、属性方法等共同构成了UI开发的主体。
  • 状态管理：ArkTS提供了多维度的状态管理机制。在UI开发框架中，与UI相关联的数据可以在组件内使用，也可以在不同组件层级间传递，比如父子组件之间、爷孙组件之间，还可以在应用全局范围内传递或跨设备传递。另外，从数据的传递形式来看，可分为只读的单向传递和可变更的双向传递。开发者可以灵活地利用这些能力来实现数据和UI的联动。
  • 渲染控制：ArkTS提供了渲染控制的能力。条件渲染可根据应用的不同状态，渲染对应状态下的UI内容。循环渲染可从数据源中迭代获取数据，并在每次迭代过程中创建相应的组件。数据懒加载从数据源中按需迭代数据，并在每次迭代过程中创建相应的组件。

.1、基本语法概述

https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/arkts-basic-syntax-overview-0000001531611153-V3

  • 装饰器： 用于装饰类、结构、方法以及变量，并赋予其特殊的含义。如上述示例中@Entry、@Component和@State都是装饰器，@Component表示自定义组件，@Entry表示该自定义组件为入口组件，@State表示组件中的状态变量，状态变量变化会触发UI刷新。
  • UI描述：以声明式的方式来描述UI的结构，例如build()方法中的代码块。
  • 自定义组件：可复用的UI单元，可组合其他组件，如上述被@Component装饰的struct Hello。
  • 系统组件：ArkUI框架中默认内置的基础和容器组件，可直接被开发者调用，比如示例中的Column、Text、Divider、Button。
  • 属性方法：组件可以通过链式调用配置多项属性，如fontSize()、width()、height()、backgroundColor()等。
  • 事件方法：组件可以通过链式调用设置多个事件的响应逻辑，如跟随在Button后面的onClick()。
  • 系统组件、属性方法、事件方法具体使用可参考基于ArkTS的声明式开发范式。

除此之外，ArkTS扩展了多种语法范式来使开发更加便捷：

  • @Builder/@BuilderParam：特殊的封装UI描述的方法，细粒度的封装和复用UI描述。
  • @Extend/@Styles：扩展内置组件和封装属性样式，更灵活地组合内置组件。
    stateStyles：多态样式，可以依据组件的内部状态的不同，设置不同样式。
    鸿蒙App语法/结构/注意-LMLPHP

.2、声明式UI描述

https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/arkts-declarative-ui-description-0000001524416537-V3
ArkTS以声明方式组合和扩展组件来描述应用程序的UI，同时还提供了基本的属性、事件和子组件配置方法，帮助开发者实现应用交互逻辑。

.2.1、创建组件

//无参数
Column() {
  Text('item 1')
  Divider()
  Text('item 2')
}
// string类型的参数
Text('test')
// $r形式引入应用资源，可应用于多语言场景
Text($r('app.string.title_value'))
// 无参数形式
Text()
Image(this.imagePath)
Image('https://' + this.imageUrl)
Text(`count: ${this.count}`)

.2.2、配置属性

属性方法以“.”链式调用的方式配置系统组件的样式和其他属性，建议每个属性方法单独写一行。

Text('hello')
  .fontSize(this.size)
Image('test.jpg')
  .width(this.count % 2 === 0 ? 100 : 200)    
  .height(this.offset + 100)

.2.3、配置事件

//使用箭头函数配置组件的事件方法。
Button('Click me')
  .onClick(() => {
    this.myText = 'ArkUI';
  })
//使用匿名函数表达式配置组件的事件方法，要求使用bind，以确保函数体中的this指向当前组件。
Button('add counter')
  .onClick(function(){
    this.counter += 2;
  }.bind(this))
//使用组件的成员函数配置组件的事件方法。
myClickHandler(): void {
  this.counter += 2;
}
...
Button('add counter')
  .onClick(this.myClickHandler.bind(this))
//使用声明的箭头函数，可以直接调用，不需要bind this
fn = () => {
  console.info(`counter: ${this.counter}`)
  this.counter++
}
...
Button('add counter')
  .onClick(this.fn)

.2.4、配置子组件

如果组件支持子组件配置，则需在尾随闭包"{…}"中为组件添加子组件的UI描述。Column、Row、Stack、Grid、List等组件都是容器组件。

//以下是简单的Column组件配置子组件的示例。
Column() {
  Text('Hello')
    .fontSize(100)
  Divider()
  Text(this.myText)
    .fontSize(100)
    .fontColor(Color.Red)
}
//容器组件均支持子组件配置，可以实现相对复杂的多级嵌套。
Column() {
  Row() {
    Image('test1.jpg')
      .width(100)
      .height(100)
    Button('click +1')
      .onClick(() => {
        console.info('+1 clicked!');
      })
  }
}

.3、自定义组件

.3.1、创建自定义组件

https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/arkts-create-custom-components-0000001473537046-V3
在ArkUI中，UI显示的内容均为组件，由框架直接提供的称为系统组件，由开发者定义的称为自定义组件。在进行 UI 界面开发时，通常不是简单的将系统组件进行组合使用，而是需要考虑代码可复用性、业务逻辑与UI分离，后续版本演进等因素。因此，将UI和部分业务逻辑封装成自定义组件是不可或缺的能力。

自定义组件具有以下特点：

  • 可组合：允许开发者组合使用系统组件、及其属性和方法。
  • 可重用：自定义组件可以被其他组件重用，并作为不同的实例在不同的父组件或容器中使用。
  • 数据驱动UI更新：通过状态变量的改变，来驱动UI的刷新。
.3.1.1、自定义组件的基本用法

如果在另外的文件中引用该自定义组件，需要使用export关键字导出，并在使用的页面import该自定义组件。

@Component
struct HelloComponent {
  @State message: string = 'Hello, World!';

  build() {
    // HelloComponent自定义组件组合系统组件Row和Text
    Row() {
      Text(this.message)
        .onClick(() => {
          // 状态变量message的改变驱动UI刷新，UI从'Hello, World!'刷新为'Hello, ArkUI!'
          this.message = 'Hello, ArkUI!';
        })
    }
  }
}
.3.1.2、自定义组件的基本结构
  • struct：自定义组件基于struct实现，struct + 自定义组件名 + {…}的组合构成自定义组件，不能有继承关系。对于struct的实例化，可以省略new。
  • @Component：@Component装饰器仅能装饰struct关键字声明的数据结构。struct被@Component装饰后具备组件化的能力，需要实现build方法描述UI，一个struct只能被一个@Component装饰。
  • build()函数：build()函数用于定义自定义组件的声明式UI描述，自定义组件必须定义build()函数。
  • @Entry：@Entry装饰的自定义组件将作为UI页面的入口。在单个UI页面中，最多可以使用@Entry装饰一个自定义组件。@Entry可以接受一个可选的LocalStorage的参数。
.3.1.3、成员函数/变量

自定义组件除了必须要实现build()函数外，还可以实现其他成员函数，成员函数具有以下约束：

  • 不支持静态函数。
  • 成员函数的访问是私有的。

自定义组件可以包含成员变量，成员变量具有以下约束：

  • 不支持静态成员变量。
  • 所有成员变量都是私有的，变量的访问规则与成员函数的访问规则相同。
  • 自定义组件的成员变量本地初始化有些是可选的，有些是必选的。具体是否需要本地初始化，是否需要从父组件通过参数传递初始化子组件的成员变量，请参考状态管理。
.3.1.4、build()函数

所有声明在build()函数的语言，我们统称为UI描述，UI描述需要遵循以下规则：

  • @Entry装饰的自定义组件，其build()函数下的根节点唯一且必要，且必须为容器组件，其中ForEach禁止作为根节点。
    @Component装饰的自定义组件，其build()函数下的根节点唯一且必要，可以为非容器组件，其中ForEach禁止作为根节点。
@Entry
@Component
struct MyComponent {
  build() {
    // 根节点唯一且必要，必须为容器组件
    Row() {
      ChildComponent() 
    }
  }
}

@Component
struct ChildComponent {
  build() {
    // 根节点唯一且必要，可为非容器组件
    Image('test.jpg')
  }
}
  • 不允许声明本地变量，反例如下。
build() {
  // 反例：不允许声明本地变量
  let a: number = 1;
}
  • 不允许在UI描述里直接使用console.info，但允许在方法或者函数里使用，反例如下
build() {
  // 反例：不允许console.info
  console.info('print debug log');
}
  • 不允许创建本地的作用域，反例如下
build() {
  // 反例：不允许本地作用域
  {
    ...
  }
}
  • 不允许调用没有用@Builder装饰的方法，允许系统组件的参数是TS方法的返回值
@Component
struct ParentComponent {
  doSomeCalculations() {
  }

  calcTextValue(): string {
    return 'Hello World';
  }

  @Builder doSomeRender() {
    Text(`Hello World`)
  }

  build() {
    Column() {
      // 反例：不能调用没有用@Builder装饰的方法
      this.doSomeCalculations();
      // 正例：可以调用
      this.doSomeRender();
      // 正例：参数可以为调用TS方法的返回值
      Text(this.calcTextValue())
    }
  }
}
  • 不允许switch语法，如果需要使用条件判断，请使用if。反例如下
build() {
  Column() {
    // 反例：不允许使用switch语法
    switch (expression) {
      case 1:
        Text('...')
        break;
      case 2:
        Image('...')
        break;
      default:
        Text('...')
        break;
    }
  }
}
  • 不允许使用表达式，反例如下
build() {
  Column() {
    // 反例：不允许使用表达式
    (this.aVar > 10) ? Text('...') : Image('...')
  }
}
.3.1.5、自定义组件通用样式

自定义组件通过“.”链式调用的形式设置通用样式。

ArkUI给自定义组件设置样式时，相当于给MyComponent2套了一个不可见的容器组件，而这些样式是设置在容器组件上的，而非直接设置给MyComponent2的Button组件。通过渲染结果我们可以很清楚的看到，背景颜色红色并没有直接生效在Button上，而是生效在Button所处的开发者不可见的容器组件上。

@Component
struct MyComponent2 {
  build() {
    Button(`Hello World`)
  }
}

@Entry
@Component
struct MyComponent {
  build() {
    Row() {
      MyComponent2()
        .width(200)
        .height(300)
        .backgroundColor(Color.Red)
    }
  }
}

.3.2、页面和自定义组件生命周期

在开始之前，我们先明确自定义组件和页面的关系：

  • 自定义组件：@Component装饰的UI单元，可以组合多个系统组件实现UI的复用，可以调用组件的生命周期。
  • 页面：即应用的UI页面。可以由一个或者多个自定义组件组成，@Entry装饰的自定义组件为页面的入口组件，即页面的根节点，一个页面有且仅能有一个@Entry。只有被@Entry装饰的组件才可以调用页面的生命周期。
    鸿蒙App语法/结构/注意-LMLPHP

.4、注解相关

.4.1、@Builder装饰器：自定义构建函数

前面章节介绍了如何创建一个自定义组件。该自定义组件内部UI结构固定，仅与使用方进行数据传递。ArkUI还提供了一种更轻量的UI元素复用机制@Builder，@Builder所装饰的函数遵循build()函数语法规则，开发者可以将重复使用的UI元素抽象成一个方法，在build方法里调用。

为了简化语言，我们将@Builder装饰的函数也称为“自定义构建函数”。‘

  • 允许在自定义组件内定义一个或多个@Builder方法，该方法被认为是该组件的私有、特殊类型的成员函数。
  • 自定义构建函数可以在所属组件的build方法和其他自定义构建函数中调用，但不允许在组件外调用。
  • 在自定义函数体中，this指代当前所属组件，组件的状态变量可以在自定义构建函数内访问。建议通过this访问自定义组件的状态变量而不是参数传递。
  • 全局的自定义构建函数可以被整个应用获取，不允许使用this和bind方法。
  • 如果不涉及组件状态变化，建议使用全局的自定义构建方法。
.4.1.1、参数传递规则

自定义构建函数的参数传递有按值传递和按引用传递两种，均需遵守以下规则：

  • 参数的类型必须与参数声明的类型一致，不允许undefined、null和返回undefined、null的表达式。
  • 在自定义构建函数内部，不允许改变参数值。如果需要改变参数值，且同步回调用点，建议使用@Link。
  • @Builder内UI语法遵循UI语法规则。
  • 只有传入一个参数，且参数需要直接传入对象字面量才会按引用传递该参数，其余传递方式均为按值传递。
.4.1.1.1、按引用传递参数

按引用传递参数时，传递的参数可为状态变量，且状态变量的改变会引起@Builder方法内的UI刷新。ArkUI提供$$作为按引用传递参数的范式。

ABuilder( $$ : { paramA1: string, paramB1 : string } );
@Builder function ABuilder($$: { paramA1: string }) {
  Row() {
    Text(`UseStateVarByReference: ${$$.paramA1} `)
  }
}
@Entry
@Component
struct Parent {
  @State label: string = 'Hello';
  build() {
    Column() {
      // 在Parent组件中调用ABuilder的时候，将this.label引用传递给ABuilder
      ABuilder({ paramA1: this.label })
      Button('Click me').onClick(() => {
        // 点击“Click me”后，UI从“Hello”刷新为“ArkUI”
        this.label = 'ArkUI';
      })
    }
  }
}
4.1.1.2、按值传递参数

调用@Builder装饰的函数默认按值传递。当传递的参数为状态变量时，状态变量的改变不会引起@Builder方法内的UI刷新。所以当使用状态变量的时候，推荐使用按引用传递。

@Builder function ABuilder(paramA1: string) {
  Row() {
    Text(`UseStateVarByValue: ${paramA1} `)
  }
}
@Entry
@Component
struct Parent {
  @State label: string = 'Hello';
  build() {
    Column() {
      ABuilder(this.label)
    }
  }
}

.4.2、@BuilderParam装饰器：引用@Builder函数

https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/arkts-builderparam-0000001524416541-V3
当开发者创建了自定义组件，并想对该组件添加特定功能时，例如在自定义组件中添加一个点击跳转操作。若直接在组件内嵌入事件方法，将会导致所有引入该自定义组件的地方均增加了该功能。为解决此问题，ArkUI引入了@BuilderParam装饰器，@BuilderParam用来装饰指向@Builder方法的变量，开发者可在初始化自定义组件时对此属性进行赋值，为自定义组件增加特定的功能。该装饰器用于声明任意UI描述的一个元素，类似slot占位符。

  • @BuilderParam装饰的方法只能被自定义构建函数（@Builder装饰的方法）初始化。
///使用所属自定义组件的自定义构建函数或者全局的自定义构建函数，在本地初始化@BuilderParam。
@Builder function GlobalBuilder0() {}

@Component
struct Child {
  @Builder doNothingBuilder() {};

  @BuilderParam aBuilder0: () => void = this.doNothingBuilder;
  @BuilderParam aBuilder1: () => void = GlobalBuilder0;
  build(){}
}


///用父组件自定义构建函数初始化子组件@BuilderParam装饰的方法。
@Component
struct Child {
  @BuilderParam aBuilder0: () => void;

  build() {
    Column() {
      this.aBuilder0()
    }
  }
}

@Entry
@Component
struct Parent {
  @Builder componentBuilder() {
    Text(`Parent builder `)
  }

  build() {
    Column() {
      Child({ aBuilder0: this.componentBuilder })
    }
  }
}

///以下示例中，Parent组件在调用this.componentBuilder()时，this指向其所属组件，即“Parent”。@Builder componentBuilder()传给子组件@BuilderParam aBuilder0，在Child组件中调用this.aBuilder0()时，this指向在Child的label，即“Child”。
@Component
struct Child {
  label: string = `Child`
  @BuilderParam aBuilder0: () => void;

  build() {
    Column() {
      this.aBuilder0()
    }
  }
}

@Entry
@Component
struct Parent {
  label: string = `Parent`

  @Builder componentBuilder() {
    Text(`${this.label}`)
  }

  build() {
    Column() {
      this.componentBuilder()
      Child({ aBuilder0: this.componentBuilder })
    }
  }
}
  • @BuilderParam装饰的方法可以是有参数和无参数的两种形式，需与指向的@Builder方法类型匹配。@BuilderParam装饰的方法类型需要和@Builder方法类型一致。
@Builder function GlobalBuilder1($$ : {label: string }) {
  Text($$.label)
    .width(400)
    .height(50)
    .backgroundColor(Color.Green)
}

@Component
struct Child {
  label: string = 'Child'
  // 无参数类，指向的componentBuilder也是无参数类型
  @BuilderParam aBuilder0: () => void;
  // 有参数类型，指向的GlobalBuilder1也是有参数类型的方法
  @BuilderParam aBuilder1: ($$ : { label : string}) => void;

  build() {
    Column() {
      this.aBuilder0()
      this.aBuilder1({label: 'global Builder label' } )
    }
  }
}

@Entry
@Component
struct Parent {
  label: string = 'Parent'

  @Builder componentBuilder() {
    Text(`${this.label}`)
  }

  build() {
    Column() {
      this.componentBuilder()
      Child({ aBuilder0: this.componentBuilder, aBuilder1: GlobalBuilder1 })
    }
  }
}
  • 在自定义组件中使用@BuilderParam装饰的属性时也可通过尾随闭包进行初始化。在初始化自定义组件时，组件后紧跟一个大括号“{}”形成尾随闭包场景。
// xxx.ets
@Component
struct CustomContainer {
  @Prop header: string;
  @BuilderParam closer: () => void

  build() {
    Column() {
      Text(this.header)
        .fontSize(30)
      this.closer()
    }
  }
}

@Builder function specificParam(label1: string, label2: string) {
  Column() {
    Text(label1)
      .fontSize(30)
    Text(label2)
      .fontSize(30)
  }
}

@Entry
@Component
struct CustomContainerUser {
  @State text: string = 'header';

  build() {
    Column() {
      // 创建CustomContainer，在创建CustomContainer时，通过其后紧跟一个大括号“{}”形成尾随闭包
      // 作为传递给子组件CustomContainer @BuilderParam closer: () => void的参数
      CustomContainer({ header: this.text }) {
        Column() {
          specificParam('testA', 'testB')
        }.backgroundColor(Color.Yellow)
        .onClick(() => {
          this.text = 'changeHeader';
        })
      }
    }
  }
}

.4.3、@Styles装饰器：定义组件重用样式

@Styles装饰器可以将多条样式设置提炼成一个方法，直接在组件声明的位置调用。通过@Styles装饰器可以快速定义并复用自定义样式。用于快速定义并复用自定义样式。

  • 当前@Styles仅支持通用属性和通用事件。
  • @Styles方法不支持参数，反例如下。
// 反例： @Styles不支持参数
@Styles function globalFancy (value: number) {
  .width(value)
}
  • @Styles可以定义在组件内或全局，在全局定义时需在方法名前面添加function关键字，组件内定义时则不需要添加function关键字。
// 全局
@Styles function functionName() { ... }

// 在组件内
@Component
struct FancyUse {
  @Styles fancy() {
    .height(100)
  }
}
  • 定义在组件内的@Styles可以通过this访问组件的常量和状态变量，并可以在@Styles里通过事件来改变状态变量的值，示例如下：
@Component
struct FancyUse {
  @State heightValue: number = 100
  @Styles fancy() {
    .height(this.heightValue)
    .backgroundColor(Color.Yellow)
    .onClick(() => {
      this.heightValue = 200
    })
  }
}
  • 组件内@Styles的优先级高于全局@Styles。框架优先找当前组件内的@Styles，如果找不到，则会全局查找。

以下示例中演示了组件内@Styles和全局@Styles的用法

// 定义在全局的@Styles封装的样式
@Styles function globalFancy  () {
  .width(150)
  .height(100)
  .backgroundColor(Color.Pink)
}

@Entry
@Component
struct FancyUse {
  @State heightValue: number = 100
  // 定义在组件内的@Styles封装的样式
  @Styles fancy() {
    .width(200)
    .height(this.heightValue)
    .backgroundColor(Color.Yellow)
    .onClick(() => {
      this.heightValue = 200
    })
  }

  build() {
    Column({ space: 10 }) {
      // 使用全局的@Styles封装的样式
      Text('FancyA')
        .globalFancy ()
        .fontSize(30)
      // 使用组件内的@Styles封装的样式
      Text('FancyB')
        .fancy()
        .fontSize(30)
    }
  }
}

.4.4、@Extend装饰器：定义扩展组件样式

在前文的示例中，可以使用@Styles用于样式的扩展，在@Styles的基础上，我们提供了@Extend，用于扩展原生组件样式。

  • 和@Styles不同，@Extend仅支持定义在全局，不支持在组件内部定义。
  • 和@Styles不同，@Extend支持封装指定的组件的私有属性和私有事件和预定义相同组件的@Extend的方法。
// @Extend(Text)可以支持Text的私有属性fontColor
@Extend(Text) function fancy () {
  .fontColor(Color.Red)
}
// superFancyText可以调用预定义的fancy
@Extend(Text) function superFancyText(size:number) {
    .fontSize(size)
    .fancy()
}
  • 和@Styles不同，@Extend装饰的方法支持参数，开发者可以在调用时传递参数，调用遵循TS方法传值调用。
// xxx.ets
@Extend(Text) function fancy (fontSize: number) {
  .fontColor(Color.Red)
  .fontSize(fontSize)
}

@Entry
@Component
struct FancyUse {
  build() {
    Row({ space: 10 }) {
      Text('Fancy')
        .fancy(16)
      Text('Fancy')
        .fancy(24)
    }
  }
}
  • @Extend装饰的方法的参数可以为function，作为Event事件的句柄。
@Extend(Text) function makeMeClick(onClick: () => void) {
  .backgroundColor(Color.Blue)
  .onClick(onClick)
}

@Entry
@Component
struct FancyUse {
  @State label: string = 'Hello World';

  onClickHandler() {
    this.label = 'Hello ArkUI';
  }

  build() {
    Row({ space: 10 }) {
      Text(`${this.label}`)
        .makeMeClick(this.onClickHandler.bind(this))
    }
  }
}
  • @Extend的参数可以为状态变量，当状态变量改变时，UI可以正常的被刷新渲染。
@Extend(Text) function fancy (fontSize: number) {
  .fontColor(Color.Red)
  .fontSize(fontSize)
}

@Entry
@Component
struct FancyUse {
  @State fontSizeValue: number = 20
  build() {
    Row({ space: 10 }) {
      Text('Fancy')
        .fancy(this.fontSizeValue)
        .onClick(() => {
          this.fontSizeValue = 30
        })
    }
  }
}

.4.5、stateStyles：多态样式

@Styles和@Extend仅仅应用于静态页面的样式复用，stateStyles可以依据组件的内部状态的不同，快速设置不同样式。这就是我们本章要介绍的内容stateStyles（又称为：多态样式）。

stateStyles是属性方法，可以根据UI内部状态来设置样式，类似于css伪类，但语法不同。ArkUI提供以下四种状态：

  • focused：获焦态。
  • normal：正常态。
  • pressed：按压态。
  • disabled：不可用态。
@Entry
@Component
struct StateStylesSample {
  build() {
    Column() {
      Button('Button1')
        .stateStyles({
          focused: {
            .backgroundColor(Color.Pink)
          },
          pressed: {
            .backgroundColor(Color.Black)
          },
          normal: {
            .backgroundColor(Color.Red)
          }
        })
        .margin(20)
      Button('Button2')
        .stateStyles({
          focused: {
            .backgroundColor(Color.Pink)
          },
          pressed: {
            .backgroundColor(Color.Black)
          },
          normal: {
            .backgroundColor(Color.Red)
          }
        })
    }.margin('30%')
  }
}

鸿蒙App语法/结构/注意-LMLPHP
@Styles和stateStyles联合使用
以下示例通过@Styles指定stateStyles的不同状态。

@Entry
@Component
struct MyComponent {
  @Styles normalStyle() {
    .backgroundColor(Color.Gray)
  }

  @Styles pressedStyle() {
    .backgroundColor(Color.Red)
  }

  build() {
    Column() {
      Text('Text1')
        .fontSize(50)
        .fontColor(Color.White)
        .stateStyles({
          normal: this.normalStyle,
          pressed: this.pressedStyle,
        })
    }
  }
}

鸿蒙App语法/结构/注意-LMLPHP
stateStyles可以通过this绑定组件内的常规变量和状态变量。

@Entry
@Component
struct CompWithInlineStateStyles {
  @State focusedColor: Color = Color.Red;
  normalColor: Color = Color.Green

  build() {
    Column() {
      Button('clickMe').height(100).width(100)
        .stateStyles({
          normal: {
            .backgroundColor(this.normalColor)
          },
          focused: {
            .backgroundColor(this.focusedColor)
          }
        })
        .onClick(() => {
          this.focusedColor = Color.Pink
        })
        .margin('30%')
    }
  }
}

Button默认normal态显示绿色，第一次按下Tab键让Button获焦显示为focus态的红色，点击事件触发后，再次按下Tab键让Button获焦，focus态变为粉色。
鸿蒙App语法/结构/注意-LMLPHP

状态管理

https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/arkts-state-management-overview-0000001524537145-V3
在声明式UI编程框架中，UI是程序状态的运行结果，用户构建了一个UI模型，其中应用的运行时的状态是参数。当参数改变时，UI作为返回结果，也将进行对应的改变。这些运行时的状态变化所带来的UI的重新渲染，在ArkUI中统称为状态管理机制。

自定义组件拥有变量，变量必须被装饰器装饰才可以成为状态变量，状态变量的改变会引起UI的渲染刷新。如果不使用状态变量，UI只能在初始化时渲染，后续将不会再刷新。 下图展示了State和View（UI）之间的关系。
鸿蒙App语法/结构/注意-LMLPHP

  • View(UI)：UI渲染，指将build方法内的UI描述和@Builder装饰的方法内的UI描述映射到界面。
  • State：状态，指驱动UI更新的数据。用户通过触发组件的事件方法，改变状态数据。状态数据的改变，引起UI的重新渲染。

.1、基本概念

  • 状态变量：被状态装饰器装饰的变量，状态变量值的改变会引起UI的渲染更新。示例：@State num: number = 1,其中，@State是状态装饰器，num是状态变量。
  • 常规变量：没有被状态装饰器装饰的变量，通常应用于辅助计算。它的改变永远不会引起UI的刷新。以下示例中increaseBy变量为常规变量。
  • 数据源/同步源：状态变量的原始来源，可以同步给不同的状态数据。通常意义为父组件传给子组件的数据。以下示例中数据源为count: 1。
  • 命名参数机制：父组件通过指定参数传递给子组件的状态变量，为父子传递同步参数的主要手段。示例：CompA: ({ aProp: this.aProp })。
  • 从父组件初始化：父组件使用命名参数机制，将指定参数传递给子组件。子组件初始化的默认值在有父组件传值的情况下，会被覆盖。示例：
@Component
struct MyComponent {
  @State count: number = 0;
  private increaseBy: number = 1;

  build() {
  }
}

@Component
struct Parent {
  build() {
    Column() {
      // 从父组件初始化，覆盖本地定义的默认值
      MyComponent({ count: 1, increaseBy: 2 })
    }
  }
}
  • 初始化子节点：父组件中状态变量可以传递给子组件，初始化子组件对应的状态变量。示例同上。
  • 本地初始化：在变量声明的时候赋值，作为变量的默认值。示例：@State count: number = 0。

.2、装饰器总览

ArkUI提供了多种装饰器，通过使用这些装饰器，状态变量不仅可以观察在组件内的改变，还可以在不同组件层级间传递，比如父子组件、跨组件层级，也可以观察全局范围内的变化。根据状态变量的影响范围，将所有的装饰器可以大致分为：

  • 管理组件拥有状态的装饰器：组件级别的状态管理，可以观察组件内变化，和不同组件层级的变化，但需要唯一观察同一个组件树上，即同一个页面内。
  • 管理应用拥有状态的装饰器：应用级别的状态管理，可以观察不同页面，甚至不同UIAbility的状态变化，是应用内全局的状态管理。

从数据的传递形式和同步类型层面看，装饰器也可分为：

  • 只读的单向传递；
  • 可变更的双向传递。

图示如下，具体装饰器的介绍，可详见管理组件拥有的状态和管理应用拥有的状态。开发者可以灵活地利用这些能力来实现数据和UI的联动。
鸿蒙App语法/结构/注意-LMLPHP
上图中，Components部分的装饰器为组件级别的状态管理，Application部分为应用的状态管理。开发者可以通过@StorageLink/@LocalStorageLink实现应用和组件状态的双向同步，通过@StorageProp/@LocalStorageProp实现应用和组件状态的单向同步。

管理组件拥有的状态，即图中Components级别的状态管理：

  • @State：@State装饰的变量拥有其所属组件的状态，可以作为其子组件单向和双向同步的数据源。当其数值改变时，会引起相关组件的渲染刷新。
  • @Prop：@Prop装饰的变量可以和父组件建立单向同步关系，@Prop装饰的变量是可变的，但修改不会同步回父组件。
  • @Link：@Link装饰的变量和父组件构建双向同步关系的状态变量，父组件会接受来自-@Link装饰的变量的修改的同步，父组件的更新也会同步给@Link装饰的变量。
  • @Provide/@Consume：@Provide/@Consume装饰的变量用于跨组件层级（多层组件）同步状态变量，可以不需要通过参数命名机制传递，通过alias（别名）或者属性名绑定。
  • @Observed：@Observed装饰class，需要观察多层嵌套场景的class需要被@Observed装饰。单独使用@Observed没有任何作用，需要和@ObjectLink、@Prop连用。
  • @ObjectLink：@ObjectLink装饰的变量接收@Observed装饰的class的实例，应用于观察多层嵌套场景，和父组件的数据源构建双向同步。

管理应用拥有的状态，即图中Application级别的状态管理：

  • AppStorage是应用程序中的一个特殊的单例LocalStorage对象，是应用级的数据库，和进程绑定，通过@StorageProp和@StorageLink装饰器可以和组件联动。
  • AppStorage是应用状态的“中枢”，将需要与组件（UI）交互的数据存入AppStorage，比如持久化数据PersistentStorage和环境变量Environment。UI再通过AppStorage提供的装饰器或者API接口，访问这些数据。
  • 框架还提供了LocalStorage，AppStorage是LocalStorage特殊的单例。LocalStorage是应用程序声明的应用状态的内存“数据库”，通常用于页面级的状态共享，通过@LocalStorageProp和@LocalStorageLink装饰器可以和UI联动。

.2.1、其他状态管理功能

@Watch用于监听状态变量的变化。
$$运算符：给内置组件提供TS变量的引用，使得TS变量和内置组件的内部状态保持同步。

03-10 08:01
Powered by LMLPHP ©2024 Loren_Wang 0.010352