8.7 版本发布—WinterCG 兼容性第一部分
了解更多

Utils 提供了便捷的实用程序，涵盖了项目中使用的各种常见帮助器，从轻量级的 JavaScript 实用程序到 iOS 和 Android 特定的属性和方法。

使用 Utils ​

验证资源或本地文件的路径 ​

要验证路径是否为有效的资源或本地文件路径，请使用 isFileOrResourcePath() 方法

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

// or

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

检查 URI 是否为数据 URI ​

要检查特定 URI 是否为有效的数据 URI，请使用 isDataURI() 方法。

ts
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

打开网址 ​

使用 openUrl() 方法可以打开网址，如果成功打开了指定网址的浏览器选项卡，则返回 true，否则返回 false。

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

转义正则表达式符号 ​

要转义字符串中的正则表达式元字符，请使用 escapeRegexSymbols() 方法。

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

检查应用程序是否在物理设备上运行 ​

ts
const isOnPhysicalDevice: boolean = Utils.isRealDevice()

检查值是否为数字 ​

要检查值是否为数字，请使用 isNumber() 方法。

ts
const isANumber: boolean = Utils.isNumber(2) // true
const isNumber: boolean = Utils.isNumber('test') // false
const isNumber: boolean = Utils.isNumber(true) // false

获取对象的类层次结构 ​

要列出对象是其实例的所有类，请使用 getBaseClasses() 方法

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

隐藏键盘 ​

要隐藏屏幕上的软键盘，请使用 dismissKeyboard() 方法。

ts
Utils.dismissKeyboard()

Utils API ​

MajorVersion ​

ts
const majorVersion: number = Utils.ios

(仅限 iOS) 获取 iOS 设备的主版本号。例如，对于 16.0，它返回 16。

isFileOrResourcePath() ​

ts
const isFileOrResourcePath: boolean = Utils.isFileOrResourcePath(path)

如果指定的路径指向资源或本地文件，则返回 true。

isDataURI() ​

ts
const isDataURI: boolean = Utils.isDataURI(uri)

openUrl() ​

ts
const isUrlOpened: boolean = Utils.openUrl(url)

使用默认应用程序打开传递的网址。

escapeRegexSymbols() ​

ts
const escapedString: string = Utils.escapeRegexSymbols(string)

转义字符串中的特殊正则表达式字符 (., *, ^, $ 等)，并返回有效的正则表达式。

convertString() ​

ts
const toStr: number | boolean = Utils.convertString(value)

将字符串值转换为数字或布尔值。如果无法转换，则返回传递的字符串。

GC() ​

ts
Utils.GC()

一个实用程序函数，用于在 JavaScript 端调用垃圾回收。

queueMacrotask() ​

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

将传递的函数排队，作为宏任务运行。

queueGC() ​

ts
Utils.queueGC(delay, useThrottle)
  • 可选：delay 延迟时间（以毫秒为单位），在垃圾回收开始前等待的时间。
  • 可选：useThrottle 如果设置为 true，则使用节流而不是默认的去抖策略。

一个实用程序函数，用于排队垃圾回收。默认情况下，多个快速连续的调用会被去抖动，并且只有在 900 毫秒后才会执行一次垃圾回收。

debounce() ​

ts
const debouncedFn = Utils.debounce(fn, delay)

debouncedFn()

一个简单的去抖动实用程序。

  • fn 要去抖动的函数。
  • 可选：delay 延迟去抖动（以毫秒为单位）。默认为 300 毫秒。

throttle() ​

ts
const throttledFn = Utils.throttle(fn, delay)

throttledFn()

一个简单的节流实用程序。

  • fn 要节流的函数。
  • 可选：delay 延迟节流（以毫秒为单位）。默认为 300 毫秒。

isFontIconURI() ​

ts
const isFontIconURI: boolean = Utils.isFontIconURI('font://&#xf51e;')

如果指定的 URI 是字体图标 URI，则返回 true。

executeOnMainThread() ​

ts
Utils.executeOnMainThread(fn: Function)

检查当前线程是否为主线程。如果是，则调用传递的函数。否则，将其分派到主线程。

重要！

从主线程调用时，这将同步执行，否则将异步执行。

executeOnUIThread() ​

ts
Utils.executeOnUIThread(fn: Function)

在 UI 线程上运行传递的函数。

重要！

始终异步分派到 UI 线程。

mainThreadify() ​

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

返回一个函数包装器，该包装器在主线程上执行提供的函数。包装器与原始函数的行为相同，并传递其所有参数，但会丢弃其返回值。

isMainThread() ​

ts
const isMainThread: boolean = Utils.isMainThread()

布尔值，指示当前线程是否为主线程。

dispatchToMainThread() ​

ts
Utils.dispatchToMainThread(fn: Function)

分派传递的函数，以便在主线程上执行。

releaseNativeObject() ​

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

释放对包装的原生对象的引用。

getModuleName() ​

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

从指定的路径获取模块名称。

openFile() ​

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

打开指定 filePath 处的文件。可选：(仅限 Android) title 是文件查看器的标题。

isRealDevice() ​

ts
const isOnPhysicalDevice: boolean = Utils.isRealDevice()

检查应用程序是否在物理设备上运行，而不是在模拟器/仿真器上运行。

getClass() ​

ts
const objectClass: string = Utils.getClass(object)

获取对象的类名。

getBaseClasses() ​

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

返回指定对象的完整类继承层次结构。

getClassInfo() ​

ts
const objectClassInfo: ClassInfo = Utils.getClassInfo(object)

获取对象的 ClassInfo。ClassInfo 对象具有以下属性

  • _name：对象的类的名称。

isBoolean() ​

ts
const isValueBoolean: boolean = Utils.isBoolean(someValue)

检查指定的值是否为有效的布尔值。

isDefined() ​

ts
const isValueDefined: boolean = Utils.isDefined(someValue)

检查指定的值是否不为 undefined。

isUndefined() ​

ts
const isUndefined: boolean = Utils.isUndefined(someValue)

检查值是否为 undefined。

isNullOrUndefined() ​

ts
const isNullOrUndefined: boolean = Utils.isNullOrUndefined(someValue)

检查值是否为 null 或 undefined。

isFunction() ​

ts
const isValueAFunction: boolean = Utils.isFunction(someValue)

检查值是否为函数。

isNumber() ​

ts
const isNumber: boolean = Utils.isNumber(someValue)

检查值是否为有效的数字。

isObject() ​

ts
const isObject: boolean = Utils.isObject(someValue)

如果值为对象或数组，则返回 true。

isString() ​

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

检查值是否为字符串。

toUIString() ​

ts
const stringified: string = Utils.toUIString(object)

返回对象的字符串表示形式，以便在 UI 中显示。

dataSerialize() ​

ts
const serializedData = Utils.dataSerialize(data, wrapPrimitives)

从 JS 到 Native 的数据序列化。

  • 可选：data 是要序列化的 JavaScript 数据。
  • 可选：wrapPrimitives 是一个 boolean 参数，指示是否包装基本数据类型。

dataDeserialize() ​

ts
const dataDeserialized = Utils.dataDeserialize(nativeData)

将数据从 Native 反序列化到 JS。

  • 可选 nativeData 要反序列化的数据。

setInterval() ​

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

一个定时器方法，允许您每隔 milliseconds（毫秒）运行 callback。它返回一个用于 停止 定时器的 ID。

clearInterval() ​

ts
Utils.clearInterval(timerID)

停止指定 ID 的间隔计时器。

setTimeout() ​

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

一个定时器方法，允许您等待 milliseconds（毫秒），然后运行 callback。它返回一个用于 停止 定时器的 ID。

dismissKeyboard() ​

ts
Utils.dismissKeyboard()

隐藏屏幕上的任何键盘。

getApplication() ​

ts
const app: android.app.Application = Utils.android.getApplication()

（仅限 Android）获取原生 Android 应用程序实例。另请参阅 原生应用。

getApplicationContext() ​

ts
Utils.android.getApplicationContext()

（仅限 Android）获取 Android 应用程序 上下文。

getInputMethodManager() ​

ts
const inputMethodManager: android.view.inputmethod.InputMethodManager =
  Utils.android.getInputMethodManager()

（仅限 Android）获取原生 Android InputMethodManager 实例。

showSoftInput() ​

ts
Utils.android.showSoftInput(nativeView)

（仅限 Android）显示软键盘。nativeView 是一个 android.view.View 实例，用于禁用其软输入。

stringArrayToStringSet() ​

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

将字符串数组转换为 String 哈希集。

stringSetToStringArray() ​

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

将字符串哈希集转换为字符串数组。

getDrawableId() ​

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

根据给定的资源名称获取 drawable ID。

getStringId() ​

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

根据给定的资源名称获取字符串 ID。

getPaletteColor() ​

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

从当前主题获取颜色。

joinPaths() ​

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

将传递的字符串连接成路径。

getWindow() ​

ts
const window: UIWindow = Utils.ios.getWindow()

获取应用程序的 UIWindow。

copyToClipboard() ​

ts
Utils.copyToClipboard(value):

将指定的值复制到设备剪贴板。

setWindowBackgroundColor() ​

ts
Utils.ios.setWindowBackgroundColor(someColorString)

设置应用程序基本视图的窗口背景颜色。通常在打开模态时显示，因为下方的视图会缩小，从而显示窗口颜色。

getCurrentAppPath() ​

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

获取当前应用程序的根文件夹。另请参阅 currentApp()

getVisibleViewController() ​

ts
const visibleView: UIViewController = Utils.ios.getVisibleViewController(rootViewController: UIViewController)

获取当前可见（最顶层）的 UIViewController。rootViewController 是要开始搜索的根 UIViewController 实例（通常是 window.rootViewController）。

getRootViewController() ​

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

获取应用程序的根 UIViewController。

getShadowLayer() ​

ts
const shadowLayer: CALayer = Utils.ios.getShadowLayer(nativeView, name, create)
  • nativeView 是一个 UIView 实例，用于查找其阴影层。
  • 可选：name（string）是阴影层的名称，如果您要查找特定层。
  • 可选：create（boolean）如果设置为 true，则表示如果未找到层，则应创建一个新层。

createUIDocumentInteractionControllerDelegate() ​

创建一个 UIDocumentInteractionControllerDelegate 实现，用于 UIDocumentInteractionController。

jsArrayToNSArray() ​

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

（仅限 iOS）将 JavaScript 数组（元素类型为 T）转换为类型为 T 的 NSArray。

nsArrayToJSArray() ​

ts
const nsArrayToJSArray: Array<T> = nsArrayToJSArray<T>(a: NSArray<T>)

（仅限 iOS）将类型为 T 的 NSArray 元素转换为等效的 JavaScript 数组。

API 参考 ​

上一个
跟踪
下一个
XmlParser