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:

const isPathValid: boolean = Utils.isFileOrResourcePath(
  'https://nativescript.org/'
) //  false

// or

const isPathValid: 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.

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

// or
const isDataURI: 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.

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

Escaping regex symbols ​

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

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

Check if the application is running on a physical device ​

const isOnPhysicalDevice: boolean = Utils.isRealDevice()

Checking if a value is a number ​

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

const isANumber: boolean = Utils.isNumber(2) // true
const isNumber: boolean = Utils.isNumber('test') // false
const isNumber: 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:

const labelHierarchy: Array<string> = Utils.getBaseClasses(new Label())
/* [
  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 ​

const majorVersion: number = Utils.ios

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

isFileOrResourcePath() ​

const isFileOrResourcePath: boolean = Utils.isFileOrResourcePath(path)

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

isDataURI() ​

const isDataURI: boolean = Utils.isDataURI(uri)

openUrl() ​

const isUrlOpened: boolean = Utils.openUrl(url)

Opens the passed url using the default application.

escapeRegexSymbols() ​

const escapedString: string = Utils.escapeRegexSymbols(string)

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

convertString() ​

const toStr: 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() ​

const debouncedFn = 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() ​

const throttledFn = 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() ​

const isFontIconURI: 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() ​

const isMainThread: 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() ​

const moduleName: string = Utils.getModuleName(path: string)

Gets module name from the specified path.

openFile() ​

const didFileOpen: boolean = Utils.openFile(filePath, title)

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

isRealDevice() ​

const isOnPhysicalDevice: boolean = Utils.isRealDevice()

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

getClass() ​

const objectClass: string = Utils.getClass(object)

Gets the class name of an object.

getBaseClasses() ​

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

Returns an entire class inheritance hierarchy for the specified object.

getClassInfo() ​

const objectClassInfo: 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() ​

const isValueBoolean: boolean = Utils.isBoolean(someValue)

Checks if the specified value is a valid boolean.

isDefined() ​

const isValueDefined: boolean = Utils.isDefined(someValue)

Checks if the specified value is not undefined.

isUndefined() ​

const isUndefined: boolean = Utils.isUndefined(someValue)

Checks if a value is undefined.

isNullOrUndefined() ​

const isNullOrUndefined: boolean = Utils.isNullOrUndefined(someValue)

Checks if a value is null or undefined.

isFunction() ​

const isValueAFunction: boolean = Utils.isFunction(someValue)

Checks if a value is a function.

isNumber() ​

const isNumber: boolean = Utils.isNumber(someValue)

Checks if a value is a valid number.

isObject() ​

const isObject: boolean = Utils.isObject(someValue)

Returns true if a value is an object or array.

isString() ​

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

Checks if a value is a string.

toUIString() ​

const stringified: string = Utils.toUIString(object)

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

dataSerialize() ​

const serializedData = 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() ​

const dataDeserialized = Utils.dataDeserialize(nativeData)

Data deserialization from Native to JS.

• Optional nativeData data to be deserialized.

setInterval() ​

const timerID: 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() ​

const timerId: 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() ​

const app: 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() ​

const inputMethodManager: 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() ​

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

Converts string array into a String hash set.

stringSetToStringArray() ​

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

Converts string hash set into array of strings.

getDrawableId() ​

const drawableId: number = Utils.android.resources.getDrawableId(resourceName)

Gets the drawable id from a given resource name.

getStringId() ​

const stringId: number = Utils.android.resources.getStringId(resourceName)

Gets the string id from a given resource name.

getPaletteColor() ​

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

Gets a color from the current theme.

joinPaths() ​

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

Joins the passed strings into a path.

getWindow() ​

const window: 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() ​

const appPath: string = Utils.ios.getCurrentAppPath()

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

getVisibleViewController() ​

const visibleView: 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() ​

const rootView: UIViewController = Utils.ios.getRootViewController()

Gets the root UIViewController of the app.

getShadowLayer() ​

const shadowLayer: 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() ​

const jsArrayToNSArray : 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() ​

const nsArrayToJSArray: 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