系列文章目录
【鸿蒙】HarmonyOS NEXT开发快速入门教程之ArkTS语法装饰器（上）
【鸿蒙】HarmonyOS NEXT开发快速入门教程之ArkTS语法装饰器（下）
文章目录
- 系列文章目录
- 前言
- 一、装饰器语法
- 6.@Builder
- 语法：
- （1）在组件内创建（按值传递）：
- （2）在组件外创建（按值传递）
- （3）对象字面量入参形式（引用传递）
- 示例1：
- 示例2：
- 示例3：
- 7.@BuilderParam
- 语法：
- 示例1：
- 示例2：
- 8.@Styles
- 语法：
- 示例1：
- 示例2：
- 9.@Extend
- 语法：
- 示例：
- 10.@LocalStorageProp和@LocalStorageLink
- 语法：
- 示例
- 11.@StorageProp和@StorageLink
- 语法：
- 示例：
- 二、 总结
前言
HarmonyOS NEXT（鸿蒙应用）开发快速入门教程ArkTS语法之装饰器篇（下），基于HarmonyOS NEXT Beta1版本（api 12）讲解。
一、装饰器语法
6.@Builder
自定义组件除了通过@Component申明方式构建，也可以通过函数方式构建。@Builder就是用来装饰函数定义一个轻量级组件(UI元素)，因此@Builder装饰器也简称为自定义构建函数，返回一个组件或UI元素。类似vue的render函数，通过函数形式来构建UI元素。
语法：
（1）在组件内创建（按值传递）：
@Component
struct Demo {
@Builder 函数名(参数1：类型，参数2：类型,.....) {
}
}
调用：
this.函数名(参数1：类型，参数2：类型,.....)
（2）在组件外创建（按值传递）
@Builder function 函数名(参数1：类型，参数2：类型,.....) {
}
@Component
struct Demo {
}
调用：
函数名(参数1：类型，参数2：类型,.....)
（3）对象字面量入参形式（引用传递）
class ClassName{
a:xxxx
b:xxxx
c:xxxx
}
@Component
struct Demo {
@Builder 函数名($$:ClassName) {
}
}
调用
函数名({
a:value,
b:value2,
c:value3,
......
.......
})
说明：
1、在组件内创建称为私有自定义构建函数，只有当前组件能使用，在组件外创建称为全局自定义构建函数，所有组件都能使用。
2、入参有2种写法，一种像上面示例传递多个形参方式，称为按值传递，另一种把多个参数写成对象字面量形式（只有一个入参）传入，这种叫按引用传递。按值传递只会在首次渲染时候有效，后续修改入参值将无法响应UI变化，而引用传递修改对象字面量属性值会响应UI变化，所以推荐入参全部写成对象字面量形式。
示例1：
按引用传递
class BuilderParams {
image: Resource | string = ''
label: string = ''
}
@Entry
@Component
struct Parent {
@State image: Resource = $r('app.media.home')//图标
@State label: string = '首页'; //标签
//自定义构建函数
@Builder
childBuilder(params: BuilderParams) {
Column({ space: 6 }) {
Image(params.image).width(100)
Text(params.label).fontSize(16)
}
}
build() {
Column({ space: 30 }) {
this.childBuilder({ image: this.image, label: this.label })
Button('改变图标和标签').onClick(() => {
this.image = $r('app.media.mine')
this.label = '我的'
})
}.width('100%')
}
}
运行效果：
示例2：
示例1也可以改成 如下直接访问外部状态变量，效果一样
@Entry
@Component
struct Parent {
@State image: Resource = $r('app.media.home')//图标
@State label: string = '首页'; //标签
//自定义构建函数
@Builder
childBuilder() {
Column({ space: 6 }) {
Image(this.image).width(100)
Text(this.label).fontSize(16)
}
}
build() {
Column({ space: 30 }) {
this.childBuilder()
Button('改变图标和标签').onClick(() => {
this.image = $r('app.media.mine')
this.label = '我的'
})
}.width('100%')
}
}
示例3：
示例1也可以改成全局构建自定义函数，效果一样
class BuilderParams {
image: Resource | string = ''
label: string = ''
}
//全局自定义构建函数
@Builder
function childBuilder(params: BuilderParams) {
Column({ space: 6 }) {
Image(params.image).width(100)
Text(params.label).fontSize(16)
}
}
@Entry
@Component
struct Parent {
@State image: Resource = $r('app.media.home')//图标
@State label: string = '首页'; //标签
build() {
Column({ space: 30 }) {
childBuilder({ image: this.image, label: this.label })
Button('改变图标和标签').onClick(() => {
this.image = $r('app.media.mine')
this.label = '我的'
})
}.width('100%')
}
}
@Builder和@Component都可以自定义组件，我们要怎么选择呢？
@Builder主要封装轻量级UI元素，组件参数传递只靠入参或者直接访问外部状态变量，无生命周期函数、无法使用其他装饰器功能，有开发的局限性，而@Component适用于构建复杂逻辑的组件，有自己的生命周期可以使用各种类型装饰器，可实现更复杂的场景。
实际开发根据自己的需求场景去选择，如果2种方式都满足，选择@Builder方式性能会更好。
7.@BuilderParam
@BuilderParam相当于vue的插槽作用（slot），先在子组件调用@BuilderParam修饰的函数占位，具体渲染内容从父组件传入，通过上面介绍我们知道@Builder是用来自定义一个组件，父组件通过@Builder生成的组件当参数传入子组件，子组件拿到@Builder组件在占位地方填充渲染。所以可以简单理解和记忆@BuilderParam是子组件的入参（函数类型），入参类型是@Builder函数。
语法：
子组件：
@Builder A() {};
@BuilderParam B:类型=this.A
build(){
...
...
//插槽占位
this.B()
}
ps:@BuilderParam装饰的函数初始值必须设置且只能是@Builder装饰的函数
父组件：
//自定义插槽内容
@Builder C（）{
}
build(){
...
...
child({B:this.C})
}
如果只有一个插槽，父组件可以省略自定义构建函数，直接在子组件内嵌套写布局，此方式叫尾随闭包初始化组件，相当于vue中的默认插槽场景
父组件
build(){
...
...
child(){
//自定义插槽内容
......
......
}
}
示例1：
只有一个@BuilderParam
@Entry
@Component
struct Parent {
@Builder customBuild(){
//插槽内容
Button('插槽按钮')
}
build() {
Column({ space: 30 }) {
Child({customBuilderParam:this.customBuild})
}.width('100%')
}
}
@Component
struct Child{
@Builder customBuilder() {};
@BuilderParam customBuilderParam:()=>void=this.customBuilder
build() {
Column(){
Text('child组件')
//插槽占位
this.customBuilderParam()
}
}
}
示例2：
只有一个@BuilderParam可以写成尾随闭包方式：
@Entry
@Component
struct Parent {
build() {
Column({ space: 30 }) {
Child(){
//插槽内容
Button('插槽按钮')
}
}.width('100%')
}
}
@Component
struct Child{
@Builder customBuilder() {};
@BuilderParam customBuilderParam:()=>void=this.customBuilder
build() {
Column(){
Text('child组件')
//插槽占位
this.customBuilderParam()
}
}
}
运行效果：
8.@Styles
@Styles用于装饰函数，函数内封装公共通用属性或通用事件，提供给需要的组件复用。类似scss里面的@mixin的作用
语法：
和@Builder类似@Styles可以定义在组件内或全局，在全局定义时需在方法名前面添加function关键字，组件内定义时则不需要添加function关键字
（1）全局：
@Styles function functionName() { ... }
调用：
组件(){
}.functionName()
（2）组件内：
// 在组件内
@Component
struct Demo{
@Styles functionName() {
.height(100)
}
}
调用：
组件(){
}.functionName()
使用限制规则：
1、@Styles仅支持通用属性和通用事件
2、@Styles修饰的方法不支持入参
3、只能在当前文件内使用，不支持export导出给其他文件使用
4、组件内的@Styles优先级高于全局@Style
示例1：
全局定义
//全局公共样式
@Styles
function globalStyle() {
.width('100%')
.height(100)
.padding(10)
.backgroundColor(Color.Green)
.border({ width: 1, color: Color.Black, style: BorderStyle.Solid })
.borderRadius(10)
}
@Entry
@Component
struct Parent {
build() {
Column({ space: 30 }) {
Text('text1').fontColor(Color.White).globalStyle()
Text('text2').fontColor(Color.White).globalStyle()
Text('text3').fontColor(Color.White).globalStyle()
}.width('100%')
.padding(20)
}
}
运行效果：
示例2：
组件内定义
@Entry
@Component
struct Demo {
@State bgColor: ResourceColor = Color.Yellow //背景色
@State iHeight: number = 100 //高度
//组件内样式
@Styles
globalStyle() {
.width('100%')
.height(this.iHeight)
.border({ width: 1, color: Color.Black, style: BorderStyle.Solid })
.backgroundColor(this.bgColor)
.borderRadius(10)
.onClick(() => {
//高度+10
this.iHeight += 10
})
}
//按钮样式
@Styles
custButtonStyle(){
.width(200)
.height(80)
.onClick(() => {
//切换背景色
this.bgColor = this.bgColor === Color.Pink ? Color.Yellow : Color.Pink
})
}
build() {
Column({ space: 30 }) {
Column() {
Text('点击高度+10')
}
.justifyContent(FlexAlign.Center)
.globalStyle()
Button('改变颜色').custButtonStyle()
}.width('100%')
.padding(20)
}
}
运行效果：
从上述示例看，尽管@Styles装饰的函数不能写入参数，但是我们可以把@Style定义在组件内，并通过this去访问组件内的状态变量，达到动态传参的效果。
9.@Extend
@Extend跟@Styles功能类似，都是用来抽离组件属性和事件，@Extend针对的是某个具体系统组件单独设置，单独使用，而@Styles所有组件通用。
语法：
@Extend(系统组件名) function functionName(入参可选) { ... }
使用规则：
1、和@Styles不同，@Extend仅支持在全局定义，不支持在组件内部定义。
2、和@Styles不同，@Extend支持封装指定组件的私有属性、私有事件和自身定义的全局方法。
3、和@Styles不同，@Extend装饰的方法支持参数，开发者可以在调用时传递参数，调用遵循TS方法传值调用。
4、只支持扩展原生组件，不支持自定义组件
示例：
/**
* 自定义按钮样式
* @param height:按钮高
* @param width ：按钮宽
* @param backgourndColor ：按钮背景色
* @param type //按钮样式
*/
@Extend(Button)
function customButton(height: number, width: number, backgourndColor: ResourceColor, type: ButtonType) {
.height(height)
.width(width)
.type(type)
.backgroundColor(backgourndColor)
.fontColor(Color.White)
.fontSize(14)
}
@Entry
@Component
struct Demo {
build() {
Column({ space: 30 }) {
Button('提交').customButton(50, 300, Color.Blue, ButtonType.Capsule)
Button('删除').customButton(60, 60, Color.Red, ButtonType.Circle)
}.width('100%')
.padding(20)
}
}
运行效果：
从以下开始的装饰器都是跟数据本地存储相关
10.@LocalStorageProp和@LocalStorageLink
@LocalStorageProp和@LocalStorageLink是页面级的UI状态存储，通过@Entry装饰器接收的参数可以在页面内共享同一个LocalStorage实例。
简单说每个注册的路由页面（@Entry装饰的组件）单独享有和管理一个LocalStorage实例，包括该页面引入的子孙组件共用同一个LocalStorage来存取数据。每个页面单独使用互不影响，默认不能相互访问，不能覆盖存储，关闭页面LocalStorage实例被系统回收数据被清除，类似web sessionStorage。
@LocalStorageProp(key)是和LocalStorage实例中key对应的属性建立单向数据同步。LocalStorage实例中key数据改变，@LocalStorageProp(key)装饰的变量也将跟着改变并能响应UI变化。
@LocalStorageLink(key)是和LocalStorage实例中key对应的属性建立双向数据同步，两者区别跟@Prop和@Link一样，一个数据单向流动一个双向绑定，其他作用一致。
语法：
创建LocalStorage实例：
let storage: LocalStorage = new LocalStorage();
storage.setOrCreate(key,value)//创建属性
storage.setOrCreate(key2,value2)//创建属性
storage.setOrCreate(key3,value3)//创建属性
...
...
@Entry(storage)//页面绑定LocalStorage
@Component
struct Parent {
}
组件调用：
@Entry(storage)
@Component
struct Parent {
@LocalStorageProp(key) 变量:类型=默认值
@LocalStorageLink(key) 变量:类型=默认值
}
修改值：
分两种方式，如果是@LocalStorageLink(key)双向绑定只要修改@LocalStorageLink绑定变量即可。另一种通过调用LocalStorage实例的方法修改
storage.set(key,value)
也可以通过storage获取值：
storage.get(key)
判断key是否存在
storage.has(key)
删除LocalStorage中所有的属性
storage.clear()
更多的api可以查看LocalStorage9+文档
示例
//城市地区对象
class AddressProp{
city:string
area:string
constructor(city:string,area:string) {
this.city=city
this.area=area
}
}
let storage: LocalStorage = new LocalStorage();
storage.setOrCreate('name','李磊')
storage.setOrCreate('age',0)
storage.setOrCreate('address',new AddressProp('厦门市','思明区'))
@Entry(storage)
@Component
struct Parent {
@LocalStorageProp('name') name:string='' //姓名
@LocalStorageLink('age') age:number=0 //年龄
@LocalStorageLink('address') address:AddressProp=new AddressProp('','') //地址
build() {
Column({ space: 20 }) {
Text(`姓名：${this.name}`)
Text(`年龄:${this.age}`)
//子组件
Child()
Button('修改姓名').onClick(()=>{
storage.set('name','小明')
})
Button('修改年龄').onClick(()=>{
this.age=20
})
Button('修改城市').onClick(()=>{
this.address.city='福州市'
})
Button('修改地区').onClick(()=>{
this.address.area='鼓楼区'
})
Button('修改城市+地区').onClick(()=>{
storage.set('address',new AddressProp('泉州市','丰泽区'))
})
}.padding(20).alignItems(HorizontalAlign.Start)
}
}
//子组件
@Component
struct Child {
@LocalStorageLink('address') address:AddressProp=new AddressProp('','')
build() {
Column({space:20}){
Text(`地址：${this.address.city}${this.address.area}`)
}
}
}
运行效果：
11.@StorageProp和@StorageLink
@StorageProp和@StorageLink是应用全局的UI状态存储，与之对应的是全局静态类AppStorage。和进程绑定，同一进程下的所有页面共用，生命周期和LocalStorage类似，当关闭应用将被回收，如果想要数据持久化本地保存需要结合PersistentStorage使用。
语法：
@Entry
@Component
struct Parent {
@StorageLink(key) 变量:类型=默认值
@StorageProp(key) 变量:类型=默认值
}
无需创建实例，直接使用
AppStorage和LocalStorage实例内置方法一样
AppStorage.setOrCreate(key,value) //创建属性
AppStorage.set(key,value) //设置值
AppStorage.get(key) //获取值
AppStorage.has(key)//判断是否存在属性
AppStorage.clear()//清除所有属性
示例：
Index.ets （第一个页面）
import { router } from '@kit.ArkUI'
//商品对象类型
export class GoodsProp{
name:string
price:number
image:Resource|string
constructor(name:string,price:number,image:Resource|string) {
this.name=name
this.price=price
this.image=image
}
}
//创建属性并设置初始值
AppStorage.setOrCreate('category','水果')
AppStorage.setOrCreate('place','海南')
AppStorage.setOrCreate('goods',new GoodsProp('榴莲',200,'https://img0.baidu.com/it/u=211945568,1824960805&fm=253&fmt=auto&app=120&f=JPEG?w=399&h=399'))
@Entry
@Component
struct Demo {
@StorageProp('category') category:string=''
@StorageLink('place') place:string=''
@StorageLink('goods') goods:GoodsProp=new GoodsProp('',0,'')
build() {
Column({ space: 20 }) {
Text(`类别：${this.category}`)
Text(`产地：${this.place}`)
Text(`名称：${this.goods.name}`)
Text(`价格：￥${this.goods.price}`)
Image(this.goods.image).width(100)
Button('修改商品信息').onClick(()=>{
//修改商品信息
AppStorage.set('category','饮料')
this.place='福建'
this.goods=new GoodsProp('雪津啤酒',10,'https://img1.baidu.com/it/u=3892212987,1352825001&fm=253&fmt=auto&app=138&f=JPEG?w=283&h=800')
})
Button('跳转下一页').onClick(()=>{
router.pushUrl({url:'pages/Second'})
})
}.padding(20).alignItems(HorizontalAlign.Start)
}
}
Second.ets(第二个页面)
import {GoodsProp} from './Index'
import { router } from '@kit.ArkUI'
@Entry
@Component
struct Second{
@StorageLink('category') category:string=''
@StorageProp('place') place:string=''
@StorageProp('goods') goods:GoodsProp=new GoodsProp('',0,'')
build() {
Column({ space: 20 }) {
Text(`类别：${this.category}`)
Text(`产地：${this.place}`)
Text(`名称：${this.goods.name}`)
Text(`价格：￥${this.goods.price}`)
Image(this.goods.image).width(100)
Button('修改商品信息').onClick(()=>{
//修改商品信息
this.category="食物"
AppStorage.set('place','北京')
AppStorage.set('goods',new GoodsProp('北京烤鸭',50,'https://img2.baidu.com/it/u=543904622,2448295859&fm=253&fmt=auto&app=138&f=JPEG?w=500&h=667'))
})
Button('返回上一页').onClick(()=>{
router.back()
})
}.padding(20).alignItems(HorizontalAlign.Start)
}
}
运行效果：
想要持久化数据只需页面开头用PersistentStorage.persistProp(key,value)初始化属性即可
例如上个例子改为：
Index.ets:
import { router } from '@kit.ArkUI'
//商品对象类型
export class GoodsProp{
name:string
price:number
image:Resource|string
constructor(name:string,price:number,image:Resource|string) {
this.name=name
this.price=price
this.image=image
}
}
PersistentStorage.persistProp('category','水果')
PersistentStorage.persistProp('place','海南')
PersistentStorage.persistProp('goods',new GoodsProp('榴莲',200,'https://img0.baidu.com/it/u=211945568,1824960805&fm=253&fmt=auto&app=120&f=JPEG?w=399&h=399'))
@Entry
@Component
struct Demo {
@StorageProp('category') category:string=''
@StorageLink('place') place:string=''
@StorageLink('goods') goods:GoodsProp=new GoodsProp('',0,'')
build() {
Column({ space: 20 }) {
Text(`类别：${this.category}`)
Text(`产地：${this.place}`)
Text(`名称：${this.goods.name}`)
Text(`价格：￥${this.goods.price}`)
Image(this.goods.image).width(100)
Button('修改商品信息').onClick(()=>{
//修改商品信息
AppStorage.set('category','饮料')
this.place='福建'
this.goods=new GoodsProp('雪津啤酒',10,'https://img1.baidu.com/it/u=3892212987,1352825001&fm=253&fmt=auto&app=138&f=JPEG?w=283&h=800')
})
Button('跳转下一页').onClick(()=>{
router.pushUrl({url:'pages/Second'})
})
}.padding(20).alignItems(HorizontalAlign.Start)
}
}
二、 总结
至此11个常用的装饰器已经讲完了，完全掌握你将能从容应对大部分的需求场景开发。v2版本官方也在加速推进开发中，我们完全能期待下一个版本正式发布，因为v2版本又会新增多个实用装饰器，改进v1版本不足将带来更加便捷的开发方式。例如有类似vue中的compute计算属性装饰器、类似@click装饰事件的装饰器，以及对对象深度监听支持等。
