初始ArkTS语言

1. 简单介绍

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

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

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

2.基本语法

2.1.组件声明和使用

一个组件可以实现以下功能

参数设置：可以是有参数和无参数两种
```
1.  Text('item 1')
1.  Divider()
```
属性设置

Text('test').fontSize(12)

事件设置

1.  Button('Click me')
1.  .onClick(() => {
1.  this.myText = 'ArkUI';
1.  })

子元素设置

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

自定义组件（与java类似就是定一个类）

定义：

@Component修饰组件
struct 定义组件,{}进行组件的开关与闭合

struct ParentComponent {}
build()函数：build()函数用于定义自定义组件的声明式UI描述，自定义组件必须定义build()函数。
- build()函数不允许调用没有用@Builder装饰的方法，允许系统组件的参数是TS方法的返回值。
- 不允许switch语法，如果需要使用条件判断，请使用if。
- 不允许使用表达式，
- 不允许创建本地的作用域，
- 不允许在UI描述里直接使用console.info，但允许在方法或者函数里使用，
- 不允许声明本地变量
@Entry：@Entry装饰的自定义组件将作为UI页面的入口。在单个UI页面中，最多可以使用@Entry装饰一个自定义组件。@Entry可以接受一个可选的LocalStorage的参数。
@Entry装饰的自定义组件，其build()函数下的根节点唯一且必要，且必须为容器组件，其中ForEach禁止作为根节点。
@Component装饰的自定义组件，其build()函数下的根节点唯一且必要，可以为非容器组件，其中ForEach禁止作为根节点。

要求

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

自定义组件的成员变量为私有的，且不建议声明成静态变量。
自定义组件的成员变量本地初始化有些是可选的，有些是必选的。具体是否需要本地初始化，是否需要从父组件通过参数传递初始化子组件的成员变量，请参考状态管理。

生命周期

应用冷启动的初始化流程为：MyComponent aboutToAppear --> MyComponent build --> Child aboutToAppear --> Child build --> Child build执行完毕 --> MyComponent build执行完毕 --> Index onPageShow。
如果调用的是router.replaceUrl，则当前Index页面被销毁，执行的生命周期流程将变为：Index onPageHide --> MyComponent aboutToDisappear --> Child aboutToDisappear。上文已经提到，组件的销毁是从组件树上直接摘下子树，所以先调用父组件的aboutToDisappear，再调用子组件的aboutToDisappear，然后执行初始化新页面的生命周期流程。

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

按引用传递参数

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

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

按值传递参数

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

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

2.3. @BuilderParam装饰器：引用父组件的@Builder函数

// 无参数类型，指向的componentBuilder也是无参数类型
@BuilderParam customBuilderParam: () => void;
// 有参数类型，指向的GlobalBuilder1也是有参数类型的方法
@BuilderParam customOverBuilderParam: ($$ : { label : string}) => void;
开发者可以将尾随闭包内的内容看做@Builder装饰的函数传给@BuilderParam。示例如下：

// xxx.ets
@Component
struct CustomContainer {
  @Prop header: string;
  // 使用父组件的尾随闭包{}(@Builder装饰的方法)初始化子组件@BuilderParam
  @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';
        })
      }
    }
  }
}

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

@Styles方法不支持参数，反例如下。

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

和@Styles不同，@Extend仅支持定义在全局，不支持在组件内部定义。
和@Styles不同，@Extend支持封装指定的组件的私有属性和私有事件和预定义相同组件的@Extend的方法。
和@Styles不同，@Extend装饰的方法支持参数，开发者可以在调用时传递参数，调用遵循TS方法传值调用。
@Extend装饰的方法的参数可以为function，作为Event事件的句柄。
@Extend的参数可以为状态变量，当状态变量改变时，UI可以正常的被刷新渲染。

使用案例

@Extend(Text) function fancyText(weightValue: number, color: Color) {
  .fontStyle(FontStyle.Italic)
  .fontWeight(weightValue)
  .backgroundColor(color)
}

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

  build() {
    Row({ space: 10 }) {
      Text(`${this.label}`)
        .fancyText(100, Color.Blue)
      Text(`${this.label}`)
        .fancyText(200, Color.Pink)
      Text(`${this.label}`)
        .fancyText(300, Color.Orange)
    }.margin('20%')
  }
}

2.6. stateStyles：多态样式

类似于css伪类，但语法不同。ArkUI提供以下四种状态：

focused：获焦态。
normal：正常态。
pressed：按压态。
disabled：不可用态。

3.状态管理

3.1. 组件内的通信

有问题的

Assigning the '@State' decorated attribute 'message' to the '@State' decorated attribute 'message' is not allowed.
@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的实例，应用于观察多层嵌套场景，和父组件的数据源构建双向同步。

3.1.1. @State装饰器：组件内状态

特点：

@State装饰的变量与子组件中的@Prop装饰变量之间建立单向数据同步，与@Link、@ObjectLink装饰变量之间建立双向数据同步。
@State装饰的变量生命周期与其所属自定义组件的生命周期相同。

3.1.2. @Prop装饰器：父子单向同步

特点

@Prop装饰的变量可以和父组件建立单向的同步关系。@Prop装饰的变量是可变的，但是变化不会同步回其父组件。
@Prop装饰器不能在@Entry装饰的自定义组件中使用。

3.1.2.1. 父组件@State到子组件@Prop简单数据类型同步,

-  以下示例是@State到子组件@Prop简单数据同步，父组件ParentComponent的状态变量countDownStartValue初始化子组件CountDownComponent中@Prop装饰的count，点击“Try again”，count的修改仅保留在CountDownComponent，不会同步给父组件ParentComponent。

struct CountDownComponent {
  @Prop count: number;
  costOfOneAttempt: number = 1;

  build() {
    Column() {
      if (this.count > 0) {
        Text(`You have ${this.count} Nuggets left`)
      } else {
        Text('Game over!')
      }
      // @Prop装饰的变量不会同步给父组件
      Button(`Try again`).onClick(() => {
        this.count -= this.costOfOneAttempt;
      })
    }
  }
}

@Entry
@Component
struct ParentComponent {
  @State countDownStartValue: number = 10;

  build() {
    Column() {
      Text(`Grant ${this.countDownStartValue} nuggets to play.`)
      // 父组件的数据源的修改会同步给子组件
      Button(`+1 - Nuggets in New Game`).onClick(() => {
        this.countDownStartValue += 1;
      })
      // 父组件的修改会同步给子组件
      Button(`-1  - Nuggets in New Game`).onClick(() => {
        this.countDownStartValue -= 1;
      })

      CountDownComponent({ count: this.countDownStartValue, costOfOneAttempt: 2 })
    }
  }
}

3.1.2.2 父组件@State数组项到子组件@Prop简单数据类型同步

struct Child {
  @Prop value: number;

  build() {
    Text(`${this.value}`)
      .fontSize(50)
      .onClick(()=>{this.value++})
  }
}

@Entry
@Component
struct Index {
  @State arr: number[] = [1,2,3];

  build() {
    Row() {
      Column() {
        Child({value: this.arr[0]})
        Child({value: this.arr[1]})
        Child({value: this.arr[2]})

        Divider().height(5)

        ForEach(this.arr, 
          item => {
            Child({'value': item} as Record<string, number>)
          }, 
          item => item.toString()
        )
        Text('replace entire arr')
        .fontSize(50)
        .onClick(()=>{
          // 两个数组都包含项“3”。
          this.arr = this.arr[0] == 1 ? [10,4,1] : [6,7,8,9];
        })
      }
    }
  }
}

this.arr的更改触发ForEach更新，this.arr更新的前后都有数值为3的数组项：[3, 4, 5] 和[1, 2, 3]。根据diff算法，数组项“3”将被保留，删除“1”和“2”的数组项，添加为“4”和“5”的数组项。这就意味着，数组项“3”的组件不会重新生成，而是将其移动到第一位。所以“3”对应的组件不会更新，此时“3”对应的组件数值为“7”，ForEach最终的渲染结果是“7”，“4”，“5”。

*forEach 在更新渲染的时候，需要比较如果更新前后有相同的数组项，则该数组项不被更新，保留被数组项对应的数组值，就是说如果更新前的数组和更新后的数组有一个相同，那么就把更后的数组值保留到对应的相同数组项的位置。

更新前

更新后

3.1.2.3. 从父组件中的@State类对象属性到@Prop简单类型的同步

可以构建不同的对象实例进行数据初始化

3.1.3. @Link装饰器：父子双向同步

@Link装饰器不能在@Entry装饰的自定义组件中使用。可以实现父子数据对象的依赖

3.1.4. @Provide装饰器和@Consume装饰器：与后代组件双向同步

-- @Provide和@Consume可以通过相同的变量名或者相同的变量别名绑定，变量类型必须相同。

-- @Consume("reviewVotes") reviewVotes2: number;

-- 别名：常量字符串，可选。如果提供了别名，则必须有@Provide的变量和其有相同的别名才可以匹配成功；否则，则需要变量名相同才能匹配成功。

3.1.5. @Observed装饰器和@ObjectLink装饰器：嵌套类对象属性变化

对于多层嵌套的情况，比如二维数组，或者数组项class，或者class的属性是class，使用这俩个来观察引用的地方用# @ObjectLink修饰，定义的地方@Observed修饰

3.2. 应用内的通信

概述

多个页面的状态数据共享，就需要用到应用级别的状态管理的概念。ArkTS根据不同特性，提供了多种应用状态管理的能力：

3.2.1. LocalStorage：页面级UI状态存储

LocalStorage创建后，命名属性的类型不可更改。后续调用Set时必须使用相同类型的值。
@LocalStorageProp：@LocalStorageProp装饰的变量和与LocalStorage中给定属性建立单向同步关系。
@LocalStorageLink：@LocalStorageLink装饰的变量和在@Component中创建与LocalStorage中给定属性建立双向同步关系。

实现方案

1、在入口配置文件EntryAbility.ts中设置localStorage对象

  para:Record<string, number> = { 'PropA': 47 };
  storage: LocalStorage = new LocalStorage(this.para);

2、在EntryAbility.ts的onWindowStageCreate方法中引入store对象

onWindowStageCreate(windowStage: window.WindowStage) {
windowStage.loadContent('pages/Index', this.storage);
}

3、在使用的UIAbility组件中进行引入使用

通过getShared接口获取stage共享的LocalStorage实例
let storage = LocalStorage.GetShared() 4、

3.2.2. AppStorage：应用全局的UI状态存储

@StorageProp(key)是和AppStorage中key对应的属性建立单向数据同步，我们允许本地改变的发生，但是对于@StorageProp，本地的修改永远不会同步回AppStorage中，相反，如果AppStorage给定key的属性发生改变，改变会被同步给@StorageProp，并覆盖掉本地的修改。

3.2.3. PersistentStorage：持久化存储UI状态

PersistentStorage是应用程序中的可选单例对象。此对象的作用是持久化存储选定的AppStorage属性，以确保这些属性在应用程序重新启动时的值与应用程序关闭时的值相同。

3.2.4. Environment：设备环境查询

获取系统参数

3.2.5. @Watch用于监听状态变量的变化。

监听数据变化

3.2.6.$$运算符：给内置组件提供TS变量的引用，使得TS变量和内置组件的内部状态保持同步。

实现地址引用

鸿蒙学习路线图-ArkTS语言基础状态管理