Skip to content

Application ​

Application 表示正在运行的这个 App。它唯一的实例是全局对象 application:运行时在 App 启动时创建它,整个 App 只有这一个,一直存在到 App 结束。脚本的任何位置都可以直接使用,不需要创建,也不能再创建一个。

application 管整个 App 范围内的事:

  • App 的信息:包名、版本、配置文件的内容。
  • App 的状态:在前台还是后台,当前有哪些场景。
  • App 级的事件:可以建界面了、进入后台、内存不足、被一条链接打开、有没处理的异常。
  • App 级的能力:本地存储、文件和网络状态的入口,以及让系统打开一个 URL(往外打开;别的 App 打开本 App 是上一条里的事件)、切到后台时向系统多要一段时间。装了 @nacrejs/keychain 之后,Keychain 的入口也在这里;装了 @nacrejs/push 之后,远程推送的入口也在这里。
  • 原生模块的入口:App 自己的原生代码和第三方原生 SDK 提供的方法,从 application.nativeModules 调。

界面不在 application 上。界面属于场景(UIWindowScene):场景表示 App 界面的一个实例,由系统创建,窗口要建在场景上才能显示。application 负责在场景可用时派发 sceneconnect,并记录当前有哪些场景。

事件相关的几个类也由运行时提供,各有自己的页面:EventTarget(会发事件的对象的基类)、Event(事件对象的基类),以及 application 上三种事件的事件对象 ErrorEvent、PromiseRejectionEvent、OpenURLEvent。

继承关系:EventTarget → Application

怎么组织启动代码、处理前后台和内存警告,见指南处理 App 的生命周期;怎么统一处理错误,见统一处理错误;怎么处理打开 App 的链接,见处理打开 App 的链接。

构造函数 ​

不能用 new 创建。new Application() 抛 TypeError: Illegal constructor。直接用全局的 application。

实例属性 ​

App 的信息。这四个属性在 App 运行期间不变,所以没有变化事件:

属性说明
info 只读Info.plist 的全部内容
bundleIdentifier 只读包名
version 只读给用户看的版本号
build 只读构建号

App 的状态:

属性说明
state 只读所有场景合在一起的前后台状态
scenes 只读当前已接入的场景
supportsMultipleScenes 只读能不能同时有多个场景
protectedDataAvailable 只读加密保护的文件现在能不能读
backgroundTimeRemaining 只读在后台还能运行多少秒。在前台是 Infinity

设备的环境设置:

属性说明
layoutDirection 只读界面的书写方向
contentSizeCategory 只读用户选的字体大小档位
backgroundRefreshStatus 只读App 能不能在后台刷新内容
prefersReducedResourceUsage 只读系统是否建议 App 减少资源消耗
idleTimerDisabled是否阻止设备自动锁屏

各种能力的入口。每次读到的都是同一个对象:

属性说明
storage 只读键值存储
fileSystem 只读文件读写
network 只读网络状态:连没连上、哪种网络、是否按流量计费
keychain 只读令牌和密码的加密存储。只在装了 @nacrejs/keychain 的项目里有
remoteNotifications 只读远程推送:注册、设备令牌、静默推送。只在装了 @nacrejs/push 的项目里有
nativeModules 只读登记进这个 App 的原生模块

实例方法 ​

还继承 EventTarget 的 addEventListener()、removeEventListener()、dispatchEvent()。

方法说明
openURL()把一个 URL 交给系统打开
runBackgroundTask()运行一个函数,期间切到后台也向系统多要一段时间把它做完

事件 ​

事件名全部小写,没有分隔符。

场景:

事件什么时候派发
sceneconnect系统创建好了一个场景。界面代码写在这里
scenedisconnect系统销毁了一个场景

链接:

事件什么时候派发
openurl别的 App 或一条链接打开了本 App

前后台:

事件什么时候派发
inactiveApp 即将离开活动状态
backgroundApp 已经进入后台
foregroundApp 即将回到前台
activeApp 已经进入活动状态
beforeterminate系统即将结束 App

系统通知:

事件什么时候派发
memorywarning系统内存不足,App 应该释放缓存
screenshot用户截了屏
significanttimechange时间发生大的变化:过了午夜、时区变了、夏令时切换
contentsizecategorychange用户改了系统字体大小
localechange用户改了地区设置:国家或地区、货币、数字和日期的格式
protecteddataavailable设备解锁,加密保护的文件可以读了
protecteddataunavailable设备即将锁屏,加密保护的文件将读不了
backgroundrefreshstatuschange用户改了后台刷新的设置
reducedresourceusagechange系统对资源消耗的建议变了

错误:

事件什么时候派发
error有没被捕获的异常
unhandledrejection有被拒绝、却没有挂处理函数的 Promise

application 也可以监听和派发自己定义的事件,事件名可以是任意字符串,只要不和上面的相同。

场景 ​

拿到场景有两个途径:

途径什么时候有值
sceneconnect 事件的 e.scene事件派发时
application.scenessceneconnect 派发之后。脚本刚开始执行时是空数组

所以界面代码的入口固定是 sceneconnect。App 启动后,运行时先把整个 main.js 执行完,系统随后才创建场景。场景被销毁时派发 scenedisconnect,这个场景同时从 application.scenes 里移除。

application 和场景的分工:

管什么
application整个 App:信息、所有场景合在一起的前后台状态、内存警告、错误
场景一个界面实例:它的窗口、它自己的前后台状态

前台、后台和运行状态 ​

iOS 的 App 不是一直在运行。用户回到主屏幕或切到别的 App 时,当前 App 进入后台,系统随后可能暂停它,也可能直接结束它。

application.state 有三种正常取值:

取值含义
'active'在前台,并且在接收用户的操作
'inactive'在前台,但暂时不接收操作。例如正在切换 App、来电、下拉了通知中心
'background'不在屏幕上。脚本刚开始执行时也是这个值

状态变化时派发四个事件。其中两个在状态改变之前派发:

事件含义事件到达时 state 的值
inactive即将离开活动状态'active',还是旧值
background已经进入后台'background'
foreground即将回到前台'background',还是旧值
active已经进入活动状态'active'

场景也有同名的四个事件。application 上的是所有场景合在一起的状态,场景上的是那一个场景的状态。两者读到的值在同一时刻可能不同,见 UIWindowScene。

进入后台之后,系统会在一小段时间之后暂停 App。一件已经开始、还要几秒钟才能做完的事(上传、写文件),用 runBackgroundTask() 包起来,系统会多给一段时间让它做完;还剩多少秒从 backgroundTimeRemaining 读。

系统事件不能取消 ​

application 上的事件分两类,区别在于能不能 preventDefault():

类别包括cancelablepreventDefault()
系统通知sceneconnect、openurl、前后台事件、memorywarning 等,除下面两个以外的全部false没有效果,也不报错
错误类事件error、unhandledrejectiontrue阻止运行时输出默认的错误日志

系统通知不能取消,是因为监听器不是在系统发出通知的那一刻执行的。运行时稍后才派发,那时系统的处理已经结束。见运行时怎么工作。系统通知的 target 都是 application。

没处理的异常不会让 App 退出 ​

JS 里抛出的异常没有被 try / catch 接住时,App 不会退出。抛出异常的那一段代码停止执行,其余部分照常运行:监听器还在,定时器照常触发,界面可以继续操作。

异常出现在运行时怎么处理
main.js 顶层、定时器的回调、事件监听器的回调(包括 sceneconnect 的回调、按钮的点击回调)在 application 上派发 error。没有监听器取消时,向控制台输出以 Uncaught 开头的错误日志
Promise 被拒绝,并且没有挂处理函数。async 函数里抛出的异常属于这一种在 application 上派发 unhandledrejection。没有监听器取消时,输出以 Uncaught (in promise) 开头的错误日志
  • main.js 顶层抛出异常时,这一行之后的顶层代码不再执行。在它之前注册的监听器仍然有效。
  • 事件监听器抛出异常时,同一个事件的其余监听器照常执行,error 在下一个监听器执行之前就派发了。
  • 在这两个事件的监听器里调 preventDefault(),取消的只是运行时输出的那条默认日志。异常已经发生,被中断的代码不会恢复执行。

示例 ​

每个 App 的起点 ​

打印 App 的信息,等系统准备好之后建窗口和页面。

js
console.log('包名', application.bundleIdentifier);
console.log('版本', application.version, '构建号', application.build);
console.log('场景个数', application.scenes.length);

application.addEventListener('sceneconnect', (e) => {
  const win = new UIWindow(e.scene);
  const page = new UIViewController();
  page.view.backgroundColor = 'systemBackground';
  win.rootViewController = page;
  win.makeKeyAndVisible();

  console.log('界面建好了,场景个数', application.scenes.length);
});

效果

  • 控制台先输出三行。包名是 com.example.shop 的 App 运行时是:
    • 包名 com.example.shop
    • 版本 0.1.0 构建号 1
    • 场景个数 0
  • 随后屏幕从黑色变成系统背景色:浅色模式下是白色,深色模式下是黑色。
  • 控制台输出 界面建好了,场景个数 1。

这段代码没有作为一个整体在模拟器运行过。其中用到的每个 API 都在验收用例里运行过。

对应的 iOS API ​

application 不是 UIApplication 的逐项映射。它把 iOS 里分散在几处的 App 级能力放在一个对象上。

ObjCJS
NSBundle.mainBundle.infoDictionaryapplication.info
NSBundle.mainBundle.bundleIdentifierapplication.bundleIdentifier
UIApplication.sharedApplication.applicationStateapplication.state
UIApplication.sharedApplication.connectedScenesapplication.scenes
UIApplication.sharedApplication.supportsMultipleScenesapplication.supportsMultipleScenes
UIApplication.sharedApplication.userInterfaceLayoutDirectionapplication.layoutDirection
UIApplication.sharedApplication.preferredContentSizeCategoryapplication.contentSizeCategory
UIApplication.sharedApplication.backgroundRefreshStatusapplication.backgroundRefreshStatus
UIApplication.sharedApplication.protectedDataAvailableapplication.protectedDataAvailable
UIApplication.sharedApplication.idleTimerDisabled = YESapplication.idleTimerDisabled = true
[UIApplication.sharedApplication openURL:url options:@{} completionHandler:…]application.openURL(url)
beginBackgroundTaskWithName:expirationHandler:、endBackgroundTask:application.runBackgroundTask(work, { name })
UIApplication.sharedApplication.backgroundTimeRemainingapplication.backgroundTimeRemaining
NSUserDefaults.standardUserDefaultsapplication.storage
UISceneWillConnectNotificationapplication.addEventListener('sceneconnect', …)
UISceneDidDisconnectNotificationapplication.addEventListener('scenedisconnect', …)
scene:openURLContexts:application.addEventListener('openurl', …)
scene:continueUserActivity:,活动类型是 NSUserActivityTypeBrowsingWebapplication.addEventListener('openurl', …)
scene:willConnectToSession:options: 里 connectionOptions 的 URLContexts 和 userActivities同一个 openurl,在 sceneconnect 之后派发
Info.plist 的 CFBundleURLTypesnacre.config.json 的 ios.urlSchemes
UIApplicationDidBecomeActiveNotificationapplication.addEventListener('active', …)
UIApplicationWillResignActiveNotificationapplication.addEventListener('inactive', …)
UIApplicationDidEnterBackgroundNotificationapplication.addEventListener('background', …)
UIApplicationWillEnterForegroundNotificationapplication.addEventListener('foreground', …)
UIApplicationDidReceiveMemoryWarningNotificationapplication.addEventListener('memorywarning', …)
UIApplicationUserDidTakeScreenshotNotificationapplication.addEventListener('screenshot', …)
UIApplicationSignificantTimeChangeNotificationapplication.addEventListener('significanttimechange', …)
UIContentSizeCategoryDidChangeNotificationapplication.addEventListener('contentsizecategorychange', …)
NSCurrentLocaleDidChangeNotificationapplication.addEventListener('localechange', …)
UIApplicationProtectedDataDidBecomeAvailableapplication.addEventListener('protecteddataavailable', …)
UIApplicationProtectedDataWillBecomeUnavailableapplication.addEventListener('protecteddataunavailable', …)
UIApplicationBackgroundRefreshStatusDidChangeNotificationapplication.addEventListener('backgroundrefreshstatuschange', …)
UIApplicationWillTerminateNotificationapplication.addEventListener('beforeterminate', …)

与浏览器的对照 ​

浏览器Nacre
window.addEventListener('error', …)application.addEventListener('error', …)
window.addEventListener('unhandledrejection', …)application.addEventListener('unhandledrejection', …)
document.visibilityState 和 visibilitychangeapplication.state 和四个前后台事件
navigator.wakeLock.request('screen')application.idleTimerDisabled = true
rejectionhandled 事件没有

参见 ​