Developers transitioning to HarmonyOS NEXT development often encounter a frustrating scenario: console logs confirm that underlying data has mutated, but the application interface remains entirely static. This is the classic "ArkTS UI not updating" problem.
In most cases, this issue isolates down to how ArkTS state management handles complex data structures. When using the @State decorator on nested objects or arrays of objects, modifications to deep properties fail to trigger the component's build() function. Understanding the precise mechanics of the ArkTS reactivity system is required to architect applications that render predictably.
The Root Cause: Shallow Observation
To understand why the UI fails to update, we must look at how the ArkTS compiler processes the @State decorator under the hood.
When you apply @State to a variable, the framework wraps that variable in a reactive proxy. However, for performance reasons, this proxy is strictly shallow. It intercepts and reacts to two specific types of operations:
- Reassignment of the variable itself (e.g.,
this.myObject = newObject). - Mutations to the immediate, first-level properties of the object (e.g.,
this.myObject.firstLevelProperty = "new value").
If the @State variable is an array containing objects, the proxy observes array structural changes like push(), pop(), or splice(). It does not recursively proxy the objects residing inside the array. When you execute this.tasks[0].isCompleted = true, you are mutating a property of an unobserved nested object. The proxy on the tasks array never detects this inner change, and the rendering engine is never notified to schedule a UI update.
The Fix: Implementing @Observed and @ObjectLink
To resolve deep reactivity issues without resorting to computationally expensive deep-copying or forced reassignments, ArkTS provides a dedicated pattern: combining the @Observed class decorator with the @ObjectLink property decorator.
This pattern requires extracting the nested data into its own class and extracting the UI rendering for that data into a child component.
Step 1: Decorate the Class with @Observed
First, define the data structure using a standard ES6 class. Apply the @Observed decorator to the class definition. This instructs the ArkTS compiler to wrap instances of this class in their own reactive proxies.
@Observed
export class TaskModel {
public id: string;
public title: string;
public isCompleted: boolean;
constructor(id: string, title: string, isCompleted: boolean) {
this.id = id;
this.title = title;
this.isCompleted = isCompleted;
}
}
Step 2: Create a Child Component with @ObjectLink
Next, create a child component responsible for rendering the individual instance of the TaskModel. Instead of using @State or @Prop, bind the incoming instance using @ObjectLink.
@Component
export struct TaskItem {
// @ObjectLink maintains a two-way sync with the @Observed instance
@ObjectLink task: TaskModel;
build() {
Row() {
Text(this.task.title)
.fontSize(16)
.decoration({
type: this.task.isCompleted ? TextDecorationType.LineThrough : TextDecorationType.None
})
.layoutWeight(1)
Toggle({ type: ToggleType.Checkbox, isOn: this.task.isCompleted })
.onChange((isOn: boolean) => {
// This mutation now successfully triggers a re-render in this component
this.task.isCompleted = isOn;
})
}
.width('100%')
.padding(12)
.backgroundColor('#F5F5F5')
.borderRadius(8)
.margin({ bottom: 8 })
}
}
Step 3: Manage the Array in the Parent Component
Finally, maintain the array of @Observed class instances in the parent component using the standard @State decorator. Iterate over the array using ForEach and pass the instances to the child component.
@Entry
@Component
struct TaskListView {
@State tasks: TaskModel[] = [
new TaskModel('1', 'Implement ArkTS state management', false),
new TaskModel('2', 'Test application in DevEco Studio', false),
new TaskModel('3', 'Optimize rendering performance', false)
];
build() {
Column() {
Text('Project Tasks')
.fontSize(24)
.fontWeight(FontWeight.Bold)
.margin({ bottom: 16 })
List() {
ForEach(this.tasks, (item: TaskModel) => {
ListItem() {
// Pass the reference directly to the @ObjectLink property
TaskItem({ task: item })
}
}, (item: TaskModel) => item.id)
}
.width('100%')
}
.padding(20)
.width('100%')
.height('100%')
}
}
Deep Dive: Why This Architecture Works
When dealing with ArkTS state management, separating concerns via @Observed and @ObjectLink is not just a workaround; it is the framework's intended architectural pattern for performance optimization.
By marking TaskModel with @Observed, DevEco Studio's compilation process injects a proxy wrapper around every instantiated object of that class. However, parent components holding an array of these objects still only track the array's surface.
The @ObjectLink decorator acts as the bridge. When passed to the TaskItem child component, @ObjectLink subscribes directly to the proxy wrapper of that specific TaskModel instance. If this.task.isCompleted changes, the proxy notifies the TaskItem component to invalidate and re-render only its specific UI nodes.
This prevents the parent TaskListView from needlessly re-rendering the entire list when only a single item changes. The rendering cost remains localized to the exact component mutating the data.
Common Pitfalls and Edge Cases
Attempting to use @ObjectLink without @Observed
If you attempt to pass an interface or a standard class instance to an @ObjectLink property, the framework will fail to establish the proxy connection. DevEco Studio will typically flag this during compilation. Always ensure the data source is instantiated from a class explicitly marked with @Observed.
Direct Initialization of @ObjectLink
An @ObjectLink variable cannot be initialized locally. Writing @ObjectLink task: TaskModel = new TaskModel(...) is invalid ArkTS syntax. The property must act purely as a receiver for an instance passed down from a parent component.
Reassigning the @ObjectLink Variable
While you can mutate properties inside the @ObjectLink object (e.g., this.task.title = 'New'), you cannot reassign the object itself (e.g., this.task = new TaskModel(...)). The @ObjectLink reference is immutable. If the entire object needs to be replaced, that replacement must occur at the parent level within the @State array.
Overusing @Observed on Static Data
Proxies carry a memory footprint and a slight CPU overhead during instantiation and mutation. Applying @Observed to deeply nested classes that never change at runtime wastes device resources. Only apply these decorators to data structures that actively require reactivity within the UI layer.