ObservableArray

The ObservableArray class expands the Javascript Array class by providing a capability of detecting and responding to changes of a collection of objects. The ObservableArray supports the known methods like concat, push, reduce, slice, splice, reverse and many more (full list here).

Creating an ObservableArray

Creating an ObservableArray with different class constructors.

// Create ObservableArray with lenght
let myObservableArray = new ObservableArray(10)

// Create ObservableArray from array.
const arr = [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
myObservableArray = new ObservableArray(arr)

Listening to the ObservableArray.changeEvent

The example in the Stackblitz IDE below shows how to hook to the changeEvent. To try it out, you have to download the Nativescript Preview app from Google Play or App Store. Once you have the app, scan the QR with your phone Camera and the app resulting from the code in the IDE will appear in the Nativescript Preview app.

You can use the IDE and the Preview app to experiment with the rest of the ObservableArray methods.

Array index

One difference between the base array implementation and the ObservableArray is in the way the items are accessed through their index. While in the common JS array we would do array[index], with an ObservableArray we need to use the getItem(index) method.

const firstItem = myObservableArray.getItem(0)
const secondItem = myObservableArray.getItem(1)
const thirdItem = myObservableArray.getItem(2)
console.log(firstItem, secondItem, thirdItem)

Properties

Name Type Description

Name	Type	Description
`changeEvent`	`string`	This is a static property used when hooking to change event.

changeEvent

string

This is a static property used when hooking to change event.

Methods

Name Return Type Description

Name	Return Type	Description
`setItem(index: number, value: T)`	`void`	Sets item at specified index.
`getItem(index: number)`	`T`	Returns item at specified index. `T` represents the type of the element retrieved. For example, if the retrieved value is a number, then `T` is `number` type
`toString()`, `toLocaleString()`	`string`	Returns a string representation of an array.
`concat(...args: any[])`	`T[]`	Combines two or more arrays. + `items`: Additional items to add to the end of array1.
`join(separator?: string)`	`string`	Adds all the elements of an array separated by the specified separator string. + `separator`: A string used to separate one element of an array from the next in the resulting string. If omitted, the array elements are separated with a comma.
`pop()`	`T`	Removes the last element from an array and returns it.
`push(...args: any)`	`number`	Appends new elements to an array and returns the new length of the array. + `item`: New element(s) of the Array.
`reverse()`	`T[]`	Reverses the elements in an Array.
`shift()`	`T`	Removes the first element from an array and returns it.
`slice(start?: number, end?: number)`	`T[]`	Returns a section of an array. + `start`: The beginning of the specified portion of the array. + `end`: The end of the specified portion of the array.
`sort(compareFn?: (a: T, b: T) => number)`	`T[]`	Sorts an array. + `start`: The name of the function used to determine the order of the elements. If omitted, the elements are sorted into ascending, ASCII character order.
`splice(start: number, deleteCount?: number, ...items: any)`	`T[]`	Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements. + + Parameters: + `start`: The zero-based location in the array from which to start removing elements. + `deleteCount`: The number of elements to remove. + `items`: Elements to insert into the array in place of the deleted elements.
`unshift(...args: any)`	`T[]`	Inserts new elements at the start of an array and returns the new length of the array. + + Parameters: + `items`: Elements to insert at the start of the Array.
`findIndex(predicate: (value: any, index: number, obj: any[]) => unknown, thisArg?: any)`	`number`	Returns the index of the first element in the array where predicate is true, and -1 otherwise. + + Parameters: + `predicate`: A function used to test elements in the array. + `thisArg`: If provided, it will be used as the `this` value for each invocation of predicate. If it is not provided, undefined is used instead.
`indexOf(searchElement: T, fromIndex?: number)`	`number`	Returns the index of the first occurrence of a value in an array. + + Parameters: + `searchElement`: The value to locate in the array. + `fromIndex`: The array index at which to begin the search. If fromIndex is omitted, the search starts at index 0.
`lastIndexOf(searchElement: T, fromIndex?: number)`	`number`	Returns the index of the last occurrence of a specified value in an array. + + Parameters: + `searchElement`: The value to locate in the array. + `fromIndex`: The array index at which to begin the search. If fromIndex is omitted, the search starts at the last index in the array.
`every(callbackfn: (value: T, index: number, array: T[]) => boolean, thisArg?: any)`	`boolean`	Determines whether all the members of an array satisfy the specified test. + + Parameters: + `callbackfn`: The `every()` method calls the `callbackfn` function for each element in an array until the `callbackfn` returns false, or until the end of the array. + `thisArg`: An object to which the `this` keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
`some(callbackfn: (value: T, index: number, array: T[]) => boolean, thisArg?: any)`	`boolean`	Determines whether the specified callback function returns true for any element of an array. + + Parameters: + `callbackfn`: The `some()` method calls the `callbackfn` function for each element in array until the `callbackfn` returns true, or until the end of the array. + `thisArg`: An object to which the `this` keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
`forEach(callbackfn: (value: T, index: number, array: T[]) => void, thisArg?: any)`	`void`	Determines whether the specified callback function returns true for any element of an array. + + Parameters: + `callbackfn`: `forEach()` calls the callbackfn function one time for each element in the array. + `thisArg`: An object to which the `this` keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
`map<U>(callbackfn: (value: T, index: number, array: T[]) => U, thisArg?: any)`	`U[]`	Calls the defined callback function on each element of an array and returns an array that contains the results. + + Parameters: + `callbackfn`: The `map()` method calls the callbackfn function one time for each element in the array. + `thisArg`: An object to which the `this` keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
`map<U>(callbackfn: (value: T, index: number, array: T[]) => U, thisArg?: any)`	`U[]`	Returns the elements of an array that meet the condition specified in a callback function. + + Parameters: + `callbackfn`: The `filter()` method calls the callbackfn function one time for each element in the array. + `thisArg`: An object to which the `this` keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
`filter(callbackfn: (value: T, index: number, array: T[]) => boolean, thisArg?: any)`	`T[]`	Returns the elements of an array that meet the condition specified in a callback function. + + Parameters: + `callbackfn`: The `filter()` method calls the callbackfn function one time for each element in the array. + `thisArg`: An object to which the `this` keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
`reduce(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T, initialValue?: T)`	`T`	Calls the specified callback function for all the elements in an array, in descending order. The return value of the callback function is the accumulated result and is provided as an argument in the next call to the callback function. + + Parameters: + `initialValue`: If `initialValue` is specified, it is used as the initial value to start the accumulation. The first call to the `callbackfn` function provides this value as an argument instead of an array value.
`reduceRight(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T, initialValue?: T)`	`T`	Calls the specified callback function for all the elements in an array starting from the end of the array, in descending order. The return value of the callback function is the accumulated result and is provided as an argument in the next call to the callback function. + + Parameters: + `initialValue`: If `initialValue` is specified, it is used as the initial value to start the accumulation. The first call to the `callbackfn` function provides this value as an argument instead of an array value.

setItem(index: number, value: T)

void

Sets item at specified index.

getItem(index: number)

T

Returns item at specified index. T represents the type of the element retrieved. For example, if the retrieved value is a number, then T is number type

toString(), toLocaleString()

string

Returns a string representation of an array.

concat(...args: any[])

T[]

Combines two or more arrays. + items: Additional items to add to the end of array1.

join(separator?: string)

string

Adds all the elements of an array separated by the specified separator string. + separator: A string used to separate one element of an array from the next in the resulting string. If omitted, the array elements are separated with a comma.

pop()

T

Removes the last element from an array and returns it.

push(...args: any)

number

Appends new elements to an array and returns the new length of the array. + item: New element(s) of the Array.

reverse()

T[]

Reverses the elements in an Array.

shift()

T

Removes the first element from an array and returns it.

slice(start?: number, end?: number)

T[]

Returns a section of an array. + start: The beginning of the specified portion of the array. + end: The end of the specified portion of the array.

sort(compareFn?: (a: T, b: T) => number)

T[]

Sorts an array. + start: The name of the function used to determine the order of the elements. If omitted, the elements are sorted into ascending, ASCII character order.

splice(start: number, deleteCount?: number, ...items: any)

T[]

Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements. + + Parameters: + start: The zero-based location in the array from which to start removing elements. + deleteCount: The number of elements to remove. + items: Elements to insert into the array in place of the deleted elements.

unshift(...args: any)

T[]

Inserts new elements at the start of an array and returns the new length of the array. + + Parameters: + items: Elements to insert at the start of the Array.

findIndex(predicate: (value: any, index: number, obj: any[]) => unknown, thisArg?: any)

number

Returns the index of the first element in the array where predicate is true, and -1 otherwise. + + Parameters: + predicate: A function used to test elements in the array. + thisArg: If provided, it will be used as the this value for each invocation of predicate. If it is not provided, undefined is used instead.

indexOf(searchElement: T, fromIndex?: number)

number

Returns the index of the first occurrence of a value in an array. + + Parameters: + searchElement: The value to locate in the array. + fromIndex: The array index at which to begin the search. If fromIndex is omitted, the search starts at index 0.

lastIndexOf(searchElement: T, fromIndex?: number)

number

Returns the index of the last occurrence of a specified value in an array. + + Parameters: + searchElement: The value to locate in the array. + fromIndex: The array index at which to begin the search. If fromIndex is omitted, the search starts at the last index in the array.

every(callbackfn: (value: T, index: number, array: T[]) => boolean, thisArg?: any)

boolean

Determines whether all the members of an array satisfy the specified test. + + Parameters: + callbackfn: The every() method calls the callbackfn function for each element in an array until the callbackfn returns false, or until the end of the array. + thisArg: An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.

some(callbackfn: (value: T, index: number, array: T[]) => boolean, thisArg?: any)

boolean

Determines whether the specified callback function returns true for any element of an array. + + Parameters: + callbackfn: The some() method calls the callbackfn function for each element in array until the callbackfn returns true, or until the end of the array. + thisArg: An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.

forEach(callbackfn: (value: T, index: number, array: T[]) => void, thisArg?: any)

void

Determines whether the specified callback function returns true for any element of an array. + + Parameters: + callbackfn: forEach() calls the callbackfn function one time for each element in the array. + thisArg: An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.

map<U>(callbackfn: (value: T, index: number, array: T[]) => U, thisArg?: any)

U[]

Calls the defined callback function on each element of an array and returns an array that contains the results. + + Parameters: + callbackfn: The map() method calls the callbackfn function one time for each element in the array. + thisArg: An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.

map<U>(callbackfn: (value: T, index: number, array: T[]) => U, thisArg?: any)

U[]

Returns the elements of an array that meet the condition specified in a callback function. + + Parameters: + callbackfn: The filter() method calls the callbackfn function one time for each element in the array. + thisArg: An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.

filter(callbackfn: (value: T, index: number, array: T[]) => boolean, thisArg?: any)

T[]

reduce(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T, initialValue?: T)

T

Calls the specified callback function for all the elements in an array, in descending order. The return value of the callback function is the accumulated result and is provided as an argument in the next call to the callback function. + + Parameters: + initialValue: If initialValue is specified, it is used as the initial value to start the accumulation. The first call to the callbackfn function provides this value as an argument instead of an array value.

reduceRight(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T, initialValue?: T)

T

Calls the specified callback function for all the elements in an array starting from the end of the array, in descending order. The return value of the callback function is the accumulated result and is provided as an argument in the next call to the callback function. + + Parameters: + initialValue: If initialValue is specified, it is used as the initial value to start the accumulation. The first call to the callbackfn function provides this value as an argument instead of an array value.

For more infomation on what the T or U[] types mean, see Generic Types.

API References

Name Type

Name	Type
@nativescript/core/ObservableArray	`Class`

@nativescript/core/ObservableArray

Class