Utils

Utils provides convenient utilities covering a broad range of common helpers used in projects from light JavaScript utilities to iOS and Android specific properties and methods.

Using Utils ​

Validating a path for a resource or a local file ​

To verify if a path is valid resource or local file path, use the isFileOrResourcePath() method:

constisPathValid:boolean= Utils.isFileOrResourcePath(
'https://nativescript.org/',
) // false

// or

constisPathValid:boolean= Utils.isFileOrResourcePath('res://icon') // true

Check if a URI is a data URI ​

To check if a specific URI is a valid data URI, use the isDataURI() method.

constisDataURI:boolean= Utils.isDataURI(`data:image/png;base64,iVBORw0KGgoAAA
 ANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4
 //8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU
 5ErkJggg==`) // true

// or
constisDataURI:boolean= Utils.isDataURI(`base64,iVBORw0KGgoAAA
 ANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4
 //8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU
 5ErkJggg==`) // false

Opening a url ​

The openUrl() method allows you to open a url and returns true if a browser tab with the specified url opened successfully or false otherwise.

constdidUrlOpen:boolean= Utils.openUrl('https://nativescript.org/')

Escaping regex symbols ​

To escape regex metacharacters in string, use the escapeRegexSymbols() method.

constescapedString:string= Utils.escapeRegexSymbols('$hello') // \$hello

Check if the application is running on a physical device ​

constisOnPhysicalDevice:boolean= Utils.isRealDevice()

Checking if a value is a number ​

To check if a value is a number, use the isNumber() method.

constisANumber:boolean= Utils.isNumber(2) // true
constisNumber:boolean= Utils.isNumber('test') // false
constisNumber:boolean= Utils.isNumber(true) // false

Get a class hierarchy of an object ​

To list all the classes an object is an instance of, use the getBaseClasses() method:

constlabelHierarchy:Array<string> = Utils.getBaseClasses(newLabel())
/* [
 Label,
 TextBase,
 TextBaseCommon,
 View,
 ViewCommon,
 ViewBase,
 Observable,
 Object,
] */

Hiding a keyboard ​

To hide a soft keyboard on the screen, use the dismissKeyboard() method.

Utils.dismissKeyboard()

Utils API ​

MajorVersion ​

constmajorVersion:number= Utils.ios

(iOS only) Gets the iOS device major version. For example, for 16.0 ,it returns 16.

isFileOrResourcePath() ​

constisFileOrResourcePath:boolean= Utils.isFileOrResourcePath(path)

Returns true if the specified path points to a resource or local file.

isDataURI() ​

constisDataURI:boolean= Utils.isDataURI(uri)

openUrl() ​

constisUrlOpened:boolean= Utils.openUrl(url)

Opens the passed url using the default application.

escapeRegexSymbols() ​

constescapedString:string= Utils.escapeRegexSymbols(string)

Escapes special regex characters (., *, ^, $ and so on) in a string and returns a valid regex.

convertString() ​

consttoStr:number|boolean= Utils.convertString(value)

Converts a string value to a number or boolean. If it can not convert, it returns the passed string.

GC() ​

Utils.GC()

A utility function that invokes garbage collection on the JavaScript side.

queueMacrotask() ​

Utils.queueMacrotask(task: () =>void)

Queues the passed function to be ran as a macroTask.

queueGC() ​

Utils.queueGC(delay, useThrottle)

• Optional: delay time, in milliseconds, to wait before garbage collection starts.
• Optional: useThrottle If set to true throttling is used instead of default debounce strategy.

A utility function that queues a garbage collection. Multiple calls in quick succession are debounced by default and only one gc will be executed after 900ms.

debounce() ​

constdebouncedFn= Utils.debounce(fn, delay)

debouncedFn()

A simple debounce utility.

• fn The function to debounce.
• Optional:delay delays the bouncing, in milliseconds. Defaults to 300ms.

throttle() ​

constthrottledFn= Utils.throttle(fn, delay)

throttledFn()

A simple throttle utility.

• fn The function to throttle.
• Optional:delay delays the throttling, in milliseconds. Defaults to 300ms.

isFontIconURI() ​

constisFontIconURI:boolean= Utils.isFontIconURI('font://')

Returns true if the specified URI is a font icon URI.

executeOnMainThread() ​

Utils.executeOnMainThread(fn: Function)

Checks if the current thread is the main thread. If it is, calls the passed function. Otherwise, it dispatches it to the main thread.

executeOnUIThread() ​

Utils.executeOnUIThread(fn: Function)

Runs the passed function on the UI Thread.

mainThreadify() ​

Utils.mainThreadify(fn: Function): (...args:any[])

Returns a function wrapper which executes the supplied function on the main thread. The wrapper behaves like the original function and passes all of its arguments BUT discards its return value.

isMainThread() ​

constisMainThread:boolean= Utils.isMainThread()

Boolean value indicating whether the current thread is the main thread.

dispatchToMainThread() ​

Utils.dispatchToMainThread(fn: Function)

Dispatches the passed function for execution on the main thread.

releaseNativeObject() ​

Utils.releaseNativeObject(object: java.lang.Object | NSObject)

Releases the reference to the wrapped native object.

getModuleName() ​

constmoduleName:string= Utils.getModuleName(path: string)

Gets module name from the specified path.

openFile() ​

constdidFileOpen:boolean= Utils.openFile(filePath, title)

Opens the file at the specified filePath. Optional: (Android-only) title is the title of the file viewer.

isRealDevice() ​

constisOnPhysicalDevice:boolean= Utils.isRealDevice()

Checks whether the application is running on a physical device and not on a simulator/emulator.

getClass() ​

constobjectClass:string= Utils.getClass(object)

Gets the class name of an object.

getBaseClasses() ​

constobjectParentClasses:Array<string> = Utils.getBaseClasses(object)

Returns an entire class inheritance hierarchy for the specified object.

getClassInfo() ​

constobjectClassInfo:ClassInfo= Utils.getClassInfo(object)

Gets the ClassInfo for an object. ClassInfo object has the following properties:

• _name: The name of the class of the object.

isBoolean() ​

constisValueBoolean:boolean= Utils.isBoolean(someValue)

Checks if the specified value is a valid boolean.

isDefined() ​

constisValueDefined:boolean= Utils.isDefined(someValue)

Checks if the specified value is not undefined.

isUndefined() ​

constisUndefined:boolean= Utils.isUndefined(someValue)

Checks if a value is undefined.

isNullOrUndefined() ​

constisNullOrUndefined:boolean= Utils.isNullOrUndefined(someValue)

Checks if a value is null or undefined.

isFunction() ​

constisValueAFunction:boolean= Utils.isFunction(someValue)

Checks if a value is a function.

isNumber() ​

constisNumber:boolean= Utils.isNumber(someValue)

Checks if a value is a valid number.

isObject() ​

constisObject:boolean= Utils.isObject(someValue)

Returns true if a value is an object or array.

isString() ​

constisString= (boolean = Utils.isString(someValue))

Checks if a value is a string.

toUIString() ​

conststringified:string= Utils.toUIString(object)

Returns a string representation of an object to be shown in UI.

dataSerialize() ​

constserializedData= Utils.dataSerialize(data, wrapPrimitives)

Data serialization from JS > Native.

• Optional: data is the JavaScript data to serialize.
• Optional: wrapPrimitives is a boolean parameter indicating whether to wrap primitive data types.

dataDeserialize() ​

constdataDeserialized= Utils.dataDeserialize(nativeData)

Data deserialization from Native to JS.

• Optional nativeData data to be deserialized.

setInterval() ​

consttimerID:number= Utils.setInterval((args) => {}, milliseconds, [
 arg1,
 arg2,
])

A timer method that allows you to run callback every milliseconds(milliseconds). It returns an id that is used to stop the timer.

clearInterval() ​

Utils.clearInterval(timerID)

Stops the interval timer of the provided id.

setTimeout() ​

consttimerId:number= Utils.setTimeout((args) => {}, milliseconds, [
 arg1,
 arg2,
])

A timer method that allows you to wait milliseconds(milliseconds) before running the callback. It returns an id to be used to stop the timer.

dismissKeyboard() ​

Utils.dismissKeyboard()

Hides any keyboard on the screen.

getApplication() ​

constapp:android.app.Application= Utils.android.getApplication()

(Android-only)Gets the native Android application instance. Also see native app.

getApplicationContext() ​

Utils.android.getApplicationContext()

(Android-only) Gets the Android application context.

getInputMethodManager() ​

constinputMethodManager:android.view.inputmethod.InputMethodManager=
 Utils.android.getInputMethodManager()

(Android-only)Gets the native Android InputMethodManager instance.

showSoftInput() ​

Utils.android.showSoftInput(nativeView)

(Android-only)Shows a soft keyboard. nativeView is an android.view.View instance to disable the soft input for.

stringArrayToStringSet() ​

conststringSet:java.util.HashSet= Utils.android.collections.stringArrayToStringSet(str: string[])

Converts string array into a String hash set.

stringSetToStringArray() ​

conststringArray:string[] =
 Utils.android.collections.stringSetToStringArray(stringSet)

Converts string hash set into array of strings.

getDrawableId() ​

constdrawableId:number= Utils.android.resources.getDrawableId(resourceName)

Gets the drawable id from a given resource name.

getStringId() ​

conststringId:number= Utils.android.resources.getStringId(resourceName)

Gets the string id from a given resource name.

getPaletteColor() ​

constpaletteColor:number= Utils.android.resources.getPaletteColor(
 resourceName,
 Utils.android.getApplicationContext(),
)

Gets a color from the current theme.

joinPaths() ​

constjoinedPath:string= Utils.ios.joinPaths('photos', 'cat.png')

Joins the passed strings into a path.

getWindow() ​

constwindow:UIWindow= Utils.ios.getWindow()

Gets the UIWindow of the app.

copyToClipboard() ​

Utils.copyToClipboard(value):

Copies the specified value to device clipboard.

setWindowBackgroundColor() ​

Utils.ios.setWindowBackgroundColor(someColorString)

Sets the window background color of base view of the app. Often this is shown when opening a modal as the view underneath scales down revealing the window color.

getCurrentAppPath() ​

constappPath:string= Utils.ios.getCurrentAppPath()

Gets the root folder for the current application. Also see currentApp()

getVisibleViewController() ​

constvisibleView:UIViewController= Utils.ios.getVisibleViewController(rootViewController: UIViewController)

Gets the currently visible(topmost) UIViewController.rootViewController is the root UIViewController instance to start searching from (normally window.rootViewController).

getRootViewController() ​

constrootView:UIViewController= Utils.ios.getRootViewController()

Gets the root UIViewController of the app.

getShadowLayer() ​

constshadowLayer:CALayer= Utils.ios.getShadowLayer(nativeView, name, create)

• nativeView is a UIView instance to find shadow layer with
• Optional: name(string) is the name of the shadow layer if looking for a specific layer.
• Optional: create(boolean) if set to true, it indicates that a new layer should be created if no layer is found.

createUIDocumentInteractionControllerDelegate() ​

Create a UIDocumentInteractionControllerDelegate implementation for use with UIDocumentInteractionController

jsArrayToNSArray() ​

constjsArrayToNSArray:NSArray<T> =Utils.ios.collections.jsArrayToNSArray<T>(str: T[])

(iOS only)Converts JavaScript array with elements of type T to NSArray of type T.

nsArrayToJSArray() ​

constnsArrayToJSArray:Array<T> =nsArrayToJSArray<T>(a: NSArray<T>)

(iOS only)Converts NSArray of elements of a type T to an equivalent JavaScript array.

API Reference(s) ​

• @nativescript/core/utils module

Contributors