lazy_foreach_array_source_helper.md · ArkUI Finland/public-reports

# LazyForEachArraySource: Authoring simplification for use of LazyForEach with Array data source.

# Summary

This document presents a solution that has the goal to reduce the amount of app source code a developer needs to write when using LazyForEach 
with a data source of type Array<T>.

An application may use `LazyForEach` with a `@State`/`@Link` decorated variable of type Array like this:

```TypeScript

@Component struct AComponent {

@State chatListData: Array<ChatData> = [ ... ];
    
    build() {
      ...
      LazyForEach(this.chatListData, 
         msg => {
             ListItem() {
            ChatView({ chatItem: msg })
      }
      ...
    }
    
    ...
}

```

`@State`/`@Link` decorated Array is normally wrapped inside `ObservedPropertyObject`, that now creates a new `SubscribableArrayHandler` to track changes to the Array.

An application can not use the this method if the data source is not an Array. In the very rare case it is not, the app has to use LazyForEach as before. The existing method requires the developer to write a lot of boiler plate code.

Further steps:
We see possibilities to extend the solution
* to detect changes to the ForEach data source, and to feed similar change events to ForEach update process
* to optimise LazyForEach framework implementation to work more efficiently with the batch array changes caused by splice and other Array functions, e.g. add or remove LayzForEach child UINodes at once.

# Analysis how developers use LazyForEach today

The following example is from the AppSamples Chat application source code. The patter is always the same: The application must implement a class (or a hierarchy of two classes, as done here) that 
* implements the `IDataSource` interface, to subscribe / unsubscribe `DataChangeListener`, and to 
send `onDataAdd`, `onDataDeleted`, `onDataChanged`, `onDataMoved`, and `onDataReloaded` events
to these listeners about data items being added, deleted, modified, index position changed, or the entire dataset
updated respectively. 
* gives access to the data with functions `getTotalCount()` and `getData()`.

This is a lot of repetitive code the developer needs to write.
Looking OHOS sample and system apps it is also clear that in most 
cases the actual data source is an TS Array<T>. We even argue that
LazyforEach works with little more than Array sources in real world
usage. That is because the IDataSource _synchronous_ `getData` and `totalCount`
methods are unsuitable for data sources such as cloud APIs or databases.

The repetitive code developer needs to write is always like the following:

```TypeScript
export abstract class BasicDataSource implements IDataSource {

private listeners: DataChangeListener[] = [];

public abstract totalCount();

// subclass overwrites
  public getData(index: number): any {
    return undefined
  }

registerDataChangeListener(listener: DataChangeListener): void {
    this.listeners = Set()
    this.listeners.add(listener)
  }

unregisterDataChangeListener(listener: DataChangeListener): void {
    const pos = this.listeners.indexOf(listener)
    if (pos >= 0) {
      this.listeners.splice(pos, 1)
    }
  }
  
class ChatListData extends BasicDataSource {

// array data source
  private chatList: Array<ChatModel> = []

public totalCount(): number {
    return this.chatList.length
  }

public getData(index: number): any {
    return this.chatList[index]
  }

public addData(index: number, data: ChatModel): void {
    this.chatList.splice(index, 0, data)
    this.notifyDataAdd(index)
  }

public pushData(data: ChatModel): void {
    this.chatList.push(data)
    this.notifyDataAdd(this.chatList.length - 1)
  }
}

@Component struct LazyforEachUsingComponent {

private chatListData = new ChatListData();

build() {
      ...
      LazyForEach(this.chatListData, (msg: ChatModel) => {
        ListItem() {
        ChatView({ chatItem: msg })
      }
      ...
    }
}
```

# Outline of the `LazyForEach` helper solution

the implementation can be viewed in a draft PR (the PR still needs some refinement before code review) at https://gitee.com/openharmony/arkui_ace_engine/pulls/5039 .

Even before creating a `@State` decorated Array has been transpiled to an `ObservedPropertyObject`:
```typescript
    @State arr: number[] = [1, 2, 3];

// Transpiled
    /* @State arr: number[]=  [1, 2, 3]; */
    private __arr: ObservedPropertyObject<number[]> = new ObservedPropertyObject<number[]>([1, 2, 3], /* owning View*/ this, /* propName */ "arr");
    private get arr(): number[] {
        return this.__arr.get();
    }
    private set arr(newValue: number[]) {
        this.__arr.set(newValue);
    }
```

Our solution adds a new handler for Array type of objects for ObservedPropretyObject to use. The new handler is called `SubscribableArrayHandler` and it derives from the existing `SubscribableHandler`, now renamed to `SubscribableObjectHandler`.

`SubscribableArrayHandler` does several things:
* It acts as a `IDataSource` towards the `LazyForEach`, meaning it intercepts all operations modifying the Array and sends corresponding `onDataChanged`, `onDataMoved`, `onDataDeleted` etc events to the registered `LazyForEach`es. 
* It implements `IDataSource` interface methods `totalCount`, `getData`, `registerDataChangeListener`, `unregisterDataChangeListener` that LazyForEach implementation uses.
* It monitors the Array's read and write access and sends corresponding notifications to the registered listeners.

## Array Proxy

`ObservedObject` extends from ES6 Proxy.

ES6 Proxy provides the essential functionality. ES6 Proxy is created from two inputs: a handler and an Object (in this case the array)
to be proxied. Its `SubscribableArrayHandler` handler implements the `set` and `get` traps:

The `set` trap serves just one purpose, to catch array access of the form `arr[Symbol] = newValue`;

All the array modifications using functions like `Array.splice` require a but more sophistication, they use the `get` trap.
When JS executes a call of the form `arr.splice(...)` the `get` trap will be called to return the property `splice`. 
It returns a function that implements `splice`.

This is the solution: `get` returns a custom function that does few things:
1. applies the `splice` function and parameters on the source array and return possible return values
2. analyses the parameters of splice, and thereby to deduce info what array items will be modified, added, and deleted. This will generate the `onDataChanged`, `onDataAdded`, `onDataDeleted` events.
3. notifies the subscribed `@State` change listeners.

## How to use it

If you have existing code that uses `LazyForEach` and a data source that implements `IDataSource`, you can keep using it as before. If you want to take `LazyForEach` helper and its benefits into use, you should modify your code and put your data inside a `@State` or `@Link`decorated variable Array. Custom data source implementations can be deleted.

## How does it work

This section is mean for developers, and might be incomplete and/or outdated.

The rough idea is that for now on `LazyForEach` accepts an `IDataSource` or `Array<any>` as a data source. The Array must be a decorated variable, so that the framework can keep track of its changes. Decorated Array is wrapped in an `ObservedPropertyObject` that acts as a proxy. The proxied array lets all non-modifying operations of Array API go through without intervening. Operations that modify the Array are caught in the `get` trap, where the operation is first performed and then all needed events are generated for the framework. Note that event's are send _after_ the operation is finished because the handling of the events is synchronous on the framework side.

The intervening handler functions use an inner constant to determine if `onDataReloaded` event should be sent instead of a bunch of other events. Currently it is set to be `0.5`, so if at least half of the items in the Array are modified, `onDataReloaded` is sent. The constant can be configured in  `state_mgmt/src/lib/common/subscribable_array_handler.ts`.

ArkUI Finland/public-reports

简介

发行版

贡献者

近期动态

ArkUI Finland/public-reports .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

ArkUI Finland/public-reports