From 276a7f200aac4eaea0aba67c2f1ee50a3dd67e58 Mon Sep 17 00:00:00 2001 From: pandamicro Date: Thu, 16 Apr 2020 11:38:24 +0800 Subject: [PATCH] Partial API translation for core and related tweaks (#6534) * Event api translation * Event manager API translation * Macro cleanup and API doc improve * Code cleanup and API translation in core/platform, * Use macro.ENABLE_WEBGL_ANTIALIAS for initialization * tweak * Improve singleton ref in view * Fix ci * Export sys without default --- cocos/audio/assets/player-web.ts | 2 +- cocos/audio/audio-downloader.ts | 2 +- cocos/core/3d/misc/buffer.ts | 2 +- cocos/core/assets/mesh.ts | 3 +- .../components/ui-base/canvas-component.ts | 4 +- cocos/core/deprecated.ts | 16 +- cocos/core/event/callbacks-invoker.ts | 99 +- cocos/core/event/defines.ts | 25 + cocos/core/event/event-target-factory.ts | 9 +- cocos/core/event/event-target.ts | 89 +- cocos/core/event/event.ts | 24 +- cocos/core/game.ts | 4 +- cocos/core/gfx/webgl/webgl-device.ts | 2 +- cocos/core/platform/SubContextView.ts | 1 - cocos/core/platform/debug.ts | 18 +- .../core/platform/event-manager/event-enum.ts | 29 +- .../platform/event-manager/event-listener.ts | 27 +- .../platform/event-manager/event-manager.ts | 5 +- cocos/core/platform/event-manager/events.ts | 494 +++--- .../platform/event-manager/input-manager.ts | 4 +- .../platform/event-manager/system-event.ts | 44 +- cocos/core/platform/event-manager/touch.ts | 92 +- cocos/core/platform/macro.ts | 538 +------ cocos/core/platform/screen.ts | 47 +- cocos/core/platform/sys.ts | 1410 ++++++++--------- cocos/core/platform/view.ts | 584 +++---- cocos/core/splash-screen-webgl.ts | 2 +- cocos/ui/assembler/label/index.ts | 2 +- .../components/editbox/edit-box-component.ts | 2 +- cocos/ui/components/editbox/edit-box-impl.ts | 2 +- cocos/ui/components/label-component.ts | 2 +- cocos/ui/components/webview/webview-impl.ts | 2 +- cocos/ui/components/widget-manager.ts | 3 +- 33 files changed, 1389 insertions(+), 2200 deletions(-) diff --git a/cocos/audio/assets/player-web.ts b/cocos/audio/assets/player-web.ts index 9445b30e2e..e8b543ffa9 100644 --- a/cocos/audio/assets/player-web.ts +++ b/cocos/audio/assets/player-web.ts @@ -28,7 +28,7 @@ */ import { clamp } from '../../core/math/utils'; -import sys from '../../core/platform/sys'; +import { sys } from '../../core/platform/sys'; import { AudioPlayer, IAudioInfo, PlayingState } from './player'; const audioSupport = sys.__audioSupport; diff --git a/cocos/audio/audio-downloader.ts b/cocos/audio/audio-downloader.ts index beac8a1980..024ba9c011 100644 --- a/cocos/audio/audio-downloader.ts +++ b/cocos/audio/audio-downloader.ts @@ -28,7 +28,7 @@ */ import { getError, log } from '../core/platform/debug'; -import sys from '../core/platform/sys'; +import { sys } from '../core/platform/sys'; import { AudioClip, AudioType } from './assets/clip'; const __audioSupport = sys.__audioSupport; diff --git a/cocos/core/3d/misc/buffer.ts b/cocos/core/3d/misc/buffer.ts index 19724ac05e..60725b17d5 100644 --- a/cocos/core/3d/misc/buffer.ts +++ b/cocos/core/3d/misc/buffer.ts @@ -1,5 +1,5 @@ import { GFXFormat, GFXFormatInfos, GFXFormatType, IGFXFormatInfo } from '../../gfx/define'; -import sys from '../../platform/sys'; +import { sys } from '../../platform/sys'; const _typeMap = { [GFXFormatType.UNORM]: 'Uint', diff --git a/cocos/core/assets/mesh.ts b/cocos/core/assets/mesh.ts index 66892a4ae8..cc962b3689 100644 --- a/cocos/core/assets/mesh.ts +++ b/cocos/core/assets/mesh.ts @@ -46,13 +46,12 @@ import { import { GFXDevice, GFXFeature } from '../gfx/device'; import { IGFXAttribute } from '../gfx/input-assembler'; import { warnID } from '../platform/debug'; -import sys from '../platform/sys'; +import { sys } from '../platform/sys'; import { murmurhash2_32_gc } from '../utils/murmurhash2_gc'; import { Asset } from './asset'; import { Skeleton } from './skeleton'; import { postLoadMesh } from './utils/mesh-utils'; import { Morph, createMorphRendering, MorphRendering } from './morph'; -import { js } from '../utils/js'; function getIndexStrideCtor (stride: number) { switch (stride) { diff --git a/cocos/core/components/ui-base/canvas-component.ts b/cocos/core/components/ui-base/canvas-component.ts index cb3e00dd1e..037db36f26 100644 --- a/cocos/core/components/ui-base/canvas-component.ts +++ b/cocos/core/components/ui-base/canvas-component.ts @@ -36,7 +36,7 @@ import { game } from '../../game'; import { GFXClearFlag } from '../../gfx/define'; import { GFXWindow } from '../../gfx/window'; import { Color, Vec3, Rect } from '../../math'; -import { ResolutionPolicy, view } from '../../platform/view'; +import { view } from '../../platform/view'; import visibleRect from '../../platform/visible-rect'; import { Camera } from '../../renderer'; import { Node } from '../../scene-graph/node'; @@ -343,7 +343,7 @@ export class CanvasComponent extends Component { designSize = view.getDesignResolutionSize(); const policy = view.getResolutionPolicy(); // const clipTopRight = !this.fitHeight && !this.fitWidth; - const clipTopRight = policy === ResolutionPolicy.NO_BORDER; + const clipTopRight = policy === cc.view._rpNoBorder; let offsetX = 0; let offsetY = 0; if (clipTopRight) { diff --git a/cocos/core/deprecated.ts b/cocos/core/deprecated.ts index 675caf869d..280f67f706 100644 --- a/cocos/core/deprecated.ts +++ b/cocos/core/deprecated.ts @@ -6,6 +6,7 @@ import { replaceProperty } from './utils/deprecated'; import * as math from './math'; import { Scheduler } from './scheduler'; import { CameraComponent } from './3d'; +import { EventTouch } from './platform'; // VMATH @@ -177,6 +178,8 @@ replaceProperty(Scheduler.prototype, 'Scheduler.prototype', [ } ]); +// Camera + replaceProperty(CameraComponent.prototype, 'CameraComponent.prototype', [ { name: 'color', @@ -190,4 +193,15 @@ replaceProperty(CameraComponent.prototype, 'CameraComponent.prototype', [ name: 'stencil', newName: 'clearStencil', }, -]) +]); + +// Events + +replaceProperty(EventTouch.prototype, 'EventTouch.prototype', [ + { + name: 'getUILocationInView', + newName: 'getLocationInView', + target: EventTouch, + targetName: 'EventTouch' + } +]); diff --git a/cocos/core/event/callbacks-invoker.ts b/cocos/core/event/callbacks-invoker.ts index bbbdd66973..d8bab4b836 100644 --- a/cocos/core/event/callbacks-invoker.ts +++ b/cocos/core/event/callbacks-invoker.ts @@ -1,6 +1,6 @@ /* Copyright (c) 2013-2016 Chukong Technologies Inc. - Copyright (c) 2017-2018 Xiamen Yaji Software Co., Ltd. + Copyright (c) 2017-2020 Xiamen Yaji Software Co., Ltd. http://www.cocos.com @@ -51,16 +51,20 @@ const callbackInfoPool = new Pool(() => { return new CallbackInfo(); }, 32); +/** + * @zh 事件监听器列表的简单封装。 + * @en A simple list of event callbacks + */ export class CallbackList { public callbackInfos: Array = []; public isInvoking = false; public containCanceled = false; /** - * @zh - * 从列表中移除与指定目标相同回调函数的事件。 + * @zh 从列表中移除与指定目标相同回调函数的事件。 + * @en Remove the event listeners with the given callback from the list * - * @param cb - 指定回调函数 + * @param cb - The callback to be removed */ public removeByCallback (cb: Function) { for (let i = 0; i < this.callbackInfos.length; ++i) { @@ -73,10 +77,9 @@ export class CallbackList { } } /** - * @zh - * 从列表中移除与指定目标相同调用者的事件。 - * - * @param target - 指定调用者 + * @zh 从列表中移除与指定目标相同调用者的事件。 + * @en Remove the event listeners with the given target from the list + * @param target */ public removeByTarget (target: Object) { for (let i = 0; i < this.callbackInfos.length; ++i) { @@ -90,10 +93,9 @@ export class CallbackList { } /** - * @zh - * 移除指定编号事件。 - * - * @param index - 指定编号。 + * @zh 移除指定编号事件。 + * @en Remove the event listener at the given index + * @param index */ public cancel (index: number) { const info = this.callbackInfos[index]; @@ -105,8 +107,8 @@ export class CallbackList { } /** - * @zh - * 注销所有事件。 + * @zh 注销所有事件。 + * @en Cancel all event listeners */ public cancelAll () { for (let i = 0; i < this.callbackInfos.length; i++) { @@ -120,8 +122,8 @@ export class CallbackList { } /** - * @zh - * 取消所有回调。(在移除过程中会更加紧凑的排列数组) + * @zh 立即删除所有取消的回调。(在移除过程中会更加紧凑的排列数组) + * @en Delete all canceled callbacks and compact array */ public purgeCanceled () { for (let i = this.callbackInfos.length - 1; i >= 0; --i) { @@ -134,8 +136,8 @@ export class CallbackList { } /** - * @zh - * 清除并重置所有数据。 + * @zh 清除并重置所有数据。 + * @en Clear all data */ public clear () { this.cancelAll(); @@ -155,21 +157,21 @@ export interface ICallbackTable { } /** - * @zh - * CallbacksInvoker 用来根据 Key 管理事件监听器列表并调用回调方法。 - * @class CallbacksInvoker + * @zh CallbacksInvoker 用来根据事件名(Key)管理事件监听器列表并调用回调方法。 + * @en CallbacksInvoker is used to manager and invoke event listeners with different event keys, + * each key is mapped to a CallbackList. */ export class CallbacksInvoker { public _callbackTable: ICallbackTable = createMap(true); /** - * @zh - * 事件添加管理 + * @zh 向一个事件名注册一个新的事件监听器,包含回调函数和调用者 + * @en Register an event listener to a given event key with callback and target. * - * @param key - 一个监听事件类型的字符串。 - * @param callback - 事件分派时将被调用的回调函数。 - * @param arget - 调用回调的目标。可以为空。 - * @param once - 是否只调用一次。 + * @param key - Event type + * @param callback - Callback function when event triggered + * @param target - Callback callee + * @param once - Whether invoke the callback only once (and remove it) */ public on (key: string, callback: Function, target?: Object, once?: boolean) { let list = this._callbackTable[key]; @@ -182,13 +184,11 @@ export class CallbacksInvoker { } /** - * @zh - * 检查指定事件是否已注册回调。 - * - * @param key - 一个监听事件类型的字符串。 - * @param callback - 事件分派时将被调用的回调函数。 - * @param target - 调用回调的目标。 - * @return - 指定事件是否已注册回调。 + * @zh 检查指定事件是否已注册回调。 + * @en Checks whether there is correspond event listener registered on the given event + * @param key - Event type + * @param callback - Callback function when event triggered + * @param target - Callback callee */ public hasEventListener (key: string, callback?: Function, target: Object | null = null) { const list = this._callbackTable[key]; @@ -222,10 +222,9 @@ export class CallbacksInvoker { } /** - * @zh - * 移除在特定事件类型中注册的所有回调或在某个目标中注册的所有回调。 - * - * @param keyOrTarget - 要删除的事件键或要删除的目标。 + * @zh 移除在特定事件类型中注册的所有回调或在某个目标中注册的所有回调。 + * @en Removes all callbacks registered in a certain event type or all callbacks registered with a certain target + * @param keyOrTarget - The event type or target with which the listeners will be removed */ public removeAll (keyOrTarget?: string | Object) { if (typeof keyOrTarget === 'string') { @@ -263,12 +262,11 @@ export class CallbacksInvoker { } /** - * @zh - * 删除之前与同类型,回调,目标注册的回调。 - * - * @param key - 一个监听事件类型的字符串。 - * @param callback - 移除指定注册回调。如果没有给,则删除全部同事件类型的监听。 - * @param target - 调用回调的目标。 + * @zh 删除以指定事件,回调函数,目标注册的回调。 + * @en Remove event listeners registered with the given event key, callback and target + * @param key - Event type + * @param callback - The callback function of the event listener, if absent all event listeners for the given type will be removed + * @param target - The callback callee of the event listener */ public off (key: string, callback?: Function, target?: Object) { const list = this._callbackTable[key]; @@ -296,15 +294,10 @@ export class CallbacksInvoker { } /** - * @zh - * 事件派发 - * - * @param key - 一个监听事件类型的字符串 - * @param p1 - 派发的第一个参数。 - * @param p2 - 派发的第二个参数。 - * @param p3 - 派发的第三个参数。 - * @param p4 - 派发的第四个参数。 - * @param p5 - 派发的第五个参数。 + * @zh 派发一个指定事件,并传递需要的参数 + * @en Trigger an event directly with the event name and necessary arguments. + * @param key - event type + * @param args - Arguments when the event triggered */ public emit (key: string, ...args: any[]) { const list: CallbackList = this._callbackTable[key]!; diff --git a/cocos/core/event/defines.ts b/cocos/core/event/defines.ts index a601229b5f..41674eaa13 100644 --- a/cocos/core/event/defines.ts +++ b/cocos/core/event/defines.ts @@ -1,3 +1,28 @@ +/* + Copyright (c) 2019-2020 Xiamen Yaji Software Co., Ltd. + + http://www.cocos.com + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated engine source code (the "Software"), a limited, + worldwide, royalty-free, non-assignable, revocable and non-exclusive license + to use Cocos Creator solely to develop games on your target platforms. You shall + not use Cocos Creator software for developing other software or tools that's + used for developing games. You are not granted to publish, distribute, + sublicense, and/or sell copies of Cocos Creator. + + The software or tools in this License Agreement are licensed, not sold. + Xiamen Yaji Software Co., Ltd. reserves all rights not expressly granted to you. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + THE SOFTWARE. +*/ + /** * @hidden */ diff --git a/cocos/core/event/event-target-factory.ts b/cocos/core/event/event-target-factory.ts index 357d2ff47d..1160bd578a 100644 --- a/cocos/core/event/event-target-factory.ts +++ b/cocos/core/event/event-target-factory.ts @@ -1,6 +1,5 @@ /* - Copyright (c) 2013-2016 Chukong Technologies Inc. - Copyright (c) 2017-2018 Xiamen Yaji Software Co., Ltd. + Copyright (c) 2019-2020 Xiamen Yaji Software Co., Ltd. http://www.cocos.com @@ -41,5 +40,9 @@ export function applyMixins (derivedCtor: any, baseCtors: any[]) { }); } -export interface IEventTarget extends EventTarget{ +/** + * @en Interface for all classes that self implement the EventTarget protocol, they are normally not sub class of EventTarget + * @zh 所有自己实现 EventTarget 功能的类都实现了这个 Interface,他们可能无法直接继承自 EventTarget + */ +export interface IEventTarget extends EventTarget { } diff --git a/cocos/core/event/event-target.ts b/cocos/core/event/event-target.ts index 15320090e7..2294d63bf5 100644 --- a/cocos/core/event/event-target.ts +++ b/cocos/core/event/event-target.ts @@ -39,32 +39,49 @@ export interface ITargetImpl extends Object { } /** - * @zh - * 事件目标是事件触发时,分派的事件对象,Node 是最常见的事件目标, - * 但是其他对象也可以是事件目标。 - * 可通过 cc.EventTarget 获得该对象。 + * !#en + * EventTarget is an object to which an event is dispatched when something has occurred. + * Entity are the most common event targets, but other objects can be event targets too. + * + * Event targets are an important part of the Fireball event model. + * The event target serves as the focal point for how events flow through the scene graph. + * When an event such as a mouse click or a keypress occurs, Fireball dispatches an event object + * into the event flow from the root of the hierarchy. The event object then makes its way through + * the scene graph until it reaches the event target, at which point it begins its return trip through + * the scene graph. This round-trip journey to the event target is conceptually divided into three phases: + * - The capture phase comprises the journey from the root to the last node before the event target's node + * - The target phase comprises only the event target node + * - The bubbling phase comprises any subsequent nodes encountered on the return trip to the root of the tree + * See also: http://www.w3.org/TR/DOM-Level-3-Events/#event-flow + * + * Event targets can implement the following methods: + * - _getCapturingTargets + * - _getBubblingTargets + * + * If a class cannot extend from EventTarget, it can consider implements IEventTarget interface. + * + * !#zh + * 事件目标是具有注册监听器、派发事件能力的类,Node 是最常见的事件目标, + * 但是其他类也可以继承自事件目标以获得管理监听器和派发事件的能力。 + * 如果无法继承自 EventTarget,也可以考虑自实现 IEventTarget */ export class EventTarget extends CallbacksInvoker { /** + * @en + * Register an callback of a specific event type on the EventTarget. + * This type of event should be triggered via `emit`. * @zh * 注册事件目标的特定事件类型回调。这种类型的事件应该被 `emit` 触发。 * - * @param type - 一个监听事件类型的字符串. - * @param callback - 事件分派时将被调用的回调函数。如果该回调存在则不会重复添加. - * @param callback.arg1 回调的第一个参数 - * @param callback.arg2 回调的第二个参数 - * @param callback.arg3 回调的第三个参数 - * @param callback.arg4 回调的第四个参数 - * @param callback.arg5 回调的第五个参数 - * @param target - 回调的目标。可以为空。 - * @return - 返回监听回调函数自身。 - * + * @param type - A string representing the event type to listen for. + * @param callback - The callback that will be invoked when the event is dispatched. + * The callback is ignored if it is a duplicate (the callbacks are unique). + * @param target - The target (this object) to invoke the callback, can be null + * @return - Just returns the incoming callback so you can save the anonymous function easier. * @example - * ```typescript * eventTarget.on('fire', function () { * cc.log("fire in the hole"); * }, node); - * ``` */ public on (type: string, callback: Function, target?: Object) { if (!callback) { @@ -88,15 +105,16 @@ export class EventTarget extends CallbacksInvoker { } /** + * @en + * Removes the listeners previously registered with the same type, callback, target and or useCapture, + * if only type is passed as parameter, all listeners registered with that type will be removed. * @zh * 删除之前用同类型,回调,目标或 useCapture 注册的事件监听器,如果只传递 type,将会删除 type 类型的所有事件监听器。 * - * @param type - 一个监听事件类型的字符串。 - * @param callback - 事件分派时将被调用的回调函数。 - * @param target - 调用回调的目标。如果为空, 只有没有目标的事件会被移除。 - * + * @param type - A string representing the event type being removed. + * @param callback - The callback to remove. + * @param target - The target (this object) to invoke the callback, if it's not given, only callback without target will be removed * @example - * ```typescript * // register fire eventListener * var callback = eventTarget.on('fire', function () { * cc.log("fire in the hole"); @@ -105,7 +123,6 @@ export class EventTarget extends CallbacksInvoker { * eventTarget.off('fire', callback, target); * // remove all fire event listeners * eventTarget.off('fire'); - * ``` */ public off (type: string, callback?: Function, target?: Object) { if (!callback) { @@ -126,36 +143,34 @@ export class EventTarget extends CallbacksInvoker { } /** - * @zh - * 在当前 EventTarget 上删除指定目标(target 参数)注册的所有事件监听器。 + * @en Removes all callbacks previously registered with the same target (passed as parameter). + * This is not for removing all listeners in the current event target, + * and this is not for removing all listeners the target parameter have registered. + * It's only for removing all listeners (callback and target couple) registered on the current event target by the target parameter. + * @zh 在当前 EventTarget 上删除指定目标(target 参数)注册的所有事件监听器。 * 这个函数无法删除当前 EventTarget 的所有事件监听器,也无法删除 target 参数所注册的所有事件监听器。 * 这个函数只能删除 target 参数在当前 EventTarget 上注册的所有事件监听器。 - * - * @param target - 注销所有指定目标的监听 + * @param target - The target to be searched for all related listeners */ public targetOff (keyOrTarget?: string | Object) { this.removeAll(keyOrTarget); } /** + * @en + * Register an callback of a specific event type on the EventTarget, + * the callback will remove itself after the first time it is triggered. * @zh * 注册事件目标的特定事件类型回调,回调会在第一时间被触发后删除自身。 * - * @param type - 一个监听事件类型的字符串。 - * @param callback - 事件分派时将被调用的回调函数。如果该回调存在则不会重复添加。 - * @param callback.arg1 回调的第一个参数。 - * @param callback.arg2 第二个参数。 - * @param callback.arg3 第三个参数。 - * @param callback.arg4 第四个参数。 - * @param callback.arg5 第五个参数。 - * @param target - 调用回调的目标。可以为空。 - * + * @param type - A string representing the event type to listen for. + * @param callback - The callback that will be invoked when the event is dispatched. + * The callback is ignored if it is a duplicate (the callbacks are unique). + * @param target - The target (this object) to invoke the callback, can be null * @example - * ```typescript * eventTarget.once('fire', function () { * cc.log("this is the callback and will be invoked only once"); * }, node); - * ``` */ public once (type: string, callback: Function, target?: Object) { if (!callback) { diff --git a/cocos/core/event/event.ts b/cocos/core/event/event.ts index 1a16ebe521..448d7cfea7 100644 --- a/cocos/core/event/event.ts +++ b/cocos/core/event/event.ts @@ -34,8 +34,7 @@ * Base class of all kinds of events. * * @zh - * 包含事件相关信息的对象。 - * 可通过 cc.Event 获得该事件信息。 + * 所有事件对象的基类,包含事件相关基本信息。 */ export default class Event { // Event types @@ -134,7 +133,7 @@ export default class Event { /** * @en - * Indicate whether the event bubbles up through the tree or not. + * Indicate whether the event bubbles up through the hierarchy or not. * * @zh * 表示该事件是否进行冒泡。 @@ -208,7 +207,7 @@ export default class Event { * Reset the event for being stored in the object pool. * * @zh - * 重置对象池中存储的事件。 + * 重置事件对象以便在对象池中存储。 */ public unuse () { this.type = Event.NO_TYPE; @@ -221,10 +220,11 @@ export default class Event { /** * @en - * Reuse the event for being used again by the object pool. - * + * Reinitialize the event for being used again after retrieved from the object pool. * @zh - * 用于对象池再次使用的事件。 + * 重新初始化让对象池中取出的事件可再次使用。 + * @param type - The name of the event (case-sensitive), e.g. "click", "fire", or "submit" + * @param bubbles - A boolean indicating whether the event bubbles up through the tree or not */ public reuse (type: string, bubbles?: boolean) { this.type = type; @@ -261,12 +261,9 @@ export default class Event { /** * @en - *

- * Gets current target of the event
- * note: It only be available when the event listener is associated with node.
- * It returns 0 when the listener is associated with fixed priority. - *

- * + * Gets current target of the event
+ * note: It only be available when the event listener is associated with node.
+ * It returns 0 when the listener is associated with fixed priority. * @zh * 获取当前目标节点 * @returns - The target with which the event associates. @@ -278,7 +275,6 @@ export default class Event { /** * @en * Gets the event type. - * * @zh * 获取事件类型。 */ diff --git a/cocos/core/game.ts b/cocos/core/game.ts index e29662eb5d..a96eba919c 100644 --- a/cocos/core/game.ts +++ b/cocos/core/game.ts @@ -35,7 +35,8 @@ import { WebGL2GFXDevice } from './gfx/webgl2/webgl2-device'; import { ForwardPipeline, RenderPipeline } from './pipeline'; import * as debug from './platform/debug'; import inputManager from './platform/event-manager/input-manager'; -import sys from './platform/sys'; +import { sys } from './platform/sys'; +import { macro } from './platform/macro'; import { ICustomJointTextureLayout } from './renderer'; /** @@ -895,6 +896,7 @@ export class Game extends EventTarget { const opts = { canvasElm: this.canvas as HTMLCanvasElement, debug: true, + isAntialias: EDITOR || macro.ENABLE_WEBGL_ANTIALIAS, devicePixelRatio: window.devicePixelRatio, nativeWidth: Math.floor(screen.width * window.devicePixelRatio), nativeHeight: Math.floor(screen.height * window.devicePixelRatio), diff --git a/cocos/core/gfx/webgl/webgl-device.ts b/cocos/core/gfx/webgl/webgl-device.ts index 1327096dc1..43f90c9bae 100644 --- a/cocos/core/gfx/webgl/webgl-device.ts +++ b/cocos/core/gfx/webgl/webgl-device.ts @@ -1,6 +1,6 @@ import { ALIPAY, RUNTIME_BASED } from 'internal:constants'; import { macro } from '../../platform'; -import sys from '../../platform/sys'; +import { sys } from '../../platform/sys'; import { GFXBindingLayout, IGFXBindingLayoutInfo } from '../binding-layout'; import { GFXBuffer, IGFXBufferInfo } from '../buffer'; import { GFXCommandAllocator, IGFXCommandAllocatorInfo } from '../command-allocator'; diff --git a/cocos/core/platform/SubContextView.ts b/cocos/core/platform/SubContextView.ts index 6de0fdf85f..5d2b795b1b 100644 --- a/cocos/core/platform/SubContextView.ts +++ b/cocos/core/platform/SubContextView.ts @@ -158,7 +158,6 @@ export class SubContextView extends Component { /** * @en Reset open data context size and viewport * @zh 重置开放数据域的尺寸和视窗 - * @method reset */ public reset () { if (this._context) { diff --git a/cocos/core/platform/debug.ts b/cocos/core/platform/debug.ts index cb3dbaf0ef..17fad0e58a 100644 --- a/cocos/core/platform/debug.ts +++ b/cocos/core/platform/debug.ts @@ -96,6 +96,16 @@ export function error (message?: any, ...optionalParams: any[]) { return ccError(message, ...optionalParams); } +/** + * @en + * Assert the condition and output error messages if the condition is not true. + * @zh + * 对检查测试条件进行检查,如果条件不为 true 则输出错误消息 + * @param value - The condition to check on + * @param message - A JavaScript string containing zero or more substitution strings. + * @param optionalParams - JavaScript objects with which to replace substitution strings within msg. + * This gives you additional control over the format of the output. + */ export function assert (value: any, message?: string, ...optionalParams: any[]) { return ccAssert(value, message, ...optionalParams); } @@ -345,16 +355,16 @@ export function getError (errorId: any, ...param: any[]): string { } /** - * @en Returns whether or not to display the FPS information. - * @zh 是否显示 FPS 信息。 + * @en Returns whether or not to display the FPS and debug information. + * @zh 是否显示 FPS 信息和部分调试信息。 */ export function isDisplayStats (): boolean { return cc.profiler ? cc.profiler.isShowingStats() : false; } /** - * @en Sets whether display the FPS on the bottom-left corner. - * @zh 设置是否在左下角显示 FPS。 + * @en Sets whether display the FPS and debug informations on the bottom-left corner. + * @zh 设置是否在左下角显示 FPS 和部分调试。 */ export function setDisplayStats (displayStats: boolean) { if (cc.profiler) { diff --git a/cocos/core/platform/event-manager/event-enum.ts b/cocos/core/platform/event-manager/event-enum.ts index 47bd2c0ac0..5c476d22ef 100644 --- a/cocos/core/platform/event-manager/event-enum.ts +++ b/cocos/core/platform/event-manager/event-enum.ts @@ -4,8 +4,8 @@ import { ccenum } from '../../value-types/enum'; /** - * @zh - * 一般用于系统事件或者节点事件的事件枚举 + * @en The event type supported by SystemEvent and Node events + * @zh SystemEvent 支持的事件类型以及节点事件类型 */ export enum SystemEventType { /** @@ -136,8 +136,8 @@ export enum SystemEventType { TRANSFORM_CHANGED = 'transform-changed', /** - * @en The event type for press the devicemotion event, you can use its value directly: 'devicemotion'. - * @zh + * @en The event type for notifying the host scene has been changed for a persist node. + * @zh 当场景常驻节点的场景发生改变时触发的事件,一般在切换场景过程中触发。 */ SCENE_CHANGED_FOR_PERSISTS = 'scene-changed-for-persists', @@ -160,40 +160,39 @@ export enum SystemEventType { * if the event callback have heavy logic it may have great performance impact, try to avoid such scenario. * * @zh - * 当节点锚点改变时触发的事件。 + * 当节点的 UITransform 锚点改变时触发的事件。 * 性能警告:这个事件会在每次对应的属性被修改时触发,如果事件回调损耗较高,有可能对性能有很大的负面影响,请尽量避免这种情况。 + * @deprecated */ ANCHOR_CHANGED = 'anchor-changed', /** * @en - * The event type for add children. + * The event type for adding a new child node to the target node. * * @zh - * 节点子类添加。 + * 给目标节点添加子节点时触发的事件。 */ CHILD_ADDED = 'child-added', /** * @en - * The event type for removed children. + * The event type for removing a child node from the target node. * * @zh - * 节点子类移除。 + * 给目标节点移除子节点时触发的事件。 */ CHILD_REMOVED = 'child-removed', /** - * @en - * @zh - * 父节点改变时触发的事件。 + * @en The event type for changing the parent of the target node + * @zh 目标节点的父节点改变时触发的事件。 */ PARENT_CHANGED = 'parent-changed', /** - * @en - * @zh - * 节点销毁时触发的事件。 + * @en The event type for destroying the target node + * @zh 目标节点被销毁时触发的事件。 */ NODE_DESTROYED = 'node-destroyed', } diff --git a/cocos/core/platform/event-manager/event-listener.ts b/cocos/core/platform/event-manager/event-listener.ts index dafbf19bdc..fb4c5ec240 100644 --- a/cocos/core/platform/event-manager/event-listener.ts +++ b/cocos/core/platform/event-manager/event-listener.ts @@ -1,7 +1,6 @@ - /* Copyright (c) 2013-2016 Chukong Technologies Inc. - Copyright (c) 2017-2018 Xiamen Yaji Software Co., Ltd. + Copyright (c) 2017-2020 Xiamen Yaji Software Co., Ltd. http://www.cocos.com @@ -26,7 +25,7 @@ */ /** - * @category event + * @hidden */ import { EventKeyboard, EventAcceleration, EventMouse } from './events'; @@ -44,20 +43,14 @@ export interface IListenerMask { } /** - *


- * The base class of event listener.
- * If you need custom listener which with different callback, you need to inherit this class.
- * For instance, you could refer to EventListenerAcceleration, EventListenerKeyboard,
- * EventListenerTouchOneByOne, EventListenerCustom.
- *


- * 封装用户的事件处理逻辑。
+ * @en The base class of event listener.
+ * If you need custom listener which with different callback, you need to inherit this class.
+ * For instance, you could refer to EventListenerAcceleration, EventListenerKeyboard,
+ * EventListenerTouchOneByOne, EventListenerCustom.
+ * @zh 封装用户的事件处理逻辑 * 注意:这是一个抽象类,开发者不应该直接实例化这个类,请参考 [[create]] 。 */ export class EventListener { - - public get onEvent () { - return this._onEvent; - } /** * @en The type code of unknown event listener.
* @zh 未知的事件监听器类型 @@ -114,7 +107,7 @@ export class EventListener { * You can also pass custom parameters in the configuration object,
* all custom parameters will be polyfilled into the event listener object and can be accessed in handlers.
* @zh 通过指定不同的 Event 对象来设置想要创建的事件监听器。 - * @param {Object} argObj a json object + * @param argObj a json object */ public static create (argObj: IEventListenerCreateInfo): EventListener { cc.assertID(argObj && argObj.event, 1900); @@ -178,6 +171,10 @@ export class EventListener { // Whether the listener is enabled private _isEnabled = true; // Whether the listener is enabled + public get onEvent () { + return this._onEvent; + } + constructor (type: number, listenerID: string, callback: ((...args: any[]) => any) | null) { this._onEvent = callback; this._type = type || 0; diff --git a/cocos/core/platform/event-manager/event-manager.ts b/cocos/core/platform/event-manager/event-manager.ts index 38b824048a..78c2943346 100644 --- a/cocos/core/platform/event-manager/event-manager.ts +++ b/cocos/core/platform/event-manager/event-manager.ts @@ -34,6 +34,7 @@ import { Event } from '../../event'; import { EventTouch } from './events'; import { EventListener, TouchOneByOne } from './event-listener'; import { Node } from '../../scene-graph'; +import { macro } from '../macro'; const ListenerID = EventListener.ListenerID; function checkUINode (node) { @@ -946,7 +947,7 @@ class EventManager { const getCode = event.getEventCode(); // const EventTouch = cc.Event.EventTouch; if (getCode === EventTouch.BEGAN) { - if (!cc.macro.ENABLE_MULTI_TOUCH && eventManager._currentTouch) { + if (!macro.ENABLE_MULTI_TOUCH && eventManager._currentTouch) { const node = eventManager._currentTouchListener!._node; if (!node || node.activeInHierarchy) { return false; @@ -964,7 +965,7 @@ class EventManager { removedIdx = listener._claimedTouches.indexOf(selTouch); if (removedIdx !== -1) { isClaimed = true; - if (!cc.macro.ENABLE_MULTI_TOUCH && eventManager._currentTouch && eventManager._currentTouch !== selTouch) { + if (!macro.ENABLE_MULTI_TOUCH && eventManager._currentTouch && eventManager._currentTouch !== selTouch) { return false; } if (getCode === EventTouch.MOVED && listener.onTouchMoved) { diff --git a/cocos/core/platform/event-manager/events.ts b/cocos/core/platform/event-manager/events.ts index 6f21e731c1..9b3e1f9284 100644 --- a/cocos/core/platform/event-manager/events.ts +++ b/cocos/core/platform/event-manager/events.ts @@ -1,6 +1,6 @@ /* Copyright (c) 2013-2016 Chukong Technologies Inc. - Copyright (c) 2017-2018 Xiamen Yaji Software Co., Ltd. + Copyright (c) 2017-2020 Xiamen Yaji Software Co., Ltd. http://www.cocos.com @@ -32,139 +32,118 @@ import Event from '../../event/event'; import { Vec2 } from '../../math/vec2'; import { Touch } from './touch'; +let _vec2 = new Vec2(); + /** * @en The mouse event * @zh 鼠标事件类型 - * @class Event.EventMouse - * @extends Event */ export class EventMouse extends Event { // Inner event types of MouseEvent /** - * @en - * The none event code of mouse event. - * - * @zh - * 无。 + * @en The none event code of mouse event. + * @zh 无效事件代码 */ public static NONE = 0; /** - * @en - * The event type code of mouse down event. - * - * @zh - * 鼠标按下事件。 + * @en The event code of mouse down event. + * @zh 鼠标按下事件代码。 */ public static DOWN = 1; /** - * @en - * The event type code of mouse up event. - * - * @zh - * 鼠标按下后释放事件。 + * @en The event code of mouse up event. + * @zh 鼠标按下后释放事件代码。 */ public static UP = 2; /** - * @en - * The event type code of mouse move event. - * - * @zh - * 鼠标移动事件。 + * @en The event code of mouse move event. + * @zh 鼠标移动事件。 */ public static MOVE = 3; /** - * @en - * The event type code of mouse scroll event. - * - * @zh - * 鼠标滚轮事件。 + * @en The event code of mouse scroll event. + * @zh 鼠标滚轮事件。 */ public static SCROLL = 4; /** - * @en - * The tag of Mouse left button. - * - * @zh - * 鼠标左键的标签。 + * @en The default tag when no button is pressed + * @zh 按键默认的缺省状态 + */ + public static BUTTON_MISSING = -1; + + /** + * @en The tag of mouse's left button. + * @zh 鼠标左键的标签。 */ public static BUTTON_LEFT = 0; /** - * @en - * The tag of Mouse right button (The right button number is 2 on browser). - * - * @zh - * 鼠标右键的标签。 + * @en The tag of mouse's right button (The right button number is 2 on browser). + * @zh 鼠标右键的标签。 */ public static BUTTON_RIGHT = 2; /** - * @en - * The tag of Mouse middle button (The right button number is 1 on browser). - * - * @zh - * 鼠标中键的标签。 + * @en The tag of mouse's middle button. + * @zh 鼠标中键的标签。 */ public static BUTTON_MIDDLE = 1; /** - * @en - * The tag of Mouse button 4. - * - * @zh - * 鼠标按键 4 的标签。 + * @en The tag of mouse's button 4. + * @zh 鼠标按键 4 的标签。 */ public static BUTTON_4 = 3; /** - * @en - * The tag of Mouse button 5. - * - * @zh - * 鼠标按键 5 的标签。 + * @en The tag of mouse's button 5. + * @zh 鼠标按键 5 的标签。 */ public static BUTTON_5 = 4; /** - * @en - * The tag of Mouse button 6. - * - * @zh - * 鼠标按键 6 的标签。 + * @en The tag of mouse's button 6. + * @zh 鼠标按键 6 的标签。 */ public static BUTTON_6 = 5; /** - * @en - * The tag of Mouse button 7. - * - * @zh - * 鼠标按键 7 的标签。 + * @en The tag of mouse's button 7. + * @zh 鼠标按键 7 的标签。 */ public static BUTTON_7 = 6; /** - * @en - * The tag of Mouse button 8. - * - * @zh - * 鼠标按键 8 的标签。 + * @en The tag of mouse's button 8. + * @zh 鼠标按键 8 的标签。 */ public static BUTTON_8 = 7; + /** + * @en Mouse movement on x axis of the UI coordinate system. + * @zh 鼠标在 UI 坐标系下 X 轴上的移动距离 + */ public movementX: number = 0; + /** + * @en Mouse movement on y axis of the UI coordinate system. + * @zh 鼠标在 UI 坐标系下 Y 轴上的移动距离 + */ public movementY: number = 0; + /** + * @en The type of the event, possible values are UP, DOWN, MOVE, SCROLL + * @zh 鼠标事件类型,可以是 UP, DOWN, MOVE, CANCELED。 + */ public eventType: number; - private _button: number | null = 0; + private _button: number = EventMouse.BUTTON_MISSING; private _x: number = 0; @@ -179,8 +158,8 @@ export class EventMouse extends Event { private _scrollY: number = 0; /** - * @param eventType - 鼠标时间类型 UP, DOWN, MOVE, CANCELED。 - * @param bubbles - 事件是否通过树结构冒泡。默认为 false。 + * @param eventType - The type of the event, possible values are UP, DOWN, MOVE, SCROLL + * @param bubbles - Indicate whether the event bubbles up through the hierarchy or not. */ constructor (eventType: number, bubbles?: boolean, prevLoc?: Vec2) { super(Event.MOUSE, bubbles); @@ -192,11 +171,10 @@ export class EventMouse extends Event { } /** - * @en - * Sets scroll data. - * - * @zh - * 设置鼠标的滚动数据。 + * @en Sets scroll data of the mouse. + * @zh 设置鼠标滚轮的滚动数据。 + * @param scrollX - The scroll value on x axis + * @param scrollY - The scroll value on y axis */ public setScrollData (scrollX: number, scrollY: number) { this._scrollX = scrollX; @@ -204,33 +182,26 @@ export class EventMouse extends Event { } /** - * @en - * Returns the x axis scroll value. - * - * @zh - * 获取鼠标滚动的X轴距离,只有滚动时才有效。 + * @en Returns the scroll value on x axis. + * @zh 获取鼠标滚动的 X 轴距离,只有滚动时才有效。 */ public getScrollX () { return this._scrollX; } /** - * @en - * Returns the y axis scroll value. - * - * @zh - * 获取滚轮滚动的 Y 轴距离,只有滚动时才有效。 + * @en Returns the scroll value on y axis. + * @zh 获取滚轮滚动的 Y 轴距离,只有滚动时才有效。 */ public getScrollY () { return this._scrollY; } /** - * @en - * Sets cursor location. - * - * @zh - * 设置当前鼠标位置。 + * @en Sets cursor location. + * @zh 设置当前鼠标位置。 + * @param x - The location on x axis + * @param y - The location on y axis */ public setLocation (x: number, y: number) { this._x = x; @@ -238,11 +209,9 @@ export class EventMouse extends Event { } /** - * @en - * Returns cursor location. - * - * @zh - * 获取鼠标相对于左下角位置对象,对象包含 x 和 y 属性。 + * @en Returns cursor location. + * @zh 获取鼠标相对于左下角位置对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getLocation (out?: Vec2) { if (!out) { @@ -254,11 +223,9 @@ export class EventMouse extends Event { } /** - * @en - * Returns the current cursor location in screen coordinates. - * - * @zh - * 获取当前事件在游戏窗口内的坐标位置对象,对象包含 x 和 y 属性。 + * @en Returns the current cursor location in game view coordinates. + * @zh 获取当前事件在游戏窗口内的坐标位置对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getLocationInView (out?: Vec2) { if (!out) { @@ -270,11 +237,9 @@ export class EventMouse extends Event { } /** - * @en - * Returns the current cursor location in ui coordinates. - * - * @zh - * 获取当前事件在 UI 窗口内的坐标位置,对象包含 x 和 y 属性。 + * @en Returns the current cursor location in ui coordinates. + * @zh 获取当前事件在 UI 窗口内的坐标位置,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getUILocation (out?: Vec2){ if (!out) { @@ -287,11 +252,9 @@ export class EventMouse extends Event { } /** - * @en - * Returns the previous touch location. - * - * @zh - * 获取鼠标点击在上一次事件时的位置对象,对象包含 x 和 y 属性。 + * @en Returns the previous touch location. + * @zh 获取鼠标点击在上一次事件时的位置对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getPreviousLocation (out?: Vec2) { if (!out) { @@ -303,11 +266,9 @@ export class EventMouse extends Event { } /** - * @en - * Returns the previous touch location. - * - * @zh - * 获取鼠标点击在上一次事件时的位置对象,对象包含 x 和 y 属性。 + * @en Returns the previous touch location. + * @zh 获取鼠标点击在上一次事件时的位置对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getUIPreviousLocation (out?: Vec2) { if (!out) { @@ -320,11 +281,9 @@ export class EventMouse extends Event { } /** - * @en - * Returns the delta distance from the previous location to current location. - * - * @zh - * 获取鼠标距离上一次事件移动的距离对象,对象包含 x 和 y 属性。 + * @en Returns the delta distance from the previous location to current location. + * @zh 获取鼠标距离上一次事件移动的距离对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getDelta (out?: Vec2) { if (!out) { @@ -336,33 +295,25 @@ export class EventMouse extends Event { } /** - * @en - * Returns the X axis delta distance from the previous location to current location. - * - * @zh - * 获取鼠标距离上一次事件移动的 X 轴距离。 + * @en Returns the X axis delta distance from the previous location to current location. + * @zh 获取鼠标距离上一次事件移动的 X 轴距离。 */ public getDeltaX () { return this._x - this._prevX; } /** - * @en - * Returns the Y axis delta distance from the previous location to current location. - * - * @zh - * 获取鼠标距离上一次事件移动的 Y 轴距离。 + * @en Returns the Y axis delta distance from the previous location to current location. + * @zh 获取鼠标距离上一次事件移动的 Y 轴距离。 */ public getDeltaY () { return this._y - this._prevY; } /** - * @en - * Returns the delta distance from the previous location to current location. - * - * @zh - * 获取鼠标距离上一次事件移动的距离对象,对象包含 x 和 y 属性。 + * @en Returns the delta distance from the previous location to current location in the UI coordinates. + * @zh 获取鼠标距离上一次事件移动在 UI 坐标系下的距离对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getUIDelta (out?: Vec2) { if (!out) { @@ -374,74 +325,57 @@ export class EventMouse extends Event { } /** - * @en - * Returns the X axis delta distance from the previous location to current location. - * - * @zh - * 获取鼠标距离上一次事件移动的 X 轴距离。 + * @en Returns the X axis delta distance from the previous location to current location in the UI coordinates. + * @zh 获取鼠标距离上一次事件移动在 UI 坐标系下的 X 轴距离。 */ public getUIDeltaX () { return (this._x - this._prevX) / cc.view.getScaleX(); } /** - * @en - * Returns the Y axis delta distance from the previous location to current location. - * - * @zh - * 获取鼠标距离上一次事件移动的 Y 轴距离。 + * @en Returns the Y axis delta distance from the previous location to current location in the UI coordinates. + * @zh 获取鼠标距离上一次事件移动在 UI 坐标系下的 Y 轴距离。 */ public getUIDeltaY () { return (this._y - this._prevY) / cc.view.getScaleY(); } /** - * @en - * Sets mouse button. - * - * @zh - * 设置鼠标按键。 + * @en Sets mouse button code. + * @zh 设置鼠标按键。 + * @param button - The button code */ - public setButton (button: number | null) { + public setButton (button: number) { this._button = button; } /** - * @en - * Returns mouse button. - * - * @zh - * 获取鼠标按键。 + * @en Returns mouse button code. + * @zh 获取鼠标按键。 */ public getButton () { return this._button; } /** - * @en - * Returns location X axis data. - * - * @zh - * 获取鼠标当前位置 X 轴。 + * @en Returns location data on X axis. + * @zh 获取鼠标当前 X 轴位置。 */ public getLocationX () { return this._x; } /** - * @en Returns location Y axis data. - * @zh 获取鼠标当前位置 Y 轴。 + * @en Returns location data on Y axis. + * @zh 获取鼠标当前 Y 轴位置。 */ public getLocationY () { return this._y; } /** - * @en - * Returns location X axis data. - * - * @zh - * 获取鼠标当前位置 X 轴。 + * @en Returns location data on X axis. + * @zh 获取鼠标当前 X 轴位置。 */ public getUILocationX () { const viewport = cc.view.getViewportRect(); @@ -449,11 +383,8 @@ export class EventMouse extends Event { } /** - * @en - * Returns location Y axis data. - * - * @zh - * 获取鼠标当前位置 Y 轴。 + * @en Returns location data on Y axis. + * @zh 获取鼠标当前 Y 轴位置。 */ public getUILocationY () { const viewport = cc.view.getViewportRect(); @@ -470,55 +401,41 @@ export class EventMouse extends Event { */ export class EventTouch extends Event { /** - * @en - * The maximum touch numbers - * - * @zh - * 最大触摸数量。 + * @en The maximum touch point numbers simultaneously + * @zh 同时存在的最大触点数量。 */ public static MAX_TOUCHES = 5; /** - * @en - * The event type code of touch began event. - * - * @zh - * 开始触摸事件。 + * @en The event type code of touch began event. + * @zh 开始触摸事件。 */ public static BEGAN = 0; /** - * @en - * The event type code of touch moved event. - * - * @zh - * 触摸后移动事件。 + * @en The event type code of touch moved event. + * @zh 触摸后移动事件。 */ public static MOVED = 1; /** - * @en - * The event type code of touch ended event. - * - * @zh - * 结束触摸事件。 + * @en The event type code of touch ended event. + * @zh 结束触摸事件。 */ public static ENDED = 2; /** - * @en - * The event type code of touch cancelled event. - * + * @en The event type code of touch canceled event. * @zh 取消触摸事件。 */ public static CANCELLED = 3; /** - * @en - * The current touch object - * - * @zh - * 当前触点对象 + * @en The current touch object + * @zh 当前触点对象 */ public touch: Touch | null = null; - + /** + * @en Indicate whether the touch event is simulated or real + * @zh 表示触摸事件是真实触点触发的还是模拟的 + */ public simulate = false; private _eventCode: number; @@ -526,8 +443,9 @@ export class EventTouch extends Event { private _touches: Touch[]; /** - * @param touches - touch 数组 - * @param bubbles - 事件是否通过树结构冒泡。默认为 false。 + * @param touches - An array of current touches + * @param bubbles - Indicate whether the event bubbles up through the hierarchy or not. + * @param eventCode - The type code of the touch event */ constructor (touches?: Touch[], bubbles?: boolean, eventCode?: number) { super(Event.TOUCH, bubbles); @@ -536,33 +454,26 @@ export class EventTouch extends Event { } /** - * @en - * Returns event code. - * - * @zh - * 获取事件类型。 + * @en Returns event type code. + * @zh 获取触摸事件类型。 */ public getEventCode () { return this._eventCode; } /** - * @en - * Returns touches of event. - * - * @zh - * 获取触摸点的列表。 + * @en Returns touches of event. + * @zh 获取触摸点的列表。 */ public getTouches () { return this._touches; } /** - * @en - * Sets touch location. - * - * @zh - * 设置当前触点位置 + * @en Sets touch location. + * @zh 设置当前触点位置 + * @param x - The current touch location on the x axis + * @param y - The current touch location on the y axis */ public setLocation (x: number, y: number) { if (this.touch) { @@ -571,151 +482,112 @@ export class EventTouch extends Event { } /** - * @en - * Returns touch location. - * - * @zh - * 获取触点位置。 + * @en Returns the current touch location. + * @zh 获取触点位置。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getLocation (out?: Vec2) { return this.touch ? this.touch.getLocation(out) : new Vec2(); } /** - * @en - * Returns touch location. - * - * @zh - * 获取触点位置。 + * @en Returns the current touch location in UI coordinates. + * @zh 获取 UI 坐标系下的触点位置。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getUILocation(out?: Vec2) { return this.touch ? this.touch.getUILocation(out) : new Vec2(); } /** - * @en - * Returns the current touch location in screen coordinates. - * - * @zh - * 获取当前触点在游戏窗口中的位置。 + * @en Returns the current touch location in game screen coordinates. + * @zh 获取当前触点在游戏窗口中的位置。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getLocationInView (out?: Vec2) { return this.touch ? this.touch.getLocationInView(out) : new Vec2(); } - /** - * @en - * Returns the current touch location in screen coordinates. - * - * @zh - * 获取当前触点在游戏窗口中的位置。 - */ - public getUILocationInView(out?: Vec2) { - return this.touch ? this.touch.getLocationInView(out) : new Vec2(); - } - /** * @en Returns the previous touch location. * @zh 获取触点在上一次事件时的位置对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getPreviousLocation (out?: Vec2) { return this.touch ? this.touch.getPreviousLocation(out) : new Vec2(); } /** - * @en - * Returns the start touch location. - * - * @zh - * 获获取触点落下时的位置对象,对象包含 x 和 y 属性。 + * @en Returns the start touch location. + * @zh 获获取触点落下时的位置对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getStartLocation (out?: Vec2) { return this.touch ? this.touch.getStartLocation(out) : new Vec2(); } /** - * @en - * Returns the start touch location. - * - * @zh - * 获获取触点落下时的 UI 世界下位置对象,对象包含 x 和 y 属性。 + * @en Returns the start touch location in UI coordinates. + * @zh 获获取触点落下时的 UI 世界下位置对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getUIStartLocation(out?: Vec2) { return this.touch ? this.touch.getUIStartLocation(out) : new Vec2(); } /** - * @en - * Returns the id of cc.Touch. - * - * @zh - * 触点的标识 ID,可以用来在多点触摸中跟踪触点。 + * @en Returns the id of the current touch point. + * @zh 获取触点的标识 ID,可以用来在多点触摸中跟踪触点。 */ public getID () { return this.touch ? this.touch.getID() : null; } /** - * @en - * Returns the delta distance from the previous location to current location. - * - * @zh - * 获取触点距离上一次事件移动的距离对象,对象包含 x 和 y 属性。 + * @en Returns the delta distance from the previous location to current location. + * @zh 获取触点距离上一次事件移动的距离对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getDelta (out?: Vec2) { return this.touch ? this.touch.getDelta(out) : new Vec2(); } /** - * @en - * Returns the delta distance from the previous location to current location. - * - * @zh - * 获取触点距离上一次事件 UI 世界下移动的距离对象,对象包含 x 和 y 属性。 + * @en Returns the delta distance from the previous location to current location. + * @zh 获取触点距离上一次事件 UI 世界下移动的距离对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getUIDelta(out?: Vec2) { return this.touch ? this.touch.getUIDelta(out) : new Vec2(); } /** - * @en - * Returns the X axis delta distance from the previous location to current location. - * - * @zh - * 获取触点距离上一次事件移动的 x 轴距离。 + * @en Returns the X axis delta distance from the previous location to current location. + * @zh 获取触点距离上一次事件移动的 x 轴距离。 */ - public getDeltaX (out?: Vec2) { - return this.touch ? this.touch.getDelta(out).x : 0; + public getDeltaX () { + return this.touch ? this.touch.getDelta(_vec2).x : 0; } /** - * @en - * Returns the Y axis delta distance from the previous location to current location. - * - * @zh - * 获取触点距离上一次事件移动的 y 轴距离。 + * @en Returns the Y axis delta distance from the previous location to current location. + * @zh 获取触点距离上一次事件移动的 y 轴距离。 */ - public getDeltaY (out?: Vec2) { - return this.touch ? this.touch.getDelta(out).y : 0; + public getDeltaY () { + return this.touch ? this.touch.getDelta(_vec2).y : 0; } /** - * @en - * Returns location X axis data. - * - * @zh - * 获取当前触点 X 轴位置。 + * @en Returns location X axis data. + * @zh 获取当前触点 X 轴位置。 */ public getLocationX () { return this.touch ? this.touch.getLocationX() : 0; } /** - * @en - * Returns location Y axis data. - * - * @zh - * 获取当前触点 Y 轴位置。 + * @en Returns location Y axis data. + * @zh 获取当前触点 Y 轴位置。 */ public getLocationY () { return this.touch ? this.touch.getLocationY() : 0; @@ -725,16 +597,19 @@ export class EventTouch extends Event { /** * @en * The acceleration event. - * * @zh - * 加速度事件。 + * 加速计事件。 */ export class EventAcceleration extends Event { + /** + * @en The acceleration object + * @zh 加速度对象 + */ public acc: Object; /** - * @param acc - 加速度 - * @param bubbles - 事件是否通过树结构冒泡。默认为 false。 + * @param acc - The acceleration + * @param bubbles - Indicate whether the event bubbles up through the hierarchy or not. */ constructor (acc: Object, bubbles?: boolean) { super(Event.ACCELERATION, bubbles); @@ -745,36 +620,37 @@ export class EventAcceleration extends Event { /** * @en * The keyboard event. - * * @zh * 键盘事件。 */ export class EventKeyboard extends Event { /** - * @en - * The keyCode read-only property represents a system and implementation dependent numerical code + * @en The keyCode read-only property represents a system and implementation dependent numerical code * identifying the unmodified value of the pressed key. * This is usually the decimal ASCII (RFC 20) or Windows 1252 code corresponding to the key. * If the key can't be identified, this value is 0. - * - * @zh - * keyCode 是只读属性它表示一个系统和依赖于实现的数字代码,可以识别按键的未修改值。 + * @zh keyCode 是只读属性它表示一个系统和依赖于实现的数字代码,可以识别按键的未修改值。 * 这通常是十进制 ASCII (RFC20) 或者 Windows 1252 代码,所对应的密钥。 * 如果无法识别该键,则该值为 0。 */ public keyCode: number; /** - * Raw DOM event. + * @en Raw DOM KeyboardEvent. + * @zh 原始 DOM KeyboardEvent 事件对象 */ public rawEvent?: KeyboardEvent; + /** + * @en Indicates whether the current key is being pressed + * @zh 表示当前按键是否正在被按下 + */ public isPressed: boolean; /** - * @param keyCode - 事件触发的键值。 - * @param isPressed - 指示键是否已按下。 - * @param bubbles - 事件是否通过树结构冒泡。默认为 false。 + * @param keyCode - The key code of the current key or the DOM KeyboardEvent + * @param isPressed - Indicates whether the current key is being pressed + * @param bubbles - Indicates whether the event bubbles up through the hierarchy or not. */ constructor (keyCode: number | KeyboardEvent, isPressed: boolean, bubbles?: boolean) { super(Event.KEYBOARD, bubbles); diff --git a/cocos/core/platform/event-manager/input-manager.ts b/cocos/core/platform/event-manager/input-manager.ts index ac6297c434..252f2a6b83 100644 --- a/cocos/core/platform/event-manager/input-manager.ts +++ b/cocos/core/platform/event-manager/input-manager.ts @@ -31,7 +31,7 @@ import { Vec2 } from '../../math/index'; import { rect } from '../../math/rect'; import { macro } from '../macro'; -import sys from '../sys'; +import { sys } from '../sys'; import eventManager from './event-manager'; import { EventAcceleration, EventKeyboard, EventMouse, EventTouch } from './events'; import { Touch } from './touch'; @@ -651,7 +651,7 @@ class InputManager { listenDOMMouseEvent('mousemove', EventMouse.MOVE, (event, mouseEvent, location, pos) => { this.handleTouchesMove([this.getTouchByXY(event, location.x, location.y, pos)]); if (!this._mousePressed) { - mouseEvent.setButton(null); + mouseEvent.setButton(EventMouse.BUTTON_MISSING); } if (event.movementX !== undefined && event.movementY !== undefined) { mouseEvent.movementX = event.movementX; diff --git a/cocos/core/platform/event-manager/system-event.ts b/cocos/core/platform/event-manager/system-event.ts index 01835635a3..cc2b884635 100644 --- a/cocos/core/platform/event-manager/system-event.ts +++ b/cocos/core/platform/event-manager/system-event.ts @@ -46,11 +46,6 @@ let mouseListener: EventListener | null = null; * @en * The System event, it currently supports keyboard events and accelerometer events.
* You can get the SystemEvent instance with cc.systemEvent.
-* @example -* ``` -* cc.systemEvent.on(cc.SystemEvent.EventType.DEVICEMOTION, this.onDeviceMotionEvent, this); -* cc.systemEvent.off(cc.SystemEvent.EventType.DEVICEMOTION, this.onDeviceMotionEvent, this); -* ``` * @zh * 系统事件,它目前支持按键事件和重力感应事件。
* 你可以通过 cc.systemEvent 获取到 SystemEvent 的实例。
@@ -59,8 +54,6 @@ let mouseListener: EventListener | null = null; * cc.systemEvent.on(cc.SystemEvent.EventType.DEVICEMOTION, this.onDeviceMotionEvent, this); * cc.systemEvent.off(cc.SystemEvent.EventType.DEVICEMOTION, this.onDeviceMotionEvent, this); * ``` -* @class SystemEvent -* @extends EventTarget */ export class SystemEvent extends EventTarget { @@ -70,29 +63,24 @@ export class SystemEvent extends EventTarget { } /** * @en - * whether enable accelerometer event. + * Sets whether to enable the accelerometer event listener or not. * * @zh * 是否启用加速度计事件。 - * - * @param {Boolean} isEnable */ - public setAccelerometerEnabled (isEnable: boolean) { + public setAccelerometerEnabled (isEnabled: boolean) { if (EDITOR) { return; } - inputManager.setAccelerometerEnabled(isEnable); + inputManager.setAccelerometerEnabled(isEnabled); } /** * @en - * set accelerometer interval value. + * Sets the accelerometer interval value. * * @zh * 设置加速度计间隔值。 - * - * @method setAccelerometerInterval - * @param {Number} interval */ public setAccelerometerInterval (interval: number) { if (EDITOR) { @@ -109,12 +97,14 @@ export class SystemEvent extends EventTarget { callback: (touch?: Touch, event?: EventTouch) => void, target?: Object); public on (type: SystemEventType.DEVICEMOTION, callback: (event?: EventAcceleration) => void, target?: Object); /** + * @en + * Register an callback of a specific system event type. * @zh - * 系统事件注册。 + * 注册特定事件类型回调。 * - * @param type - 事件名。 - * @param callback - 事件回调。 - * @param target - 接收事件目标。 + * @param type - The event type + * @param callback - The event listener's callback + * @param target - The event listener's target and callee */ public on (type: string, callback: Function, target?: Object) { if (EDITOR) { @@ -219,12 +209,15 @@ export class SystemEvent extends EventTarget { } /** + * @en + * Removes the listeners previously registered with the same type, callback, target and or useCapture, + * if only type is passed as parameter, all listeners registered with that type will be removed. * @zh - * 注销事件。 + * 删除之前用同类型,回调,目标或 useCapture 注册的事件监听器,如果只传递 type,将会删除 type 类型的所有事件监听器。 * - * @param type - 事件名。 - * @param callback - 事件回调。 - * @param target - 回调接收对象。 + * @param type - A string representing the event type being removed. + * @param callback - The callback to remove. + * @param target - The target (this object) to invoke the callback, if it's not given, only callback without target will be removed */ public off (type: string, callback?: Function, target?: Object) { if (EDITOR) { @@ -282,7 +275,8 @@ cc.SystemEvent = SystemEvent; */ /** - * 系统事件单例,方便全局使用。 + * @en The singleton of the SystemEvent, there should only be one instance to be used globally + * @zh 系统事件单例,方便全局使用。 */ export const systemEvent = new SystemEvent(); cc.systemEvent = systemEvent; diff --git a/cocos/core/platform/event-manager/touch.ts b/cocos/core/platform/event-manager/touch.ts index 921fed03c9..32a1cc4d43 100644 --- a/cocos/core/platform/event-manager/touch.ts +++ b/cocos/core/platform/event-manager/touch.ts @@ -32,19 +32,14 @@ import { Vec2 } from '../../math'; const _vec2 = new Vec2(); /** - * @en The touch event class - * @zh 封装了触摸相关的信息。 - * @class Touch - * - * @param {Number} x - * @param {Number} y - * @param {Number} id + * @en The touch point class + * @zh 封装了触点相关的信息。 */ export class Touch { private _point: Vec2 = new Vec2(); private _prevPoint: Vec2 = new Vec2(); private _lastModified = 0; - private _id: number | null = null; + private _id: number = 0; private _startPoint: Vec2 = new Vec2(); private _startPointCaptured: boolean = false; @@ -52,13 +47,19 @@ export class Touch { return this._lastModified; } - constructor (x: number, y: number, id: number | null = null) { + /** + * @param x - x position of the touch point + * @param y - y position of the touch point + * @param id - The id of the touch point + */ + constructor (x: number, y: number, id: number = 0) { this.setTouchInfo(id, x, y); } /** * @en Returns the current touch location in OpenGL coordinates.、 * @zh 获取当前触点位置。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getLocation (out?: Vec2) { if (!out){ @@ -86,8 +87,9 @@ export class Touch { } /** - * @en Returns the current touch location in OpenGL coordinates.、 - * @zh 获取当前触点位置。 + * @en Returns the current touch location in UI coordinates.、 + * @zh 获取当前触点在 UI 坐标系中的位置。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getUILocation (out?: Vec2) { if (!out) { @@ -100,8 +102,8 @@ export class Touch { } /** - * @en Returns X axis location value. - * @zh 获取当前触点 X 轴位置。 + * @en Returns X axis location value in UI coordinates. + * @zh 获取当前触点在 UI 坐标系中 X 轴位置。 */ public getUILocationX () { const viewport = cc.view.getViewportRect(); @@ -109,8 +111,8 @@ export class Touch { } /** - * @en Returns Y axis location value. - * @zh 获取当前触点 Y 轴位置。 + * @en Returns Y axis location value in UI coordinates. + * @zh 获取当前触点在 UI 坐标系中 Y 轴位置。 */ public getUILocationY () { const viewport = cc.view.getViewportRect(); @@ -118,8 +120,9 @@ export class Touch { } /** - * @en Returns the previous touch location in OpenGL coordinates. + * @en Returns the previous touch location. * @zh 获取触点在上一次事件时的位置对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getPreviousLocation (out?: Vec2) { if (!out) { @@ -131,8 +134,9 @@ export class Touch { } /** - * @en Returns the previous touch location in OpenGL coordinates. - * @zh 获取触点在上一次事件时的位置对象,对象包含 x 和 y 属性。 + * @en Returns the previous touch location in UI coordinates. + * @zh 获取触点在上一次事件时在 UI 坐标系中的位置对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getUIPreviousLocation (out?: Vec2) { if (!out) { @@ -145,8 +149,9 @@ export class Touch { } /** - * @en Returns the start touch location in OpenGL coordinates. + * @en Returns the start touch location. * @zh 获获取触点落下时的位置对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getStartLocation (out?: Vec2) { if (!out) { @@ -158,8 +163,9 @@ export class Touch { } /** - * @en Returns the start touch location in OpenGL coordinates. - * @zh 获获取触点落下时的位置对象,对象包含 x 和 y 属性。 + * @en Returns the start touch location in UI coordinates. + * @zh 获获取触点落下时在 UI 坐标系中的位置对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getUIStartLocation (out?: Vec2) { if (!out) { @@ -172,8 +178,9 @@ export class Touch { } /** - * @en Returns the delta distance from the previous touche to the current one in screen coordinates. + * @en Returns the delta distance from the previous touche to the current one. * @zh 获取触点距离上一次事件移动的距离对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getDelta (out?: Vec2) { if (!out){ @@ -186,8 +193,9 @@ export class Touch { } /** - * @en Returns the delta distance from the previous touche to the current one in screen coordinates. - * @zh 获取触点距离上一次事件移动的距离对象,对象包含 x 和 y 属性。 + * @en Returns the delta distance from the previous touche to the current one in UI coordinates. + * @zh 获取触点距离上一次事件移动在 UI 坐标系中的距离对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getUIDelta (out?: Vec2) { if (!out) { @@ -204,6 +212,7 @@ export class Touch { /** * @en Returns the current touch location in screen coordinates. * @zh 获取当前事件在游戏窗口内的坐标位置对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getLocationInView (out?: Vec2) { if (!out) { @@ -217,6 +226,7 @@ export class Touch { /** * @en Returns the previous touch location in screen coordinates. * @zh 获取触点在上一次事件时在游戏窗口中的位置对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getPreviousLocationInView (out?: Vec2) { if (!out) { @@ -230,6 +240,7 @@ export class Touch { /** * @en Returns the start touch location in screen coordinates. * @zh 获取触点落下时在游戏窗口中的位置对象,对象包含 x 和 y 属性。 + * @param out - Pass the out object to avoid object creation, very good practice */ public getStartLocationInView (out?: Vec2) { if (!out) { @@ -241,7 +252,7 @@ export class Touch { } /** - * @en Returns the id of cc.Touch. + * @en Returns the id of the touch point. * @zh 触点的标识 ID,可以用来在多点触摸中跟踪触点。 */ public getID () { @@ -249,10 +260,13 @@ export class Touch { } /** - * @en Sets information to touch. - * @zh 设置触摸相关的信息。用于监控触摸事件。 + * @en Resets touch point information. + * @zh 重置触点相关的信息。 + * @param id - The id of the touch point + * @param x - x position of the touch point + * @param y - y position of the touch point */ - public setTouchInfo (id: number | null = null, x?: number, y?: number) { + public setTouchInfo (id: number = 0, x?: number, y?: number) { this._prevPoint = this._point; this._point = new Vec2(x || 0, y || 0); this._id = id; @@ -263,8 +277,19 @@ export class Touch { } } + /** + * @en Sets touch point location. + * @zh 设置触点位置。 + * @param point - The location + */ public setPoint (point: Vec2): void; + /** + * @en Sets touch point location. + * @zh 设置触点位置。 + * @param x - x position + * @param y - y position + */ public setPoint (x: number, y: number): void; public setPoint (x: number | Vec2, y?: number) { @@ -278,8 +303,19 @@ export class Touch { this._lastModified = cc.director.getCurrentTime(); } + /** + * @en Sets the location previously registered for the current touch. + * @zh 设置触点在前一次触发时收集的位置。 + * @param point - The location + */ public setPrevPoint (point: Vec2): void; + /** + * @en Sets the location previously registered for the current touch. + * @zh 设置触点在前一次触发时收集的位置。 + * @param x - x position + * @param y - y position + */ public setPrevPoint (x: number, y: number): void; public setPrevPoint (x: number | Vec2, y?: number) { diff --git a/cocos/core/platform/macro.ts b/cocos/core/platform/macro.ts index 7339549e33..52e1de8521 100644 --- a/cocos/core/platform/macro.ts +++ b/cocos/core/platform/macro.ts @@ -31,29 +31,12 @@ import { Vec2 } from '../math'; -/** - * @en - * Predefined constants - * @zh - * 预定义常量。 - * @class macro - * @static - */ - const SUPPORT_TEXTURE_FORMATS = ['.pkm', '.pvr', '.webp', '.jpg', '.jpeg', '.bmp', '.png']; -/** - * @en Key map for keyboard event - * @zh 键盘事件的按键值。 - * @enum macro.KEY - * @example {@link cocos/core/platform/CCCommon/KEY.js} - */ const KEY = { /** * @en None * @zh 没有分配 - * @property none - * @type {Number} * @readonly */ 'none': 0, @@ -62,16 +45,12 @@ const KEY = { /** * @en The back key * @zh 返回键 - * @property back - * @type {Number} * @readonly */ 'back': 6, /** * @en The menu key * @zh 菜单键 - * @property menu - * @type {Number} * @readonly */ 'menu': 18, @@ -79,8 +58,6 @@ const KEY = { /** * @en The backspace key * @zh 退格键 - * @property backspace - * @type {Number} * @readonly */ 'backspace': 8, @@ -88,8 +65,6 @@ const KEY = { /** * @en The tab key * @zh Tab 键 - * @property tab - * @type {Number} * @readonly */ 'tab': 9, @@ -97,8 +72,6 @@ const KEY = { /** * @en The enter key * @zh 回车键 - * @property enter - * @type {Number} * @readonly */ 'enter': 13, @@ -106,8 +79,6 @@ const KEY = { /** * @en The shift key * @zh Shift 键 - * @property shift - * @type {Number} * @readonly */ 'shift': 16, // should use shiftkey instead @@ -115,8 +86,6 @@ const KEY = { /** * @en The ctrl key * @zh Ctrl 键 - * @property ctrl - * @type {Number} * @readonly */ 'ctrl': 17, // should use ctrlkey @@ -124,8 +93,6 @@ const KEY = { /** * @en The alt key * @zh Alt 键 - * @property alt - * @type {Number} * @readonly */ 'alt': 18, // should use altkey @@ -133,8 +100,6 @@ const KEY = { /** * @en The pause key * @zh 暂停键 - * @property pause - * @type {Number} * @readonly */ 'pause': 19, @@ -142,8 +107,6 @@ const KEY = { /** * @en The caps lock key * @zh 大写锁定键 - * @property capslock - * @type {Number} * @readonly */ 'capslock': 20, @@ -151,8 +114,6 @@ const KEY = { /** * @en The esc key * @zh ESC 键 - * @property escape - * @type {Number} * @readonly */ 'escape': 27, @@ -160,8 +121,6 @@ const KEY = { /** * @en The space key * @zh 空格键 - * @property space - * @type {Number} * @readonly */ 'space': 32, @@ -169,8 +128,6 @@ const KEY = { /** * @en The page up key * @zh 向上翻页键 - * @property pageup - * @type {Number} * @readonly */ 'pageup': 33, @@ -178,8 +135,6 @@ const KEY = { /** * @en The page down key * @zh 向下翻页键 - * @property pagedown - * @type {Number} * @readonly */ 'pagedown': 34, @@ -187,8 +142,6 @@ const KEY = { /** * @en The end key * @zh 结束键 - * @property end - * @type {Number} * @readonly */ 'end': 35, @@ -196,8 +149,6 @@ const KEY = { /** * @en The home key * @zh 主菜单键 - * @property home - * @type {Number} * @readonly */ 'home': 36, @@ -205,8 +156,6 @@ const KEY = { /** * @en The left key * @zh 向左箭头键 - * @property left - * @type {Number} * @readonly */ 'left': 37, @@ -214,8 +163,6 @@ const KEY = { /** * @en The up key * @zh 向上箭头键 - * @property up - * @type {Number} * @readonly */ 'up': 38, @@ -223,8 +170,6 @@ const KEY = { /** * @en The right key * @zh 向右箭头键 - * @property right - * @type {Number} * @readonly */ 'right': 39, @@ -232,8 +177,6 @@ const KEY = { /** * @en The down key * @zh 向下箭头键 - * @property down - * @type {Number} * @readonly */ 'down': 40, @@ -241,8 +184,6 @@ const KEY = { /** * @en The select key * @zh Select 键 - * @property select - * @type {Number} * @readonly */ 'select': 41, @@ -250,8 +191,6 @@ const KEY = { /** * @en The insert key * @zh 插入键 - * @property insert - * @type {Number} * @readonly */ 'insert': 45, @@ -259,8 +198,6 @@ const KEY = { /** * @en The Delete key * @zh 删除键 - * @property Delete - * @type {Number} * @readonly */ 'Delete': 46, @@ -268,8 +205,6 @@ const KEY = { /** * @en The '0' key on the top of the alphanumeric keyboard. * @zh 字母键盘上的 0 键 - * @property 0 - * @type {Number} * @readonly */ '0': 48, @@ -277,8 +212,6 @@ const KEY = { /** * @en The '1' key on the top of the alphanumeric keyboard. * @zh 字母键盘上的 1 键 - * @property 1 - * @type {Number} * @readonly */ '1': 49, @@ -286,8 +219,6 @@ const KEY = { /** * @en The '2' key on the top of the alphanumeric keyboard. * @zh 字母键盘上的 2 键 - * @property 2 - * @type {Number} * @readonly */ '2': 50, @@ -295,8 +226,6 @@ const KEY = { /** * @en The '3' key on the top of the alphanumeric keyboard. * @zh 字母键盘上的 3 键 - * @property 3 - * @type {Number} * @readonly */ '3': 51, @@ -304,8 +233,6 @@ const KEY = { /** * @en The '4' key on the top of the alphanumeric keyboard. * @zh 字母键盘上的 4 键 - * @property 4 - * @type {Number} * @readonly */ '4': 52, @@ -313,8 +240,6 @@ const KEY = { /** * @en The '5' key on the top of the alphanumeric keyboard. * @zh 字母键盘上的 5 键 - * @property 5 - * @type {Number} * @readonly */ '5': 53, @@ -322,8 +247,6 @@ const KEY = { /** * @en The '6' key on the top of the alphanumeric keyboard. * @zh 字母键盘上的 6 键 - * @property 6 - * @type {Number} * @readonly */ '6': 54, @@ -331,8 +254,6 @@ const KEY = { /** * @en The '7' key on the top of the alphanumeric keyboard. * @zh 字母键盘上的 7 键 - * @property 7 - * @type {Number} * @readonly */ '7': 55, @@ -340,8 +261,6 @@ const KEY = { /** * @en The '8' key on the top of the alphanumeric keyboard. * @zh 字母键盘上的 8 键 - * @property 8 - * @type {Number} * @readonly */ '8': 56, @@ -349,8 +268,6 @@ const KEY = { /** * @en The '9' key on the top of the alphanumeric keyboard. * @zh 字母键盘上的 9 键 - * @property 9 - * @type {Number} * @readonly */ '9': 57, @@ -358,8 +275,6 @@ const KEY = { /** * @en The a key * @zh A 键 - * @property a - * @type {Number} * @readonly */ 'a': 65, @@ -367,8 +282,6 @@ const KEY = { /** * @en The b key * @zh B 键 - * @property b - * @type {Number} * @readonly */ 'b': 66, @@ -376,8 +289,6 @@ const KEY = { /** * @en The c key * @zh C 键 - * @property c - * @type {Number} * @readonly */ 'c': 67, @@ -385,8 +296,6 @@ const KEY = { /** * @en The d key * @zh D 键 - * @property d - * @type {Number} * @readonly */ 'd': 68, @@ -394,8 +303,6 @@ const KEY = { /** * @en The e key * @zh E 键 - * @property e - * @type {Number} * @readonly */ 'e': 69, @@ -403,8 +310,6 @@ const KEY = { /** * @en The f key * @zh F 键 - * @property f - * @type {Number} * @readonly */ 'f': 70, @@ -412,8 +317,6 @@ const KEY = { /** * @en The g key * @zh G 键 - * @property g - * @type {Number} * @readonly */ 'g': 71, @@ -421,8 +324,6 @@ const KEY = { /** * @en The h key * @zh H 键 - * @property h - * @type {Number} * @readonly */ 'h': 72, @@ -430,8 +331,6 @@ const KEY = { /** * @en The i key * @zh I 键 - * @property i - * @type {Number} * @readonly */ 'i': 73, @@ -439,8 +338,6 @@ const KEY = { /** * @en The j key * @zh J 键 - * @property j - * @type {Number} * @readonly */ 'j': 74, @@ -448,8 +345,6 @@ const KEY = { /** * @en The k key * @zh K 键 - * @property k - * @type {Number} * @readonly */ 'k': 75, @@ -457,8 +352,6 @@ const KEY = { /** * @en The l key * @zh L 键 - * @property l - * @type {Number} * @readonly */ 'l': 76, @@ -466,8 +359,6 @@ const KEY = { /** * @en The m key * @zh M 键 - * @property m - * @type {Number} * @readonly */ 'm': 77, @@ -475,8 +366,6 @@ const KEY = { /** * @en The n key * @zh N 键 - * @property n - * @type {Number} * @readonly */ 'n': 78, @@ -484,8 +373,6 @@ const KEY = { /** * @en The o key * @zh O 键 - * @property o - * @type {Number} * @readonly */ 'o': 79, @@ -493,8 +380,6 @@ const KEY = { /** * @en The p key * @zh P 键 - * @property p - * @type {Number} * @readonly */ 'p': 80, @@ -502,8 +387,6 @@ const KEY = { /** * @en The q key * @zh Q 键 - * @property q - * @type {Number} * @readonly */ 'q': 81, @@ -511,8 +394,6 @@ const KEY = { /** * @en The r key * @zh R 键 - * @property r - * @type {Number} * @readonly */ 'r': 82, @@ -520,8 +401,6 @@ const KEY = { /** * @en The s key * @zh S 键 - * @property s - * @type {Number} * @readonly */ 's': 83, @@ -529,8 +408,6 @@ const KEY = { /** * @en The t key * @zh T 键 - * @property t - * @type {Number} * @readonly */ 't': 84, @@ -538,8 +415,6 @@ const KEY = { /** * @en The u key * @zh U 键 - * @property u - * @type {Number} * @readonly */ 'u': 85, @@ -547,8 +422,6 @@ const KEY = { /** * @en The v key * @zh V 键 - * @property v - * @type {Number} * @readonly */ 'v': 86, @@ -556,8 +429,6 @@ const KEY = { /** * @en The w key * @zh W 键 - * @property w - * @type {Number} * @readonly */ 'w': 87, @@ -565,8 +436,6 @@ const KEY = { /** * @en The x key * @zh X 键 - * @property x - * @type {Number} * @readonly */ 'x': 88, @@ -574,8 +443,6 @@ const KEY = { /** * @en The y key * @zh Y 键 - * @property y - * @type {Number} * @readonly */ 'y': 89, @@ -583,8 +450,6 @@ const KEY = { /** * @en The z key * @zh Z 键 - * @property z - * @type {Number} * @readonly */ 'z': 90, @@ -592,8 +457,6 @@ const KEY = { /** * @en The numeric keypad 0 * @zh 数字键盘 0 - * @property num0 - * @type {Number} * @readonly */ 'num0': 96, @@ -601,8 +464,6 @@ const KEY = { /** * @en The numeric keypad 1 * @zh 数字键盘 1 - * @property num1 - * @type {Number} * @readonly */ 'num1': 97, @@ -610,8 +471,6 @@ const KEY = { /** * @en The numeric keypad 2 * @zh 数字键盘 2 - * @property num2 - * @type {Number} * @readonly */ 'num2': 98, @@ -619,8 +478,6 @@ const KEY = { /** * @en The numeric keypad 3 * @zh 数字键盘 3 - * @property num3 - * @type {Number} * @readonly */ 'num3': 99, @@ -628,8 +485,6 @@ const KEY = { /** * @en The numeric keypad 4 * @zh 数字键盘 4 - * @property num4 - * @type {Number} * @readonly */ 'num4': 100, @@ -637,8 +492,6 @@ const KEY = { /** * @en The numeric keypad 5 * @zh 数字键盘 5 - * @property num5 - * @type {Number} * @readonly */ 'num5': 101, @@ -646,8 +499,6 @@ const KEY = { /** * @en The numeric keypad 6 * @zh 数字键盘 6 - * @property num6 - * @type {Number} * @readonly */ 'num6': 102, @@ -655,8 +506,6 @@ const KEY = { /** * @en The numeric keypad 7 * @zh 数字键盘 7 - * @property num7 - * @type {Number} * @readonly */ 'num7': 103, @@ -664,8 +513,6 @@ const KEY = { /** * @en The numeric keypad 8 * @zh 数字键盘 8 - * @property num8 - * @type {Number} * @readonly */ 'num8': 104, @@ -673,8 +520,6 @@ const KEY = { /** * @en The numeric keypad 9 * @zh 数字键盘 9 - * @property num9 - * @type {Number} * @readonly */ 'num9': 105, @@ -682,8 +527,6 @@ const KEY = { /** * @en The numeric keypad '*' * @zh 数字键盘 * - * @property * - * @type {Number} * @readonly */ '*': 106, @@ -691,8 +534,6 @@ const KEY = { /** * @en The numeric keypad '+' * @zh 数字键盘 + - * @property + - * @type {Number} * @readonly */ '+': 107, @@ -700,8 +541,6 @@ const KEY = { /** * @en The numeric keypad '-' * @zh 数字键盘 - - * @property - - * @type {Number} * @readonly */ '-': 109, @@ -709,8 +548,6 @@ const KEY = { /** * @en The numeric keypad 'delete' * @zh 数字键盘删除键 - * @property numdel - * @type {Number} * @readonly */ 'numdel': 110, @@ -718,8 +555,6 @@ const KEY = { /** * @en The numeric keypad '/' * @zh 数字键盘 / - * @property / - * @type {Number} * @readonly */ '/': 111, @@ -727,8 +562,6 @@ const KEY = { /** * @en The F1 function key * @zh F1 功能键 - * @property f1 - * @type {Number} * @readonly */ 'f1': 112, // f1-f12 dont work on ie @@ -736,8 +569,6 @@ const KEY = { /** * @en The F2 function key * @zh F2 功能键 - * @property f2 - * @type {Number} * @readonly */ 'f2': 113, @@ -745,8 +576,6 @@ const KEY = { /** * @en The F3 function key * @zh F3 功能键 - * @property f3 - * @type {Number} * @readonly */ 'f3': 114, @@ -754,8 +583,6 @@ const KEY = { /** * @en The F4 function key * @zh F4 功能键 - * @property f4 - * @type {Number} * @readonly */ 'f4': 115, @@ -763,8 +590,6 @@ const KEY = { /** * @en The F5 function key * @zh F5 功能键 - * @property f5 - * @type {Number} * @readonly */ 'f5': 116, @@ -772,8 +597,6 @@ const KEY = { /** * @en The F6 function key * @zh F6 功能键 - * @property f6 - * @type {Number} * @readonly */ 'f6': 117, @@ -781,8 +604,6 @@ const KEY = { /** * @en The F7 function key * @zh F7 功能键 - * @property f7 - * @type {Number} * @readonly */ 'f7': 118, @@ -790,8 +611,6 @@ const KEY = { /** * @en The F8 function key * @zh F8 功能键 - * @property f8 - * @type {Number} * @readonly */ 'f8': 119, @@ -799,8 +618,6 @@ const KEY = { /** * @en The F9 function key * @zh F9 功能键 - * @property f9 - * @type {Number} * @readonly */ 'f9': 120, @@ -808,8 +625,6 @@ const KEY = { /** * @en The F10 function key * @zh F10 功能键 - * @property f10 - * @type {Number} * @readonly */ 'f10': 121, @@ -817,8 +632,6 @@ const KEY = { /** * @en The F11 function key * @zh F11 功能键 - * @property f11 - * @type {Number} * @readonly */ 'f11': 122, @@ -826,8 +639,6 @@ const KEY = { /** * @en The F12 function key * @zh F12 功能键 - * @property f12 - * @type {Number} * @readonly */ 'f12': 123, @@ -835,8 +646,6 @@ const KEY = { /** * @en The numlock key * @zh 数字锁定键 - * @property numlock - * @type {Number} * @readonly */ 'numlock': 144, @@ -844,8 +653,6 @@ const KEY = { /** * @en The scroll lock key * @zh 滚动锁定键 - * @property scrolllock - * @type {Number} * @readonly */ 'scrolllock': 145, @@ -853,8 +660,6 @@ const KEY = { /** * @en The ';' key. * @zh 分号键 - * @property ; - * @type {Number} * @readonly */ ';': 186, @@ -862,8 +667,6 @@ const KEY = { /** * @en The ';' key. * @zh 分号键 - * @property semicolon - * @type {Number} * @readonly */ 'semicolon': 186, @@ -871,8 +674,6 @@ const KEY = { /** * @en The '=' key. * @zh 等于号键 - * @property equal - * @type {Number} * @readonly */ 'equal': 187, @@ -880,8 +681,6 @@ const KEY = { /** * @en The '=' key. * @zh 等于号键 - * @property = - * @type {Number} * @readonly */ '=': 187, @@ -889,8 +688,6 @@ const KEY = { /** * @en The ',' key. * @zh 逗号键 - * @property , - * @type {Number} * @readonly */ ',': 188, @@ -898,8 +695,6 @@ const KEY = { /** * @en The ',' key. * @zh 逗号键 - * @property comma - * @type {Number} * @readonly */ 'comma': 188, @@ -907,8 +702,6 @@ const KEY = { /** * @en The dash '-' key. * @zh 中划线键 - * @property dash - * @type {Number} * @readonly */ 'dash': 189, @@ -916,8 +709,6 @@ const KEY = { /** * @en The '.' key. * @zh 句号键 - * @property . - * @type {Number} * @readonly */ '.': 190, @@ -925,8 +716,6 @@ const KEY = { /** * @en The '.' key * @zh 句号键 - * @property period - * @type {Number} * @readonly */ 'period': 190, @@ -934,8 +723,6 @@ const KEY = { /** * @en The forward slash key * @zh 正斜杠键 - * @property forwardslash - * @type {Number} * @readonly */ 'forwardslash': 191, @@ -943,8 +730,6 @@ const KEY = { /** * @en The grave key * @zh 按键 ` - * @property grave - * @type {Number} * @readonly */ 'grave': 192, @@ -952,8 +737,6 @@ const KEY = { /** * @en The '[' key * @zh 按键 [ - * @property [ - * @type {Number} * @readonly */ '[': 219, @@ -961,8 +744,6 @@ const KEY = { /** * @en The '[' key * @zh 按键 [ - * @property openbracket - * @type {Number} * @readonly */ 'openbracket': 219, @@ -970,8 +751,6 @@ const KEY = { /** * @en The '\' key * @zh 反斜杠键 - * @property backslash - * @type {Number} * @readonly */ 'backslash': 220, @@ -979,8 +758,6 @@ const KEY = { /** * @en The ']' key * @zh 按键 ] - * @property ] - * @type {Number} * @readonly */ ']': 221, @@ -988,8 +765,6 @@ const KEY = { /** * @en The ']' key * @zh 按键 ] - * @property closebracket - * @type {Number} * @readonly */ 'closebracket': 221, @@ -997,8 +772,6 @@ const KEY = { /** * @en The quote key * @zh 单引号键 - * @property quote - * @type {Number} * @readonly */ 'quote': 222, @@ -1008,8 +781,6 @@ const KEY = { /** * @en The dpad left key * @zh 导航键 向左 - * @property dpadLeft - * @type {Number} * @readonly */ 'dpadLeft': 1000, @@ -1017,8 +788,6 @@ const KEY = { /** * @en The dpad right key * @zh 导航键 向右 - * @property dpadRight - * @type {Number} * @readonly */ 'dpadRight': 1001, @@ -1026,8 +795,6 @@ const KEY = { /** * @en The dpad up key * @zh 导航键 向上 - * @property dpadUp - * @type {Number} * @readonly */ 'dpadUp': 1003, @@ -1035,8 +802,6 @@ const KEY = { /** * @en The dpad down key * @zh 导航键 向下 - * @property dpadDown - * @type {Number} * @readonly */ 'dpadDown': 1004, @@ -1044,247 +809,74 @@ const KEY = { /** * @en The dpad center key * @zh 导航键 确定键 - * @property dpadCenter - * @type {Number} * @readonly */ 'dpadCenter': 1005, }; /** - * Image formats - * @enum macro.ImageFormat + * @en + * Predefined constants + * @zh + * 预定义常量。 */ -const ImageFormat = cc.Enum({ - /** - * Image Format:JPG - * @property JPG - * @type {Number} - */ - JPG: 0, - /** - * Image Format:PNG - * @property PNG - * @type {Number} - */ - PNG: 1, - /** - * Image Format:TIFF - * @property TIFF - * @type {Number} - */ - TIFF: 2, - /** - * Image Format:WEBP - * @property WEBP - * @type {Number} - */ - WEBP: 3, - /** - * Image Format:PVR - * @property PVR - * @type {Number} - */ - PVR: 4, - /** - * Image Format:ETC - * @property ETC - * @type {Number} - */ - ETC: 5, - /** - * Image Format:S3TC - * @property S3TC - * @type {Number} - */ - S3TC: 6, - /** - * Image Format:ATITC - * @property ATITC - * @type {Number} - */ - ATITC: 7, - /** - * Image Format:TGA - * @property TGA - * @type {Number} - */ - TGA: 8, - /** - * Image Format:RAWDATA - * @property RAWDATA - * @type {Number} - */ - RAWDATA: 9, - /** - * Image Format:UNKNOWN - * @property UNKNOWN - * @type {Number} - */ - UNKNOWN: 10, -}); - -// /** -// * @en -// * Enum for blend factor -// * Refer to: http://www.andersriggelsen.dk/glblendfunc.php -// * @zh -// * 混合因子 -// * 可参考: http://www.andersriggelsen.dk/glblendfunc.php -// * @enum macro.BlendFactor -// */ -// const BlendFactor = cc.Enum({ -// /** -// * @en All use -// * @zh 全部使用 -// * @property {Number} ONE -// */ -// ONE: 1, // cc.macro.ONE -// /** -// * @en Not all -// * @zh 全部不用 -// * @property {Number} ZERO -// */ -// ZERO: 0, // cc.ZERO -// /** -// * @en Using the source alpha -// * @zh 使用源颜色的透明度 -// * @property {Number} SRC_ALPHA -// */ -// SRC_ALPHA: 0x302, // cc.SRC_ALPHA -// /** -// * @en Using the source color -// * @zh 使用源颜色 -// * @property {Number} SRC_COLOR -// */ -// SRC_COLOR: 0x300, // cc.SRC_COLOR -// /** -// * @en Using the target alpha -// * @zh 使用目标颜色的透明度 -// * @property {Number} DST_ALPHA -// */ -// DST_ALPHA: 0x304, // cc.DST_ALPHA -// /** -// * @en Using the target color -// * @zh 使用目标颜色 -// * @property {Number} DST_COLOR -// */ -// DST_COLOR: 0x306, // cc.DST_COLOR -// /** -// * @en Minus the source alpha -// * @zh 减去源颜色的透明度 -// * @property {Number} ONE_MINUS_SRC_ALPHA -// */ -// ONE_MINUS_SRC_ALPHA: 0x303, // cc.ONE_MINUS_SRC_ALPHA -// /** -// * @en Minus the source color -// * @zh 减去源颜色 -// * @property {Number} ONE_MINUS_SRC_COLOR -// */ -// ONE_MINUS_SRC_COLOR: 0x301, // cc.ONE_MINUS_SRC_COLOR -// /** -// * @en Minus the target alpha -// * @zh 减去目标颜色的透明度 -// * @property {Number} ONE_MINUS_DST_ALPHA -// */ -// ONE_MINUS_DST_ALPHA: 0x305, // cc.ONE_MINUS_DST_ALPHA -// /** -// * @en Minus the target color -// * @zh 减去目标颜色 -// * @property {Number} ONE_MINUS_DST_COLOR -// */ -// ONE_MINUS_DST_COLOR: 0x307, // cc.ONE_MINUS_DST_COLOR -// }); - -/** - * @module macro - */ - const macro = { /** - * !en + * @en * The image format supported by the engine defaults, and the supported formats may differ in different build platforms and device types. * Currently all platform and device support ['.webp', '.jpg', '.jpeg', '.bmp', '.png'], ios mobile platform - * !zh + * @zh * 引擎默认支持的图片格式,支持的格式可能在不同的构建平台和设备类型上有所差别。 * 目前所有平台和设备支持的格式有 ['.webp', '.jpg', '.jpeg', '.bmp', '.png']. The iOS mobile platform also supports the PVR format。 - * @property {[String]} SUPPORT_TEXTURE_FORMATS */ SUPPORT_TEXTURE_FORMATS, + /** + * @en Key map for keyboard event + * @zh 键盘事件的按键值。 + * @example {@link cocos/core/platform/CCCommon/KEY.js} + */ KEY, - ImageFormat, - /** * PI / 180 - * @property RAD - * @type {Number} */ RAD: Math.PI / 180, /** * One degree - * @property DEG - * @type {Number} */ DEG: 180 / Math.PI, /** - * @property REPEAT_FOREVER - * @type {Number} + * A maximum value of number */ REPEAT_FOREVER: (Number.MAX_VALUE - 1), /** - * @property FLT_EPSILON - * @type {Number} + * A minimal float value */ FLT_EPSILON: 0.0000001192092896, - /** - * Minimum z index value for node - * @property MIN_ZINDEX - * @type {Number} - */ - MIN_ZINDEX: -Math.pow(2, 15), - - /** - * Maximum z index value for node - * @property MAX_ZINDEX - * @type {Number} - */ - MAX_ZINDEX: Math.pow(2, 15) - 1, - // Possible device orientations /** - * Oriented vertically - * @property ORIENTATION_PORTRAIT - * @type {Number} + * @en Oriented vertically + * @zh 竖屏朝向 */ ORIENTATION_PORTRAIT: 1, /** - * Oriented horizontally - * @property ORIENTATION_LANDSCAPE - * @type {Number} + * @en Oriented horizontally + * @zh 横屏朝向 */ ORIENTATION_LANDSCAPE: 2, /** - * Oriented automatically - * @property ORIENTATION_AUTO - * @type {Number} + * @en Oriented automatically + * @zh 自动适配朝向 */ ORIENTATION_AUTO: 3, - DENSITYDPI_DEVICE: 'device-dpi', - DENSITYDPI_HIGH: 'high-dpi', - DENSITYDPI_MEDIUM: 'medium-dpi', - DENSITYDPI_LOW: 'low-dpi', - - // General configurations - /** *

* If enabled, the texture coordinates will be calculated by using this formula:
@@ -1297,32 +889,33 @@ const macro = { * The "correct" way to prevent artifacts is by expand the texture's border with the same color by 1 pixel
*
* Affected component:
- * - cc.TMXLayer
+ * - TMXLayer
*
* Enabled by default. To disabled set it to 0.
* To modify it, in Web engine please refer to CCMacro.js, in JSB please refer to CCConfig.h *

- * - * @property {Number} FIX_ARTIFACTS_BY_STRECHING_TEXEL_TMX + * Currently not useful in 3D engine */ FIX_ARTIFACTS_BY_STRECHING_TEXEL_TMX: true, /** - * Position of the FPS (Default: 0,0 (bottom-left corner))
- * To modify it, in Web engine please refer to CCMacro.js, in JSB please refer to CCConfig.h - * @property {Vec2} DIRECTOR_STATS_POSITION + * @en + * Whether or not enabled tiled map auto culling. If you set the TiledMap skew or rotation, + * then need to manually disable this, otherwise, the rendering will be wrong. + * Currently not useful in 3D engine + * @zh + * 是否开启瓦片地图的自动裁减功能。瓦片地图如果设置了 skew, rotation 的话,需要手动关闭,否则渲染会出错。 + * 在 3D 引擎中暂时无效。 + * @default true */ - DIRECTOR_STATS_POSITION: new Vec2(0, 0), + ENABLE_TILEDMAP_CULLING: true, /** - *

- * If enabled, actions that alter the position property (eg: CCMoveBy, CCJumpBy, CCBezierBy, etc..) will be stacked.
- * If you run 2 or more 'position' actions at the same time on a node, then end position will be the sum of all the positions.
- * If disabled, only the last run action will take effect. - *

- * @property {Number} ENABLE_STACKABLE_ACTIONS + * @en Position of the FPS (Default: 0,0 (bottom-left corner))
+ * Currently not useful in 3D engine + * @zh 在 3D 引擎中暂时无效。 */ - ENABLE_STACKABLE_ACTIONS: true, + DIRECTOR_STATS_POSITION: new Vec2(0, 0), /** * @en @@ -1342,36 +935,15 @@ const macro = { * 所以这个新的机制可以在触点在一定时间内没有任何更新的情况下视为失效触点并从事件系统中移除。 * 当然,这也可能移除一个真实的触点,如果用户的触点真的在一定时间段内完全没有移动(这在当前手机屏幕的灵敏度下会很难)。 * 你可以修改这个值来获得你需要的效果,默认值是 5000 毫秒。 - * @property {Number} TOUCH_TIMEOUT + * @default 5000 */ TOUCH_TIMEOUT: 5000, - /** - * @en - * The maximum vertex count for a single batched draw call. - * @zh - * 最大可以被单次批处理渲染的顶点数量。 - * @property {Number} BATCH_VERTEX_COUNT - */ - BATCH_VERTEX_COUNT: 20000, - - /** - * @en - * Whether or not enabled tiled map auto culling. If you set the TiledMap skew or rotation, - * then need to manually disable this, otherwise, the rendering will be wrong. - * @zh - * 是否开启瓦片地图的自动裁减功能。瓦片地图如果设置了 skew, rotation 的话,需要手动关闭,否则渲染会出错。 - * @property {Boolean} ENABLE_TILEDMAP_CULLING - * @default true - */ - ENABLE_TILEDMAP_CULLING: true, - /** * @en * The max concurrent task number for the downloader * @zh * 下载任务的最大并发数限制,在安卓平台部分机型或版本上可能需要限制在较低的水平 - * @property {Number} DOWNLOAD_MAX_CONCURRENT * @default 64 */ DOWNLOAD_MAX_CONCURRENT: 64, @@ -1380,13 +952,12 @@ const macro = { * @en * Boolean that indicates if the canvas contains an alpha channel, default sets to false for better performance. * Though if you want to make your canvas background transparent and show other dom elements at the background, - * you can set it to true before `cc.game.run`. + * you can set it to true before {{game.init}}. * Web only. * @zh * 用于设置 Canvas 背景是否支持 alpha 通道,默认为 false,这样可以有更高的性能表现。 - * 如果你希望 Canvas 背景是透明的,并显示背后的其他 DOM 元素,你可以在 `cc.game.run` 之前将这个值设为 true。 + * 如果你希望 Canvas 背景是透明的,并显示背后的其他 DOM 元素,你可以在 {{game.init}} 之前将这个值设为 true。 * 仅支持 Web - * @property {Boolean} ENABLE_TRANSPARENT_CANVAS * @default false */ ENABLE_TRANSPARENT_CANVAS: false, @@ -1399,38 +970,20 @@ const macro = { * device with retina display usually have good detail on graphics with or without this option, * you probably don't want antialias if your game style is pixel art based. * Also, it could have great performance impact with some browser / device using software MSAA. - * You can set it to true before `cc.game.run`. + * You can set it to true before {{game.init}}. * Web only. * @zh * 用于设置在创建 WebGL Context 时是否开启抗锯齿选项,默认值是 false。 * 将这个选项设置为 true 会让你的游戏画面稍稍平滑一些,比如旋转硬边贴图时的锯齿。是否开启这个选项很大程度上取决于你的游戏和面向的平台。 * 在大多数拥有 retina 级别屏幕的设备上用户往往无法区分这个选项带来的变化;如果你的游戏选择像素艺术风格,你也多半不会想开启这个选项。 * 同时,在少部分使用软件级别抗锯齿算法的设备或浏览器上,这个选项会对性能产生比较大的影响。 - * 你可以在 `cc.game.run` 之前设置这个值,否则它不会生效。 + * 你可以在 {{game.init}} 之前设置这个值,否则它不会生效。 * 仅支持 Web * @property {Boolean} ENABLE_WEBGL_ANTIALIAS * @default false */ ENABLE_WEBGL_ANTIALIAS: false, - /** - * @en - * Whether or not enable auto culling. - * This feature have been removed in v2.0 new renderer due to overall performance consumption. - * We have no plan currently to re-enable auto culling. - * If your game have more dynamic objects, we suggest to disable auto culling. - * If your game have more static objects, we suggest to enable auto culling. - * @zh - * 是否开启自动裁减功能,开启裁减功能将会把在屏幕外的物体从渲染队列中去除掉。 - * 这个功能在 v2.0 的新渲染器中被移除了,因为它在大多数游戏中所带来的损耗要高于性能的提升,目前我们没有计划重新支持自动裁剪。 - * 如果游戏中的动态物体比较多的话,建议将此选项关闭。 - * 如果游戏中的静态物体比较多的话,建议将此选项打开。 - * @property {Boolean} ENABLE_CULLING - * @deprecated since v2.0 - * @default false - */ - ENABLE_CULLING: false, - /** * @en * Whether or not clear dom Image object cache after uploading to gl texture. @@ -1438,27 +991,18 @@ const macro = { * Normally you don't need to enable this option, because on web the Image object doesn't consume too much memory. * But on Wechat Game platform, the current version cache decoded data in Image object, which has high memory usage. * So we enabled this option by default on Wechat, so that we can release Image cache immediately after uploaded to GPU. + * Currently not useful in 3D engine * @zh * 是否在将贴图上传至 GPU 之后删除 DOM Image 缓存。 * 具体来说,我们通过设置 image.src 为空字符串来释放这部分内存。 * 正常情况下,你不需要开启这个选项,因为在 web 平台,Image 对象所占用的内存很小。 * 但是在微信小游戏平台的当前版本,Image 对象会缓存解码后的图片数据,它所占用的内存空间很大。 * 所以我们在微信平台默认开启了这个选项,这样我们就可以在上传 GL 贴图之后立即释放 Image 对象的内存,避免过高的内存占用。 - * @property {Boolean} CLEANUP_IMAGE_CACHE + * 在 3D 引擎中暂时无效。 * @default false */ CLEANUP_IMAGE_CACHE: false, - /** - * @en - * Whether or not show mesh wire frame. - * @zh - * 是否显示网格的线框。 - * @property {Boolean} SHOW_MESH_WIREFRAME - * @default false - */ - SHOW_MESH_WIREFRAME: false, - /** * @en * Whether to enable multi-touch. diff --git a/cocos/core/platform/screen.ts b/cocos/core/platform/screen.ts index 5e88c087ce..0d2462c273 100644 --- a/cocos/core/platform/screen.ts +++ b/cocos/core/platform/screen.ts @@ -28,12 +28,10 @@ * @category core */ -// tslint:disable - /** - * The fullscreen API provides an easy way for web content to be presented using the user's entire screen. - * It's invalid on safari, QQbrowser and android browser - * @class screen + * @en The screen API provides an easy way for web content to be presented using the user's entire screen. + * It's designed for web platforms and some mobile browsers don't provide such behavior, e.g. Safari + * @zh screen 单例对象提供简单的方法来尝试让 Web 内容进入全屏模式。这是 Web 平台特有的行为,在部分浏览器上并不支持这样的功能。 */ const screen = { _supportsFullScreen: false, @@ -81,8 +79,8 @@ const screen = { ], /** - * initialize - * @method init + * @en Initialization + * @zh 初始化函数 */ init () { this._fn = {}; @@ -102,8 +100,8 @@ const screen = { }, /** - * return true if it's full now. - * @method fullScreen + * @en Return true if it's in full screen state now. + * @zh 当前是否处在全屏状态下 * @returns {Boolean} */ fullScreen () { @@ -117,12 +115,15 @@ const screen = { }, /** - * change the screen to full mode. - * @method requestFullScreen - * @param {Element} element - * @param {Function} onFullScreenChange + * @en Request to enter full screen mode with the given element. + * Many browser forbid to enter full screen mode without an user intended interaction. + * For simplify the process, you can try to use {{autoFullScreen}} which will try to enter full screen mode during the next user touch event. + * @zh 尝试使当前节点进入全屏模式,很多浏览器不允许程序触发这样的行为,必须在一个用户交互回调中才会生效。 + * 如果希望更简单一些,可以尝试用 {{autoFullScreen}} 来自动监听用户触摸事件并在下一次触摸事件中尝试进入全屏模式。 + * @param element The element to request full screen state + * @param onFullScreenChange callback function when full screen state changed */ - requestFullScreen (element, onFullScreenChange) { + requestFullScreen (element: HTMLElement, onFullScreenChange: (this: Document, ev: any) => any) { if (!this._supportsFullScreen) { return; } @@ -142,21 +143,21 @@ const screen = { }, /** - * exit the full mode. - * @method exitFullScreen - * @return {Boolean} + * @en Exit the full mode. + * @zh 退出全屏模式 + * @return Success or not */ - exitFullScreen () { + exitFullScreen (): boolean { return this._supportsFullScreen ? document[this._fn.exitFullscreen]() : true; }, /** - * Automatically request full screen with a touch/click event - * @method autoFullScreen - * @param {Element} element - * @param {Function} onFullScreenChange + * @en Automatically request full screen during the next touch/click event + * @zh 自动监听触摸、鼠标事件并在下一次事件触发时尝试进入全屏模式 + * @param element The element to request full screen state + * @param onFullScreenChange callback function when full screen state changed */ - autoFullScreen (element, onFullScreenChange) { + autoFullScreen (element: HTMLElement, onFullScreenChange: (this: Document, ev: any) => any) { element = element || document.body; const touchTarget = cc.game.canvas || element; const theScreen = this; diff --git a/cocos/core/platform/sys.ts b/cocos/core/platform/sys.ts index 82284d9766..ad81c45272 100644 --- a/cocos/core/platform/sys.ts +++ b/cocos/core/platform/sys.ts @@ -23,6 +23,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ + /** * @category core */ @@ -31,535 +32,687 @@ import { EDITOR, TEST, WECHAT, ALIPAY, XIAOMI, BAIDU, COCOSPLAY, JSB, MINIGAME } // tslint:disable -/** - * System variables - * @class sys - * @main - * @static - */ -const sys: { [x: string]: any; } = {}; - // @ts-ignore const _global = typeof window === 'undefined' ? global : window; -/** - * English language code - * @property {String} LANGUAGE_ENGLISH - * @readOnly - */ -sys.LANGUAGE_ENGLISH = 'en'; +enum NetworkType { + /** + * @en Network is unreachable. + * @zh 网络不通 + */ + NONE, + /** + * @en Network is reachable via WiFi or cable. + * @zh 通过无线或者有线本地网络连接因特网 + */ + LAN, + /** + * @en Network is reachable via Wireless Wide Area Network + * @zh 通过蜂窝移动网络连接因特网 + */ + WWAN +}; /** - * Chinese language code - * @property {String} LANGUAGE_CHINESE - * @readOnly + * @en A set of system related variables + * @zh 一系列系统相关环境变量 + * @main */ -sys.LANGUAGE_CHINESE = 'zh'; +export const sys: { [x: string]: any; } = { + /** + * @en + * Network type enumeration + * @zh + * 网络类型枚举 + */ + NetworkType, -/** - * French language code - * @property {String} LANGUAGE_FRENCH - * @readOnly - */ -sys.LANGUAGE_FRENCH = 'fr'; + /** + * @en English language code + * @zh 语言代码 - 英语 + */ + LANGUAGE_ENGLISH: 'en', + + /** + * @en Chinese language code + * @zh 语言代码 - 中文 + */ + LANGUAGE_CHINESE: 'zh', + + /** + * @en French language code + * @zh 语言代码 - 法语 + */ + LANGUAGE_FRENCH: 'fr', + + /** + * @en Italian language code + * @zh 语言代码 - 意大利语 + */ + LANGUAGE_ITALIAN: 'it', + + /** + * @en German language code + * @zh 语言代码 - 德语 + */ + LANGUAGE_GERMAN: 'de', + + /** + * @en Spanish language code + * @zh 语言代码 - 西班牙语 + */ + LANGUAGE_SPANISH: 'es', + + /** + * @en Spanish language code + * @zh 语言代码 - 荷兰语 + */ + LANGUAGE_DUTCH: 'du', + + /** + * @en Russian language code + * @zh 语言代码 - 俄罗斯语 + */ + LANGUAGE_RUSSIAN: 'ru', + + /** + * @en Korean language code + * @zh 语言代码 - 韩语 + */ + LANGUAGE_KOREAN: 'ko', + + /** + * @en Japanese language code + * @zh 语言代码 - 日语 + */ + LANGUAGE_JAPANESE: 'ja', + + /** + * @en Hungarian language code + * @zh 语言代码 - 匈牙利语 + */ + LANGUAGE_HUNGARIAN: 'hu', + + /** + * @en Portuguese language code + * @zh 语言代码 - 葡萄牙语 + */ + LANGUAGE_PORTUGUESE: 'pt', + + /** + * @en Arabic language code + * @zh 语言代码 - 阿拉伯语 + */ + LANGUAGE_ARABIC: 'ar', + + /** + * @en Norwegian language code + * @zh 语言代码 - 挪威语 + */ + LANGUAGE_NORWEGIAN: 'no', + + /** + * @en Polish language code + * @zh 语言代码 - 波兰语 + */ + LANGUAGE_POLISH: 'pl', + + /** + * @en Turkish language code + * @zh 语言代码 - 土耳其语 + */ + LANGUAGE_TURKISH: 'tr', + + /** + * @en Ukrainian language code + * @zh 语言代码 - 乌克兰语 + */ + LANGUAGE_UKRAINIAN: 'uk', + + /** + * @en Romanian language code + * @zh 语言代码 - 罗马尼亚语 + */ + LANGUAGE_ROMANIAN: 'ro', + + /** + * @en Bulgarian language code + * @zh 语言代码 - 保加利亚语 + */ + LANGUAGE_BULGARIAN: 'bg', + + /** + * @en Unknown language code + * @zh 语言代码 - 未知 + */ + LANGUAGE_UNKNOWN: 'unknown', + + /** + * @en Operating System - iOS + * @zh 操作系统 - iOS + */ + OS_IOS: 'iOS', + /** + * @en Operating System - Android + * @zh 操作系统 - 安卓 + */ + OS_ANDROID: 'Android', + /** + * @en Operating System - Windows + * @zh 操作系统 - Windows + */ + OS_WINDOWS: 'Windows', + /** + * @en Operating System - Linux + * @zh 操作系统 - Linux + */ + OS_LINUX: 'Linux', + /** + * @en Operating System - Mac OS X + * @zh 操作系统 - Mac OS X + */ + OS_OSX: 'OS X', + /** + * @en Operating System - Unknown + * @zh 操作系统 - 未知 + */ + OS_UNKNOWN: 'Unknown', + + /** + * @en Platform - Unknown + * @zh 平台 - 未知 + * @default -1 + */ + UNKNOWN: -1, + /** + * @en Platform - 32 bit Windows application + * @zh 平台 - 32位 Windows 可执行程序 + * @default 0 + */ + WIN32: 0, + /** + * @en Platform - Linux + * @zh 平台 - Linux + * @default 1 + */ + LINUX: 1, + /** + * @en Platform - Mac OS X app + * @zh 平台 - Mac OS X 原生平台 + * @default 2 + */ + MACOS: 2, + /** + * @en Platform - Android native app + * @zh 平台 - 安卓原生平台 + * @default 3 + */ + ANDROID: 3, + /** + * @en Platform - iPhone native app + * @zh 平台 - iPhone 原生平台 + * @default 4 + */ + IPHONE: 4, + /** + * @en Platform - iPad native app + * @zh 平台 - iPad 原生平台 + * @default 5 + */ + IPAD: 5, + /** + * @en Platform - Blackberry devices + * @zh 平台 - 黑莓设备 + * @default 6 + */ + BLACKBERRY: 6, + /** + * @en Platform - NACL + * @zh 平台 - NACL + * @default 7 + */ + NACL: 7, + /** + * @en Platform - Emscripten compiled runtime + * @zh 平台 - 编译为 Emscripten 的运行时环境 + * @default 8 + */ + EMSCRIPTEN: 8, + /** + * @en Platform - Tizen + * @zh 平台 - Tizen + * @default 9 + */ + TIZEN: 9, + /** + * @en Platform - Windows RT + * @zh 平台 - Windows RT + * @default 10 + */ + WINRT: 10, + /** + * @en Platform - Windows Phone 8 app + * @zh 平台 - Windows Phone 8 原生应用 + * @default 11 + */ + WP8: 11, + /** + * @en Platform - Mobile browsers + * @zh 平台 - 移动浏览器 + * @default 100 + */ + MOBILE_BROWSER: 100, + /** + * @en Platform - Desktop browsers + * @zh 平台 - 桌面端浏览器 + * @default 101 + */ + DESKTOP_BROWSER: 101, + /** + * @en Platform - Editor's window process + * @zh 平台 - 编辑器窗口进程 + * @default 102 + */ + EDITOR_PAGE: 102, + /** + * @en Platform - Editor's main process + * @zh 平台 - 编辑器主进程 + * @default 103 + */ + EDITOR_CORE: 103, + /** + * @en Platform - WeChat Mini Game + * @zh 平台 - 微信小游戏 + * @default 104 + */ + WECHAT_GAME: 104, + /** + * @en Platform - QQ Play Game + * @zh 平台 - QQ Play + * @default 105 + */ + QQ_PLAY: 105, -/** - * Italian language code - * @property {String} LANGUAGE_ITALIAN - * @readOnly - */ -sys.LANGUAGE_ITALIAN = 'it'; + /** + * @en Browser Type - WeChat inner browser + * @zh 浏览器类型 - 微信内置浏览器 + * @default "wechat" + */ + BROWSER_TYPE_WECHAT: 'wechat', + /** + * @en Browser Type - WeChat Mini Game + * @zh 浏览器类型 - 微信小游戏 + * @default "wechatgame" + */ + BROWSER_TYPE_WECHAT_GAME: 'wechatgame', + /** + * @en Browser Type - Alipay Mini Game + * @zh 浏览器类型 - 支付宝小游戏 + * @default "alipaygame" + */ + BROWSER_TYPE_ALIPAY_GAME: 'alipaygame', + /** + * @en Browser Type - MI Quick Game + * @zh 浏览器类型 - 小米快游戏 + * @default "xiaomiquickgame" + */ + BROWSER_TYPE_XIAOMI_GAME: 'xiaomiquickgame', + /** + * @en Browser Type - Baidu Mini Game + * @zh 浏览器类型 - 百度小游戏 + * @default "baidugame" + */ + BROWSER_TYPE_BAIDU_GAME: 'baidugame', + /** + * @en Browser Type - Cocos Play Game + * @zh 浏览器类型 - Cocos Play 游戏 + * @default "cocosplay" + */ + BROWSER_TYPE_COCOSPLAY: 'cocosplay', + /** + * @en Browser Type - Android Browser + * @zh 浏览器类型 - 安卓浏览器 + * @default "androidbrowser" + */ + BROWSER_TYPE_ANDROID: 'androidbrowser', + /** + * @en Browser Type - Internet Explorer + * @zh 浏览器类型 - 微软 IE + * @default "ie" + */ + BROWSER_TYPE_IE: 'ie', + /** + * @en Browser Type - QQ Browser + * @zh 浏览器类型 - QQ 浏览器 + * @default "qqbrowser" + */ + BROWSER_TYPE_QQ: 'qqbrowser', + /** + * @en Browser Type - Mobile QQ Browser + * @zh 浏览器类型 - 手机 QQ 浏览器 + * @default "mqqbrowser" + */ + BROWSER_TYPE_MOBILE_QQ: 'mqqbrowser', + /** + * @en Browser Type - UC Browser + * @zh 浏览器类型 - UC 浏览器 + * @default "ucbrowser" + */ + BROWSER_TYPE_UC: 'ucbrowser', + /** + * @en Browser Type - Third party integrated UC browser + * @zh 浏览器类型 - 第三方应用中集成的 UC 浏览器 + * @default "ucbs" + */ + BROWSER_TYPE_UCBS: 'ucbs', + /** + * @en Browser Type - 360 Browser + * @zh 浏览器类型 - 360 浏览器 + * @default "360browser" + */ + BROWSER_TYPE_360: '360browser', + /** + * @en Browser Type - Baidu Box App + * @zh 浏览器类型 - Baidu Box App + * @default "baiduboxapp" + */ + BROWSER_TYPE_BAIDU_APP: 'baiduboxapp', + /** + * @en Browser Type - Baidu Browser + * @zh 浏览器类型 - 百度浏览器 + * @default "baidubrowser" + */ + BROWSER_TYPE_BAIDU: 'baidubrowser', + /** + * @en Browser Type - Maxthon Browser + * @zh 浏览器类型 - 傲游浏览器 + * @default "maxthon" + */ + BROWSER_TYPE_MAXTHON: 'maxthon', + /** + * @en Browser Type - Opera Browser + * @zh 浏览器类型 - Opera 浏览器 + * @default "opera" + */ + BROWSER_TYPE_OPERA: 'opera', + /** + * @en Browser Type - Oupeng Browser + * @zh 浏览器类型 - 欧朋浏览器 + * @default "oupeng" + */ + BROWSER_TYPE_OUPENG: 'oupeng', + /** + * @en Browser Type - MI UI Browser + * @zh 浏览器类型 - MIUI 内置浏览器 + * @default "miuibrowser" + */ + BROWSER_TYPE_MIUI: 'miuibrowser', + /** + * @en Browser Type - Firefox Browser + * @zh 浏览器类型 - Firefox 浏览器 + * @default "firefox" + */ + BROWSER_TYPE_FIREFOX: 'firefox', + /** + * @en Browser Type - Safari Browser + * @zh 浏览器类型 - Safari 浏览器 + * @default "safari" + */ + BROWSER_TYPE_SAFARI: 'safari', + /** + * @en Browser Type - Chrome Browser + * @zh 浏览器类型 - Chrome 浏览器 + * @default "chrome" + */ + BROWSER_TYPE_CHROME: 'chrome', + /** + * @en Browser Type - Cheetah Browser + * @zh 浏览器类型 - 猎豹浏览器 + * @default "liebao" + */ + BROWSER_TYPE_LIEBAO: 'liebao', + /** + * @en Browser Type - QZone Inner Browser + * @zh 浏览器类型 - QZone 内置浏览器 + * @default "qzone" + */ + BROWSER_TYPE_QZONE: 'qzone', + /** + * @en Browser Type - Sogou Browser + * @zh 浏览器类型 - 搜狗浏览器 + * @default "sogou" + */ + BROWSER_TYPE_SOUGOU: 'sogou', + /** + * @en Browser Type - Unknown + * @zh 浏览器类型 - 未知 + * @default "unknown" + */ + BROWSER_TYPE_UNKNOWN: 'unknown', + + /** + * @en Whether the running platform is native app + * @zh 指示运行平台是否是原生平台 + */ + isNative: JSB, + + /** + * @en Whether the running platform is browser + * @zh 指示运行平台是否是浏览器 + */ + isBrowser: typeof window === 'object' && typeof document === 'object' && !MINIGAME && !JSB, -/** - * German language code - * @property {String} LANGUAGE_GERMAN - * @readOnly - */ -sys.LANGUAGE_GERMAN = 'de'; + /** + * @en Indicate whether the current running context is a mobile system + * @zh 指示当前运行平台是否是移动端平台 + * @default false + */ + isMobile: false, -/** - * Spanish language code - * @property {String} LANGUAGE_SPANISH - * @readOnly - */ -sys.LANGUAGE_SPANISH = 'es'; + /** + * @en Whether the endianness of current platform is little endian + * @zh 当前平台字节顺序是否是小端序 + */ + isLittleEndian: (() => { + const buffer = new ArrayBuffer(2); + new DataView(buffer).setInt16(0, 256, true); + // Int16Array uses the platform's endianness. + return new Int16Array(buffer)[0] === 256; + })(), -/** - * Spanish language code - * @property {String} LANGUAGE_DUTCH - * @readOnly - */ -sys.LANGUAGE_DUTCH = 'du'; + /** + * @en The running platform + * @zh 当前运行平台或环境 + * @default {{sys.UNKNOWN}} + */ + platform: -1, -/** - * Russian language code - * @property {String} LANGUAGE_RUSSIAN - * @readOnly - */ -sys.LANGUAGE_RUSSIAN = 'ru'; + /** + * @en Indicate the current language of the running system + * @zh 指示当前运行环境的语言 + * @default {{sys.LANGUAGE_UNKNOWN}} + */ + language: 'unknown', -/** - * Korean language code - * @property {String} LANGUAGE_KOREAN - * @readOnly - */ -sys.LANGUAGE_KOREAN = 'ko'; + /** + * @en Indicate the running os name + * @zh 指示当前运行系统 + */ + os: 'Unknown', -/** - * Japanese language code - * @property {String} LANGUAGE_JAPANESE - * @readOnly - */ -sys.LANGUAGE_JAPANESE = 'ja'; + /** + * @en Indicate the running os version string + * @zh 指示当前运行系统版本字符串 + */ + osVersion: '', -/** - * Hungarian language code - * @property {String} LANGUAGE_HUNGARIAN - * @readonly - */ -sys.LANGUAGE_HUNGARIAN = 'hu'; + /** + * @en Indicate the running os main version + * @zh 指示当前系统主版本 + */ + osMainVersion: 0, -/** - * Portuguese language code - * @property {String} LANGUAGE_PORTUGUESE - * @readOnly - */ -sys.LANGUAGE_PORTUGUESE = 'pt'; + /** + * @en Indicate the running browser type + * @zh 指示当前运行的浏览器类型 + */ + browserType: 'unknown', -/** - * Arabic language code - * @property {String} LANGUAGE_ARABIC - * @readOnly - */ -sys.LANGUAGE_ARABIC = 'ar'; + /** + * @en Indicate the running browser version + * @zh 指示当前运行的浏览器版本 + */ + browserVersion: '', -/** - * Norwegian language code - * @property {String} LANGUAGE_NORWEGIAN - * @readOnly - */ -sys.LANGUAGE_NORWEGIAN = 'no'; + /** + * @en Indicate the real pixel resolution of the whole game window + * @zh 指示游戏窗口的像素分辨率 + */ + windowPixelResolution: null, -/** - * Polish language code - * @property {String} LANGUAGE_POLISH - * @readOnly - */ -sys.LANGUAGE_POLISH = 'pl'; + /** + * @en The capabilities of the current platform + * @zh 当前平台的功能可用性 + */ + capabilities: null, -/** - * Turkish language code - * @property {String} LANGUAGE_TURKISH - * @readOnly - */ -sys.LANGUAGE_TURKISH = 'tr'; + /** + * @en It is a local storage component based on HTML5 localStorage API, on web platform, it's equal to window.localStorage + * @zh HTML5 标准中的 localStorage 的本地存储功能,在 Web 端等价于 window.localStorage + */ + localStorage: null, -/** - * Ukrainian language code - * @property {String} LANGUAGE_UKRAINIAN - * @readOnly - */ -sys.LANGUAGE_UKRAINIAN = 'uk'; + /** + * Audio support in the browser + * + * MULTI_CHANNEL : Multiple audio while playing - If it doesn't, you can only play background music + * WEB_AUDIO : Support for WebAudio - Support W3C WebAudio standards, all of the audio can be played + * AUTOPLAY : Supports auto-play audio - if Don‘t support it, On a touch detecting background music canvas, and then replay + * REPLAY_AFTER_TOUCH : The first music will fail, must be replay after touchstart + * USE_EMPTIED_EVENT : Whether to use the emptied event to replace load callback + * DELAY_CREATE_CTX : delay created the context object - only webAudio + * NEED_MANUAL_LOOP : loop attribute failure, need to perform loop manually + * + * May be modifications for a few browser version + * @private + */ + __audioSupport: null, -/** - * Romanian language code - * @property {String} LANGUAGE_ROMANIAN - * @readOnly - */ -sys.LANGUAGE_ROMANIAN = 'ro'; + /** + * @en Get the network type of current device, return cc.sys.NetworkType.LAN if failure. + * @zh 获取当前设备的网络类型, 如果网络类型无法获取,默认将返回 cc.sys.NetworkType.LAN + */ + getNetworkType (): NetworkType { + // TODO: need to implement this for mobile phones. + return NetworkType.LAN; + }, -/** - * Bulgarian language code - * @property {String} LANGUAGE_BULGARIAN - * @readOnly - */ -sys.LANGUAGE_BULGARIAN = 'bg'; + /** + * @en Get the battery level of current device, return 1.0 if failure. + * @zh 获取当前设备的电池电量,如果电量无法获取,默认将返回 1 + * @return - 0.0 ~ 1.0 + */ + getBatteryLevel (): number { + // TODO: need to implement this for mobile phones. + return 1.0; + }, -/** - * Unknown language code - * @property {String} LANGUAGE_UNKNOWN - * @readOnly - */ -sys.LANGUAGE_UNKNOWN = 'unknown'; + /** + * @en Forces the garbage collection, only available in native platforms + * @zh 强制进行 JS 内存垃圾回收,尽在原生平台有效 + */ + garbageCollect () { + // N/A in web + }, -/** - * @property {String} OS_IOS - * @readOnly - */ -sys.OS_IOS = 'iOS'; -/** - * @property {String} OS_ANDROID - * @readOnly - */ -sys.OS_ANDROID = 'Android'; -/** - * @property {String} OS_WINDOWS - * @readOnly - */ -sys.OS_WINDOWS = 'Windows'; -/** - * @property {String} OS_MARMALADE - * @readOnly - */ -sys.OS_MARMALADE = 'Marmalade'; -/** - * @property {String} OS_LINUX - * @readOnly - */ -sys.OS_LINUX = 'Linux'; -/** - * @property {String} OS_BADA - * @readOnly - */ -sys.OS_BADA = 'Bada'; -/** - * @property {String} OS_BLACKBERRY - * @readOnly - */ -sys.OS_BLACKBERRY = 'Blackberry'; -/** - * @property {String} OS_OSX - * @readOnly - */ -sys.OS_OSX = 'OS X'; -/** - * @property {String} OS_WP8 - * @readOnly - */ -sys.OS_WP8 = 'WP8'; -/** - * @property {String} OS_WINRT - * @readOnly - */ -sys.OS_WINRT = 'WINRT'; -/** - * @property {String} OS_UNKNOWN - * @readOnly - */ -sys.OS_UNKNOWN = 'Unknown'; + /** + * @en Check whether an object is valid, + * In web engine, it will return true if the object exist + * In native engine, it will return true if the JS object and the correspond native object are both valid + * @zh 检查一个对象是否非空或在原生平台有效, + * 在 Web 平台,只要对象非空或非 Undefined 就会返回 true,在原生平台,我们会检查当前 JS 对象和其绑定的原生对象是否都有效 + * @param obj The object to be checked + */ + isObjectValid (obj: any): boolean { + if (obj === null || obj === undefined) { + return false; + } + else { + return true; + } + }, -/** - * @property {Number} UNKNOWN - * @readOnly - * @default -1 - */ -sys.UNKNOWN = -1; -/** - * @property {Number} WIN32 - * @readOnly - * @default 0 - */ -sys.WIN32 = 0; -/** - * @property {Number} LINUX - * @readOnly - * @default 1 - */ -sys.LINUX = 1; -/** - * @property {Number} MACOS - * @readOnly - * @default 2 - */ -sys.MACOS = 2; -/** - * @property {Number} ANDROID - * @readOnly - * @default 3 - */ -sys.ANDROID = 3; -/** - * @property {Number} IPHONE - * @readOnly - * @default 4 - */ -sys.IPHONE = 4; -/** - * @property {Number} IPAD - * @readOnly - * @default 5 - */ -sys.IPAD = 5; -/** - * @property {Number} BLACKBERRY - * @readOnly - * @default 6 - */ -sys.BLACKBERRY = 6; -/** - * @property {Number} NACL - * @readOnly - * @default 7 - */ -sys.NACL = 7; -/** - * @property {Number} EMSCRIPTEN - * @readOnly - * @default 8 - */ -sys.EMSCRIPTEN = 8; -/** - * @property {Number} TIZEN - * @readOnly - * @default 9 - */ -sys.TIZEN = 9; -/** - * @property {Number} WINRT - * @readOnly - * @default 10 - */ -sys.WINRT = 10; -/** - * @property {Number} WP8 - * @readOnly - * @default 11 - */ -sys.WP8 = 11; -/** - * @property {Number} MOBILE_BROWSER - * @readOnly - * @default 100 - */ -sys.MOBILE_BROWSER = 100; -/** - * @property {Number} DESKTOP_BROWSER - * @readOnly - * @default 101 - */ -sys.DESKTOP_BROWSER = 101; + /** + * @en Dump system informations + * @zh 在控制台打印当前的主要系统信息 + */ + dump () { + let str = ''; + str += 'isMobile : ' + this.isMobile + '\r\n'; + str += 'language : ' + this.language + '\r\n'; + str += 'browserType : ' + this.browserType + '\r\n'; + str += 'browserVersion : ' + this.browserVersion + '\r\n'; + str += 'capabilities : ' + JSON.stringify(this.capabilities) + '\r\n'; + str += 'os : ' + this.os + '\r\n'; + str += 'osVersion : ' + this.osVersion + '\r\n'; + str += 'platform : ' + this.platform + '\r\n'; + str += 'Using ' + (cc.game.renderType === cc.game.RENDER_TYPE_WEBGL ? 'WEBGL' : 'CANVAS') + ' renderer.' + '\r\n'; + cc.log(str); + }, -/** - * Indicates whether executes in editor's window process (Electron's renderer context) - * @property {Number} EDITOR_PAGE - * @readOnly - * @default 102 - */ -sys.EDITOR_PAGE = 102; -/** - * Indicates whether executes in editor's main process (Electron's browser context) - * @property {Number} EDITOR_CORE - * @readOnly - * @default 103 - */ -sys.EDITOR_CORE = 103; -/** - * @property {Number} WECHAT_GAME - * @readOnly - * @default 104 - */ -sys.WECHAT_GAME = 104; -/** - * @property {Number} QQ_PLAY - * @readOnly - * @default 105 - */ -sys.QQ_PLAY = 105; -/** - * BROWSER_TYPE_WECHAT - * @property {String} BROWSER_TYPE_WECHAT - * @readOnly - * @default "wechat" - */ -sys.BROWSER_TYPE_WECHAT = 'wechat'; -/** - * BROWSER_TYPE_WECHAT_GAME - * @property {String} BROWSER_TYPE_WECHAT_GAME - * @readOnly - * @default "wechatgame" - */ -sys.BROWSER_TYPE_WECHAT_GAME = 'wechatgame'; -/** - * BROWSER_TYPE_ALIPAY_GAME - * @property {String} BROWSER_TYPE_ALIPAY_GAME - * @readOnly - * @default "alipaygame" - */ -sys.BROWSER_TYPE_ALIPAY_GAME = 'alipaygame'; -/** - * BROWSER_TYPE_XIAOMI_GAME - * @property {String} BROWSER_TYPE_XIAOMI_GAME - * @readOnly - * @default "xiaomiquickgame" - */ -sys.BROWSER_TYPE_XIAOMI_GAME = 'xiaomiquickgame'; -/** - * BROWSER_TYPE_BAIDU_GAME - * @property {String} BROWSER_TYPE_BAIDU_GAME - * @readOnly - * @default "baidugame" - */ -sys.BROWSER_TYPE_BAIDU_GAME = 'baidugame'; -/** - * BROWSER_TYPE_COCOSPLAY - * @property {String} BROWSER_TYPE_COCOSPLAY - * @readOnly - * @default "cocosplay" - */ -sys.BROWSER_TYPE_COCOSPLAY = 'cocosplay'; -/** - * - * @property {String} BROWSER_TYPE_ANDROID - * @readOnly - * @default "androidbrowser" - */ -sys.BROWSER_TYPE_ANDROID = 'androidbrowser'; -/** - * - * @property {String} BROWSER_TYPE_IE - * @readOnly - * @default "ie" - */ -sys.BROWSER_TYPE_IE = 'ie'; -/** - * - * @property {String} BROWSER_TYPE_QQ - * @readOnly - * @default "qqbrowser" - */ -sys.BROWSER_TYPE_QQ = 'qqbrowser'; -/** - * - * @property {String} BROWSER_TYPE_MOBILE_QQ - * @readOnly - * @default "mqqbrowser" - */ -sys.BROWSER_TYPE_MOBILE_QQ = 'mqqbrowser'; -/** - * - * @property {String} BROWSER_TYPE_UC - * @readOnly - * @default "ucbrowser" - */ -sys.BROWSER_TYPE_UC = 'ucbrowser'; -/** - * uc third party integration. - * @property {String} BROWSER_TYPE_UCBS - * @readOnly - * @default "ucbs" - */ -sys.BROWSER_TYPE_UCBS = 'ucbs'; -/** - * - * @property {String} BROWSER_TYPE_360 - * @readOnly - * @default "360browser" - */ -sys.BROWSER_TYPE_360 = '360browser'; -/** - * - * @property {String} BROWSER_TYPE_BAIDU_APP - * @readOnly - * @default "baiduboxapp" - */ -sys.BROWSER_TYPE_BAIDU_APP = 'baiduboxapp'; -/** - * - * @property {String} BROWSER_TYPE_BAIDU - * @readOnly - * @default "baidubrowser" - */ -sys.BROWSER_TYPE_BAIDU = 'baidubrowser'; -/** - * - * @property {String} BROWSER_TYPE_MAXTHON - * @readOnly - * @default "maxthon" - */ -sys.BROWSER_TYPE_MAXTHON = 'maxthon'; -/** - * - * @property {String} BROWSER_TYPE_OPERA - * @readOnly - * @default "opera" - */ -sys.BROWSER_TYPE_OPERA = 'opera'; -/** - * - * @property {String} BROWSER_TYPE_OUPENG - * @readOnly - * @default "oupeng" - */ -sys.BROWSER_TYPE_OUPENG = 'oupeng'; -/** - * - * @property {String} BROWSER_TYPE_MIUI - * @readOnly - * @default "miuibrowser" - */ -sys.BROWSER_TYPE_MIUI = 'miuibrowser'; -/** - * - * @property {String} BROWSER_TYPE_FIREFOX - * @readOnly - * @default "firefox" - */ -sys.BROWSER_TYPE_FIREFOX = 'firefox'; -/** - * - * @property {String} BROWSER_TYPE_SAFARI - * @readOnly - * @default "safari" - */ -sys.BROWSER_TYPE_SAFARI = 'safari'; -/** - * - * @property {String} BROWSER_TYPE_CHROME - * @readOnly - * @default "chrome" - */ -sys.BROWSER_TYPE_CHROME = 'chrome'; -/** - * - * @property {String} BROWSER_TYPE_LIEBAO - * @readOnly - * @default "liebao" - */ -sys.BROWSER_TYPE_LIEBAO = 'liebao'; -/** - * - * @property {String} BROWSER_TYPE_QZONE - * @readOnly - * @default "qzone" - */ -sys.BROWSER_TYPE_QZONE = 'qzone'; -/** - * - * @property {String} BROWSER_TYPE_SOUGOU - * @readOnly - * @default "sogou" - */ -sys.BROWSER_TYPE_SOUGOU = 'sogou'; -/** - * - * @property {String} BROWSER_TYPE_UNKNOWN - * @readOnly - * @default "unknown" - */ -sys.BROWSER_TYPE_UNKNOWN = 'unknown'; + /** + * @en Try to open a url in browser, may not work in some platforms + * @zh 尝试打开一个 web 页面,并非在所有平台都有效 + */ + openURL (url) { + if (JSB) { + // @ts-ignore + jsb.openURL(url); + } + else { + window.open(url); + } + }, -/** - * Is native ? This is set to be true in jsb auto. - * @property {Boolean} isNative - */ -sys.isNative = JSB; + /** + * @en Get the current time in milliseconds + * @zh 获取当前时间(毫秒为单位) + */ + now () { + if (Date.now) { + return Date.now(); + } + else { + return +(new Date); + } + }, -/** - * Is web browser ? - * @property {Boolean} isBrowser - */ -sys.isBrowser = typeof window === 'object' && typeof document === 'object' && !MINIGAME && !JSB; + /** + * Dumps rooted objects, only available in native platforms + * @private + */ + dumpRoot () { + // N/A in web + }, -/** - * Endianess of current platform - * @property {boolean} isLittleEndian - */ -sys.isLittleEndian = (() => { - const buffer = new ArrayBuffer(2); - new DataView(buffer).setInt16(0, 256, true); - // Int16Array uses the platform's endianness. - return new Int16Array(buffer)[0] === 256; -})(); + /** + * Restart the JS VM, only available in native platforms + * @private + */ + restartVM () { + // N/A in web + }, + + /** + * Clean a script in the JS VM, only available in native platforms + * @private + */ + cleanScript (jsfile) { + // N/A in web + }, +}; + +// ============= Platform Adaptation ============== if (_global.__globalAdapter && _global.__globalAdapter.adaptSys) { // init sys info in adapter @@ -576,8 +729,8 @@ if (_global.__globalAdapter && _global.__globalAdapter.adaptSys) { // linux: sys.OS_LINUX, // // @ts-ignore // })[process.platform] || sys.OS_UNKNOWN; -// sys.browserType = null; -// sys.browserVersion = null; +// sys.browserType = sys.BROWSER_TYPE_UNKNOWN; +// sys.browserVersion = ''; // sys.windowPixelResolution = { // width: 0, // height: 0, @@ -601,8 +754,8 @@ else if (JSB) { // @ts-ignore sys.osVersion = __getOSVersion(); sys.osMainVersion = parseInt(sys.osVersion); - sys.browserType = null; - sys.browserVersion = null; + sys.browserType = sys.BROWSER_TYPE_UNKNOWN; + sys.browserVersion = ''; const w = window.innerWidth; const h = window.innerHeight; @@ -648,16 +801,7 @@ else { sys.platform = sys.EDITOR_PAGE; } else { - /** - * Indicate whether system is mobile system - * @property {Boolean} isMobile - */ sys.isMobile = /mobile|android|iphone|ipad/.test(ua); - - /** - * Indicate the running platform - * @property {Number} platform - */ sys.platform = sys.isMobile ? sys.MOBILE_BROWSER : sys.DESKTOP_BROWSER; } @@ -665,11 +809,6 @@ else { // @ts-ignore currLanguage = currLanguage ? currLanguage : nav.browserLanguage; currLanguage = currLanguage ? currLanguage.split('-')[0] : sys.LANGUAGE_ENGLISH; - - /** - * Indicate the current language of the running system - * @property {String} language - */ sys.language = currLanguage; // Get the os of system @@ -706,26 +845,10 @@ else { else if (isAndroid) { osName = sys.OS_ANDROID; } else if (nav.appVersion.indexOf('Linux') !== -1 || ua.indexOf('ubuntu') !== -1) { osName = sys.OS_LINUX; } - /** - * Indicate the running os name - * @property {String} os - */ sys.os = osName; - /** - * Indicate the running os version - * @property {String} osVersion - */ sys.osVersion = osVersion; - /** - * Indicate the running os main version - * @property {Number} osMainVersion - */ sys.osMainVersion = osMajorVersion; - /** - * Indicate the running browser type - * @property {String} browserType - */ sys.browserType = sys.BROWSER_TYPE_UNKNOWN; /* Determine the browser type */ (function () { @@ -754,33 +877,29 @@ else { } else if (browserType === 'micromessenger') { browserType = sys.BROWSER_TYPE_WECHAT; - } + } else if (browserType === 'safari' && isAndroid) { browserType = sys.BROWSER_TYPE_ANDROID; - } + } else if (browserType === 'qq' && ua.match(/android.*applewebkit/i)) { browserType = sys.BROWSER_TYPE_ANDROID; - } + } else if (browserType === 'trident') { browserType = sys.BROWSER_TYPE_IE; - } + } else if (browserType === '360 aphone') { browserType = sys.BROWSER_TYPE_360; - } + } else if (browserType === 'mxbrowser') { browserType = sys.BROWSER_TYPE_MAXTHON; - } + } else if (browserType === 'opr/') { browserType = sys.BROWSER_TYPE_OPERA; - } + } sys.browserType = browserType; })(); - /** - * Indicate the running browser version - * @property {String} browserVersion - */ sys.browserVersion = ''; /* Determine the browser version number */ (function () { @@ -795,21 +914,11 @@ else { const h = window.innerHeight || document.documentElement.clientHeight; const ratio = window.devicePixelRatio || 1; - /** - * Indicate the real pixel resolution of the whole game window - * @property {Size} windowPixelResolution - */ sys.windowPixelResolution = { width: ratio * w, height: ratio * h, }; - sys._checkWebGLRenderMode = function () { - if (cc.game.renderType !== cc.game.RENDER_TYPE_WEBGL) { - throw new Error('This feature supports WebGL render mode only.'); - } - }; - const _tmpCanvas1 = document.createElement('canvas'); const create3DContext = function (canvas, opt_attribs, opt_contextType) { @@ -829,10 +938,6 @@ else { } }; - /** - * cc.sys.localStorage is a local storage component. - * @property {Object} localStorage - */ try { let localStorage: Storage | null = sys.localStorage = win.localStorage; localStorage.setItem('storage', ''); @@ -906,10 +1011,6 @@ else { } } - /** - * The capabilities of the current platform - * @property {Object} capabilities - */ const capabilities = sys.capabilities = { canvas: _supportCanvas, opengl: _supportWebGL, @@ -930,24 +1031,8 @@ else { } let __audioSupport; - - /** - * Audio support in the browser - * - * MULTI_CHANNEL : Multiple audio while playing - If it doesn't, you can only play background music - * WEB_AUDIO : Support for WebAudio - Support W3C WebAudio standards, all of the audio can be played - * AUTOPLAY : Supports auto-play audio - if Don‘t support it, On a touch detecting background music canvas, and then replay - * REPLAY_AFTER_TOUCH : The first music will fail, must be replay after touchstart - * USE_EMPTIED_EVENT : Whether to use the emptied event to replace load callback - * DELAY_CREATE_CTX : delay created the context object - only webAudio - * NEED_MANUAL_LOOP : loop attribute failure, need to perform loop manually - * - * May be modifications for a few browser version - */ (function () { - const DEBUG = false; - const version = sys.browserVersion; // check if browser supports Web Audio @@ -1004,7 +1089,6 @@ else { } const formatSupport: string[] = []; - (function () { const audio = document.createElement('audio'); if (audio.canPlayType) { @@ -1025,172 +1109,4 @@ else { sys.__audioSupport = __audioSupport; } -/** - * @en - * Network type enumeration - * @zh - * 网络类型枚举 - * - * @enum NetworkType - */ -sys.NetworkType = { - /** - * @en - * Network is unreachable. - * @zh - * 网络不通 - * - * @property {Number} NONE - */ - NONE: 0, - /** - * @en - * Network is reachable via WiFi or cable. - * @zh - * 通过无线或者有线本地网络连接因特网 - * - * @property {Number} LAN - */ - LAN: 1, - /** - * @en - * Network is reachable via Wireless Wide Area Network - * @zh - * 通过蜂窝移动网络连接因特网 - * - * @property {Number} WWAN - */ - WWAN: 2, -}; - -/** - * @class sys - */ - -/** - * @en - * Get the network type of current device, return cc.sys.NetworkType.LAN if failure. - * @zh - * 获取当前设备的网络类型, 如果网络类型无法获取,默认将返回 cc.sys.NetworkType.LAN - * - * @method getNetworkType - * @return {NetworkType} - */ -sys.getNetworkType = function () { - // TODO: need to implement this for mobile phones. - return sys.NetworkType.LAN; -}; - -/** - * @en - * Get the battery level of current device, return 1.0 if failure. - * @zh - * 获取当前设备的电池电量,如果电量无法获取,默认将返回 1 - * - * @method getBatteryLevel - * @return {Number} - 0.0 ~ 1.0 - */ -sys.getBatteryLevel = function () { - // TODO: need to implement this for mobile phones. - return 1.0; -}; - -/** - * Forces the garbage collection, only available in JSB - * @method garbageCollect - */ -sys.garbageCollect = function () { - // N/A in web -}; - -/** - * Dumps rooted objects, only available in JSB - * @method dumpRoot - */ -sys.dumpRoot = function () { - // N/A in web -}; - -/** - * Restart the JS VM, only available in JSB - * @method restartVM - */ -sys.restartVM = function () { - // N/A in web -}; - -/** - * Clean a script in the JS VM, only available in JSB - * @method cleanScript - * @param {String} jsfile - */ -sys.cleanScript = function (jsfile) { - // N/A in web -}; - -/** - * Check whether an object is valid, - * In web engine, it will return true if the object exist - * In native engine, it will return true if the JS object and the correspond native object are both valid - * @method isObjectValid - * @param {Object} obj - * @return {Boolean} Validity of the object - */ -sys.isObjectValid = function (obj) { - if (obj) { - return true; - } - return false; -}; - -/** - * Dump system informations - * @method dump - */ -sys.dump = function () { - const self = this; - let str = ''; - str += 'isMobile : ' + self.isMobile + '\r\n'; - str += 'language : ' + self.language + '\r\n'; - str += 'browserType : ' + self.browserType + '\r\n'; - str += 'browserVersion : ' + self.browserVersion + '\r\n'; - str += 'capabilities : ' + JSON.stringify(self.capabilities) + '\r\n'; - str += 'os : ' + self.os + '\r\n'; - str += 'osVersion : ' + self.osVersion + '\r\n'; - str += 'platform : ' + self.platform + '\r\n'; - str += 'Using ' + (cc.game.renderType === cc.game.RENDER_TYPE_WEBGL ? 'WEBGL' : 'CANVAS') + ' renderer.' + '\r\n'; - cc.log(str); -}; - -/** - * Open a url in browser - * @method openURL - * @param {String} url - */ -sys.openURL = function (url) { - if (JSB) { - // @ts-ignore - jsb.openURL(url); - } - else { - window.open(url); - } -}; - -/** - * Get the number of milliseconds elapsed since 1 January 1970 00:00:00 UTC. - * @method now - * @return {Number} - */ -sys.now = function () { - if (Date.now) { - return Date.now(); - } - else { - return +(new Date); - } -}; - cc.sys = sys; - -export default sys; diff --git a/cocos/core/platform/view.ts b/cocos/core/platform/view.ts index 3c7c8c1092..7ee0a5c8f8 100644 --- a/cocos/core/platform/view.ts +++ b/cocos/core/platform/view.ts @@ -32,7 +32,7 @@ import '../data/class'; import { EventTarget } from '../event/event-target'; import '../game'; -import { Rect, Size } from '../math'; +import { Rect, Size, Vec2 } from '../math'; import visibleRect from './visible-rect'; import { EDITOR, MINIGAME, WECHAT, JSB } from 'internal:constants'; @@ -112,21 +112,21 @@ switch (__BrowserGetter.adaptationType) { break; } -let _scissorRect: Rect | null = null; - /** - * cc.view is the singleton object which represents the game window.
+ * @en View represents the game window.
* It's main task include:
- * - Apply the design resolution policy
+ * - Apply the design resolution policy to the UI Canvas
* - Provide interaction with the window, like resize event on web, retina display support, etc...
- * - Manage the game view port which can be different with the window
- * - Manage the content scale and translation
+ * - Manage the scale and translation of canvas related to the frame on Web
*
- * Since the cc.view is a singleton, you don't need to call any constructor or create functions,
+ * With {{view}} as its singleton initialized by the engine, you don't need to call any constructor or create functions,
* the standard way to use it is by calling:
- * - cc.view.methodName();
- * - * @class View + * - view.methodName();
+ * @zh View 代表游戏窗口视图,它的核心功能包括: + * - 对所有 UI Canvas 进行设计分辨率适配。 + * - 提供窗口视图的交互,比如监听 resize 事件,控制 retina 屏幕适配,等等。 + * - 控制 Canvas 节点相对于外层 DOM 节点的缩放和偏移。 + * 引擎会自动初始化它的单例对象 {{view}},所以你不需要实例化任何 View,只需要直接使用 `view.methodName();` */ export class View extends EventTarget { @@ -144,14 +144,14 @@ export class View extends EventTarget { private _devicePixelRatio: number; private _maxPixelRatio: number; private _retinaEnabled: boolean; - private _resizeCallback: null; + private _resizeCallback: Function | null; private _resizing: boolean; private _orientationChanging: boolean; private _isRotated: boolean; private _orientation: any; private _isAdjustViewport: boolean; private _antiAliasEnabled: boolean; - private _resolutionPolicy: any; + private _resolutionPolicy: ResolutionPolicy; private _rpExactFit: ResolutionPolicy; private _rpShowAll: ResolutionPolicy; private _rpNoBorder: ResolutionPolicy; @@ -199,12 +199,12 @@ export class View extends EventTarget { this._antiAliasEnabled = false; // Setup system default resolution policies - this._resolutionPolicy = null; this._rpExactFit = new ResolutionPolicy(_strategyer.EQUAL_TO_FRAME, _strategy.EXACT_FIT); this._rpShowAll = new ResolutionPolicy(_strategyer.EQUAL_TO_FRAME, _strategy.SHOW_ALL); this._rpNoBorder = new ResolutionPolicy(_strategyer.EQUAL_TO_FRAME, _strategy.NO_BORDER); this._rpFixedHeight = new ResolutionPolicy(_strategyer.EQUAL_TO_FRAME, _strategy.FIXED_HEIGHT); this._rpFixedWidth = new ResolutionPolicy(_strategyer.EQUAL_TO_FRAME, _strategy.FIXED_WIDTH); + this._resolutionPolicy = this._rpShowAll; cc.game.once(cc.Game.EVENT_ENGINE_INITED, this.init, this); } @@ -233,40 +233,15 @@ export class View extends EventTarget { } } - /** - * @en - * Sets view's target-densitydpi for android mobile browser. it can be set to:
- * 1. macro.DENSITYDPI_DEVICE, value is "device-dpi"
- * 2. macro.DENSITYDPI_HIGH, value is "high-dpi" (default value)
- * 3. macro.DENSITYDPI_MEDIUM, value is "medium-dpi" (browser's default value)
- * 4. macro.DENSITYDPI_LOW, value is "low-dpi"
- * 5. Custom value, e.g: "480"
- * @zh 设置目标内容的每英寸像素点密度。 - * - * @method setTargetDensityDPI - * @param {String} densityDPI - * @deprecated since v2.0 - */ - - /** - * @en - * Returns the current target-densitydpi value of cc.view. - * @zh 获取目标内容的每英寸像素点密度。 - * @method getTargetDensityDPI - * @returns {String} - * @deprecated since v2.0 - */ - /** * @en * Sets whether resize canvas automatically when browser's size changed.
* Useful only on web. * @zh 设置当发现浏览器的尺寸改变时,是否自动调整 canvas 尺寸大小。 * 仅在 Web 模式下有效。 - * @method resizeWithBrowserSize - * @param {Boolean} enabled - Whether enable automatic resize with browser's resize event + * @param enabled - Whether enable automatic resize with browser's resize event */ - public resizeWithBrowserSize (enabled) { + public resizeWithBrowserSize (enabled: boolean) { if (enabled) { // enable if (!this._resizeWithBrowserSize) { @@ -294,10 +269,9 @@ export class View extends EventTarget { * 这个回调函数会在应用适配模式之前被调用, * 因此你可以在这个回调函数内添加任意附加改变, * 仅在 Web 平台下有效。 - * @method setResizeCallback - * @param {Function|Null} callback - The callback function + * @param callback - The callback function */ - public setResizeCallback (callback) { + public setResizeCallback (callback: Function | null) { if (typeof callback === 'function' || callback == null) { this._resizeCallback = callback; } @@ -314,10 +288,9 @@ export class View extends EventTarget { * 当设置为横版或竖版,并且屏幕的宽高比例不匹配时, * cc.view 会自动用 CSS 旋转游戏场景的 canvas, * 这个方法不会对 native 部分产生任何影响,对于 native 而言,你需要在应用设置中的设置排版。 - * @method setOrientation - * @param {Number} orientation - Possible values: macro.ORIENTATION_LANDSCAPE | macro.ORIENTATION_PORTRAIT | macro.ORIENTATION_AUTO + * @param orientation - Possible values: macro.ORIENTATION_LANDSCAPE | macro.ORIENTATION_PORTRAIT | macro.ORIENTATION_AUTO */ - public setOrientation (orientation) { + public setOrientation (orientation: number) { orientation = orientation & cc.macro.ORIENTATION_AUTO; if (orientation && this._orientation !== orientation) { this._orientation = orientation; @@ -334,10 +307,9 @@ export class View extends EventTarget { * 默认设置为启动,我们强烈建议你不要将它设置为关闭。 * 即使当它启动时,你仍然能够设置你的 viewport meta,它不会被覆盖。 * 仅在 Web 模式下有效 - * @method adjustViewportMeta - * @param {Boolean} enabled - Enable automatic modification to "viewport" meta + * @param enabled - Enable automatic modification to "viewport" meta */ - public adjustViewportMeta (enabled) { + public adjustViewportMeta (enabled: boolean) { this._isAdjustViewport = enabled; } @@ -349,10 +321,9 @@ export class View extends EventTarget { * @zh 对于 Apple 这种支持 Retina 显示的设备上默认进行优化而其他类型设备默认不进行优化, * 它仅会在你调用 setDesignResolutionPolicy 方法时有影响。 * 仅在 Web 模式下有效。 - * @method enableRetina - * @param {Boolean} enabled - Enable or disable retina display + * @param enabled - Enable or disable retina display */ - public enableRetina (enabled) { + public enableRetina (enabled: boolean) { this._retinaEnabled = !!enabled; } @@ -362,20 +333,17 @@ export class View extends EventTarget { * Only useful on web * @zh 检查是否对 Retina 显示设备进行优化。 * 仅在 Web 模式下有效。 - * @method isRetinaEnabled - * @return {Boolean} */ - public isRetinaEnabled () { + public isRetinaEnabled (): boolean { return this._retinaEnabled; } /** * @en Whether to Enable on anti-alias * @zh 控制抗锯齿是否开启 - * @method enableAntiAlias - * @param {Boolean} enabled - Enable or not anti-alias + * @param enabled - Enable or not anti-alias */ - public enableAntiAlias (enabled) { + public enableAntiAlias (enabled: boolean) { if (this._antiAliasEnabled === enabled) { return; } @@ -407,10 +375,8 @@ export class View extends EventTarget { /** * @en Returns whether the current enable on anti-alias * @zh 返回当前是否抗锯齿 - * @method isAntiAliasEnabled - * @return {Boolean} */ - public isAntiAliasEnabled () { + public isAntiAliasEnabled (): boolean { return this._antiAliasEnabled; } /** @@ -420,10 +386,9 @@ export class View extends EventTarget { * Only useful on web * @zh 启动时,移动端游戏会在移动端自动尝试进入全屏模式。 * 你能够传入 true 为参数去启动它,用 false 参数来关闭它。 - * @method enableAutoFullScreen - * @param {Boolean} enabled - Enable or disable auto full screen on mobile devices + * @param enabled - Enable or disable auto full screen on mobile devices */ - public enableAutoFullScreen (enabled) { + public enableAutoFullScreen (enabled: boolean) { if (enabled && enabled !== this._autoFullScreen && cc.sys.isMobile && @@ -443,10 +408,9 @@ export class View extends EventTarget { * Only useful on web * @zh 检查自动进入全屏模式是否启动。 * 仅在 Web 模式下有效。 - * @method isAutoFullScreenEnabled - * @return {Boolean} Auto full screen enabled or not + * @return Auto full screen enabled or not */ - public isAutoFullScreenEnabled () { + public isAutoFullScreenEnabled (): boolean { return this._autoFullScreen; } @@ -454,11 +418,11 @@ export class View extends EventTarget { * Not support on native.
* On web, it sets the size of the canvas. * @zh 这个方法并不支持 native 平台,在 Web 平台下,可以用来设置 canvas 尺寸。 - * @method setCanvasSize + * @private * @param {Number} width * @param {Number} height */ - public setCanvasSize (width, height) { + public setCanvasSize (width: number, height: number) { const canvas = cc.game.canvas; const container = cc.game.container; this._devicePixelRatio = window.devicePixelRatio; @@ -486,11 +450,9 @@ export class View extends EventTarget { * @zh 返回视图中 canvas 的尺寸。 * 在 native 平台下,它返回全屏视图下屏幕的尺寸。 * 在 Web 平台下,它返回 canvas 元素尺寸。 - * @method getCanvasSize - * @return {Size} */ - public getCanvasSize () { - return cc.size(cc.game.canvas.width, cc.game.canvas.height); + public getCanvasSize (): Size { + return new Size(cc.game.canvas.width, cc.game.canvas.height); } /** @@ -501,24 +463,20 @@ export class View extends EventTarget { * @zh 返回视图中边框尺寸。 * 在 native 平台下,它返回全屏视图下屏幕的尺寸。 * 在 web 平台下,它返回 canvas 元素的外层 DOM 元素尺寸。 - * @method getFrameSize - * @return {Size} */ - public getFrameSize () { - return cc.size(this._frameSize.width, this._frameSize.height); + public getFrameSize (): Size { + return new Size(this._frameSize.width, this._frameSize.height); } /** - * @en - * On native, it sets the frame size of view.
+ * @en On native, it sets the frame size of view.
* On web, it sets the size of the canvas's outer DOM element. * @zh 在 native 平台下,设置视图框架尺寸。 * 在 web 平台下,设置 canvas 外层 DOM 元素尺寸。 - * @method setFrameSize * @param {Number} width * @param {Number} height */ - public setFrameSize (width, height) { + public setFrameSize (width: number, height: number) { this._frameSize.width = width; this._frameSize.height = height; cc.frame.style.width = width + 'px'; @@ -527,72 +485,54 @@ export class View extends EventTarget { } /** - * @en - * Returns the visible area size of the view port. + * @en Returns the visible area size of the view port. * @zh 返回视图窗口可见区域尺寸。 - * @method getVisibleSize - * @return {Size} */ - public getVisibleSize () { - return cc.size(this._visibleRect.width, this._visibleRect.height); + public getVisibleSize (): Size { + return new Size(this._visibleRect.width, this._visibleRect.height); } /** - * @en - * Returns the visible area size of the view port. + * @en Returns the visible area size of the view port. * @zh 返回视图窗口可见区域像素尺寸。 - * @method getVisibleSizeInPixel - * @return {Size} */ - public getVisibleSizeInPixel () { - return cc.size( this._visibleRect.width * this._scaleX, + public getVisibleSizeInPixel (): Size { + return new Size( this._visibleRect.width * this._scaleX, this._visibleRect.height * this._scaleY ); } /** - * @en - * Returns the visible origin of the view port. + * @en Returns the visible origin of the view port. * @zh 返回视图窗口可见区域原点。 - * @method getVisibleOrigin - * @return {Vec2} */ - public getVisibleOrigin () { - return cc.v2(this._visibleRect.x, this._visibleRect.y); + public getVisibleOrigin (): Vec2 { + return new Vec2(this._visibleRect.x, this._visibleRect.y); } /** - * @en - * Returns the visible origin of the view port. + * @en Returns the visible origin of the view port. * @zh 返回视图窗口可见区域像素原点。 - * @method getVisibleOriginInPixel - * @return {Vec2} */ - public getVisibleOriginInPixel () { - return cc.v2(this._visibleRect.x * this._scaleX, + public getVisibleOriginInPixel (): Vec2 { + return new Vec2(this._visibleRect.x * this._scaleX, this._visibleRect.y * this._scaleY); } /** - * @en - * Returns the current resolution policy + * @en Returns the current resolution policy * @zh 返回当前分辨率方案 - * @see ResolutionPolicy - * @method getResolutionPolicy - * @return {ResolutionPolicy} + * @see {{ResolutionPolicy}} */ - public getResolutionPolicy () { + public getResolutionPolicy (): ResolutionPolicy { return this._resolutionPolicy; } /** - * @en - * Sets the current resolution policy + * @en Sets the current resolution policy * @zh 设置当前分辨率模式 - * @see ResolutionPolicy - * @method setResolutionPolicy - * @param {ResolutionPolicy|Number} resolutionPolicy + * @see {{ResolutionPolicy}} */ - public setResolutionPolicy (resolutionPolicy) { + public setResolutionPolicy (resolutionPolicy: ResolutionPolicy|number) { const _t = this; if (resolutionPolicy instanceof ResolutionPolicy) { _t._resolutionPolicy = resolutionPolicy; @@ -620,8 +560,7 @@ export class View extends EventTarget { // tslint:disable: max-line-length /** - * @en - * Sets the resolution policy with designed view size in points.
+ * @en Sets the resolution policy with designed view size in points.
* The resolution policy include:
* [1] ResolutionExactFit Fill screen by stretch-to-fit: if the design resolution ratio of width to height is different from the screen resolution ratio, your game view will be stretched.
* [2] ResolutionNoBorder Full screen without black border: if the design resolution ratio of width to height is different from the screen resolution ratio, two areas of your game view will be cut.
@@ -630,12 +569,11 @@ export class View extends EventTarget { * [5] ResolutionFixedWidth Scale the content's width to screen's width and proportionally scale its height
* [ResolutionPolicy] [Web only feature] Custom resolution policy, constructed by ResolutionPolicy
* @zh 通过设置设计分辨率和匹配模式来进行游戏画面的屏幕适配。 - * @method setDesignResolutionSize - * @param {Number} width Design resolution width. - * @param {Number} height Design resolution height. - * @param {ResolutionPolicy|Number} resolutionPolicy The resolution policy desired + * @param width Design resolution width. + * @param height Design resolution height. + * @param resolutionPolicy The resolution policy desired */ - public setDesignResolutionSize (width, height, resolutionPolicy) { + public setDesignResolutionSize (width: number, height: number, resolutionPolicy: ResolutionPolicy|number) { // Defensive code if ( !(width > 0 || height > 0) ){ cc.logID(2200); @@ -703,21 +641,17 @@ export class View extends EventTarget { } /** - * @en - * Returns the designed size for the view. + * @en Returns the designed size for the view. * Default resolution size is the same as 'getFrameSize'. * @zh 返回视图的设计分辨率。 * 默认下分辨率尺寸同 `getFrameSize` 方法相同 - * @method getDesignResolutionSize - * @return {Size} */ - public getDesignResolutionSize () { - return cc.size(this._designResolutionSize.width, this._designResolutionSize.height); + public getDesignResolutionSize (): Size { + return new Size(this._designResolutionSize.width, this._designResolutionSize.height); } /** - * @en - * Sets the container to desired pixel resolution and fit the game content to it. + * @en Sets the container to desired pixel resolution and fit the game content to it. * This function is very useful for adaptation in mobile browsers. * In some HD android devices, the resolution is very high, but its browser performance may not be very good. * In this case, enabling retina display is very costy and not suggested, and if retina is disabled, the image may be blurry. @@ -727,12 +661,11 @@ export class View extends EventTarget { * 2. Set body width to the exact pixel resolution * 3. The resolution policy will be reset with designed view size in points. * @zh 设置容器(container)需要的像素分辨率并且适配相应分辨率的游戏内容。 - * @method setRealPixelResolution - * @param {Number} width Design resolution width. - * @param {Number} height Design resolution height. - * @param {ResolutionPolicy|Number} resolutionPolicy The resolution policy desired + * @param width Design resolution width. + * @param height Design resolution height. + * @param resolutionPolicy The resolution policy desired */ - public setRealPixelResolution (width, height, resolutionPolicy) { + public setRealPixelResolution (width: number, height: number, resolutionPolicy: ResolutionPolicy|number) { if (!JSB && !MINIGAME) { // Set viewport's width this._setViewportMeta({width}, true); @@ -749,152 +682,47 @@ export class View extends EventTarget { } /** - * @en - * Sets view port rectangle with points. - * @zh 用设计分辨率下的点尺寸来设置视窗。 - * @method setViewportInPoints - * @deprecated since v2.0 - * @param {Number} x - * @param {Number} y - * @param {Number} w width - * @param {Number} h height - */ - public setViewportInPoints (x, y, w, h) { - const locScaleX = this._scaleX; - const locScaleY = this._scaleY; - cc.game._renderContext.viewport((x * locScaleX + this._viewportRect.x), - (y * locScaleY + this._viewportRect.y), - (w * locScaleX), - (h * locScaleY)); - } - - /** - * @en - * Sets Scissor rectangle with points. - * @zh 用设计分辨率下的点的尺寸来设置 scissor 剪裁区域。 - * @method setScissorInPoints - * @deprecated since v2.0 - * @param {Number} x - * @param {Number} y - * @param {Number} w - * @param {Number} h - */ - public setScissorInPoints (x, y, w, h) { - const scaleX = this._scaleX; - const scaleY = this._scaleY; - const sx = Math.ceil(x * scaleX + this._viewportRect.x); - const sy = Math.ceil(y * scaleY + this._viewportRect.y); - const sw = Math.ceil(w * scaleX); - const sh = Math.ceil(h * scaleY); - const gl = cc.game._renderContext; - - if (!_scissorRect) { - const boxArr = gl.getParameter(gl.SCISSOR_BOX); - _scissorRect = new Rect(boxArr[0], boxArr[1], boxArr[2], boxArr[3]); - } - - if (_scissorRect.x !== sx || _scissorRect.y !== sy || _scissorRect.width !== sw || _scissorRect.height !== sh) { - _scissorRect.x = sx; - _scissorRect.y = sy; - _scissorRect.width = sw; - _scissorRect.height = sh; - gl.scissor(sx, sy, sw, sh); - } - } - - /** - * @en - * Returns whether GL_SCISSOR_TEST is enable - * @zh 检查 scissor 是否生效。 - * @method isScissorEnabled - * @deprecated since v2.0 - * @return {Boolean} - */ - public isScissorEnabled () { - const gl = cc.game._renderContext; - return gl.isEnabled(gl.SCISSOR_TEST); - } - - /** - * @en - * Returns the current scissor rectangle - * @zh 返回当前的 scissor 剪裁区域。 - * @method getScissorRect - * @deprecated since v2.0 - * @return {Rect} - */ - public getScissorRect () { - const gl = cc.game._renderContext; - if (!_scissorRect) { - const boxArr = gl.getParameter(gl.SCISSOR_BOX); - _scissorRect = new Rect(boxArr[0], boxArr[1], boxArr[2], boxArr[3]); - } - const scaleXFactor = 1 / this._scaleX; - const scaleYFactor = 1 / this._scaleY; - return new Rect( - (_scissorRect.x - this._viewportRect.x) * scaleXFactor, - (_scissorRect.y - this._viewportRect.y) * scaleYFactor, - _scissorRect.width * scaleXFactor, - _scissorRect.height * scaleYFactor, - ); - } - - /** - * @en - * Returns the view port rectangle. + * @en Returns the view port rectangle. * @zh 返回视窗剪裁区域。 - * @method getViewportRect - * @return {Rect} */ - public getViewportRect () { + public getViewportRect (): Rect { return this._viewportRect; } /** - * @en - * Returns scale factor of the horizontal direction (X axis). + * @en Returns scale factor of the horizontal direction (X axis). * @zh 返回横轴的缩放比,这个缩放比是将画布像素分辨率放到设计分辨率的比例。 - * @method getScaleX - * @return {Number} */ - public getScaleX () { + public getScaleX (): number { return this._scaleX; } /** - * @en - * Returns scale factor of the vertical direction (Y axis). + * @en Returns scale factor of the vertical direction (Y axis). * @zh 返回纵轴的缩放比,这个缩放比是将画布像素分辨率缩放到设计分辨率的比例。 - * @method getScaleY - * @return {Number} */ - public getScaleY () { + public getScaleY (): number { return this._scaleY; } /** - * @en - * Returns device pixel ratio for retina display. + * @en Returns device pixel ratio for retina display. * @zh 返回设备或浏览器像素比例。 - * @method getDevicePixelRatio - * @return {Number} */ - public getDevicePixelRatio () { + public getDevicePixelRatio (): number { return this._devicePixelRatio; } /** - * @en - * Returns the real location in view for a translation based on a related position + * @en Returns the real location in view for a translation based on a related position * @zh 将屏幕坐标转换为游戏视图下的坐标。 - * @method convertToLocationInView - * @param {Number} tx - The X axis translation - * @param {Number} ty - The Y axis translation - * @param {Object} relatedPos - The related position object including "left", "top", "width", "height" informations - * @return {Vec2} + * @param tx - The X axis translation + * @param ty - The Y axis translation + * @param relatedPos - The related position object including "left", "top", "width", "height" informations + * @param out - The out object to save the conversion result */ - public convertToLocationInView (tx, ty, relatedPos, out) { - const result = out || cc.v2(); + public convertToLocationInView (tx: number, ty: number, relatedPos: any, out: Vec2): Vec2 { + const result = out || new Vec2(); const x = this._devicePixelRatio * (tx - relatedPos.left); const y = this._devicePixelRatio * (relatedPos.top + relatedPos.height - ty); if (this._isRotated) { @@ -914,7 +742,7 @@ export class View extends EventTarget { // in_out_point.y = (_t._devicePixelRatio * (relatedPos.top + relatedPos.height - in_out_point.y) - viewport.y) / _t._scaleY; // } - public _convertPointWithScale (point) { + private _convertPointWithScale (point) { const viewport = this._viewportRect; point.x = (point.x - viewport.x) / this._scaleX; point.y = (point.y - viewport.y) / this._scaleY; @@ -1103,10 +931,16 @@ export class View extends EventTarget { * !zh * 当设计分辨率改变时发送。 * @event design-resolution-changed - *

cc.game.containerStrategy class is the root strategy class of container's scale strategy, - * it controls the behavior of how to scale the cc.game.container and cc.game.canvas object

- * - * @class ContainerStrategy + */ + +interface AdaptResult { + scale: number[]; + viewport?: null | Rect; +} + +/** + * ContainerStrategy class is the root strategy class of container's scale strategy, + * it controls the behavior of how to scale the cc.game.container and cc.game.canvas object */ class ContainerStrategy { public static EQUAL_TO_FRAME: any; @@ -1115,34 +949,29 @@ class ContainerStrategy { public name: string = 'ContainerStrategy'; /** - * @en - * Manipulation before appling the strategy + * @en Manipulation before appling the strategy * @zh 在应用策略之前的操作 - * @method preApply - * @param {View} view - The target view + * @param view - The target view */ - public preApply (_view) { + public preApply (_view: View) { } /** - * @en - * Function to apply this strategy + * @en Function to apply this strategy * @zh 策略应用方法 - * @method apply - * @param {View} view - * @param {Size} designedResolution + * @param view + * @param designedResolution */ - public apply (_view, designedResolution) { + public apply (_view: View, designedResolution: Size) { } /** * @en * Manipulation after applying the strategy * @zh 策略调用之后的操作 - * @method postApply - * @param {View} view The target view + * @param view The target view */ - public postApply (_view) { + public postApply (_view: View) { } @@ -1187,8 +1016,8 @@ class ContainerStrategy { } /** - *

ContentStrategy class is the root strategy class of content's scale strategy, - * it controls the behavior of how to scale the scene and setup the viewport for the game

+ * ContentStrategy class is the root strategy class of content's scale strategy, + * it controls the behavior of how to scale the scene and setup the viewport for the game * * @class ContentStrategy */ @@ -1200,7 +1029,7 @@ class ContentStrategy { public static FIXED_WIDTH: any; public name = 'ContentStrategy'; - private _result: { scale: number[]; viewport: null | Rect; }; + private _result: AdaptResult; constructor () { this._result = { scale: [1, 1], @@ -1209,13 +1038,11 @@ class ContentStrategy { } /** - * @en - * Manipulation before applying the strategy + * @en Manipulation before applying the strategy * @zh 策略应用前的操作 - * @method preApply - * @param {View} view - The target view + * @param view - The target view */ - public preApply (_view) { + public preApply (_view: View) { } /** @@ -1223,26 +1050,21 @@ class ContentStrategy { * The return value is {scale: [scaleX, scaleY], viewport: {new Rect}}, * The target view can then apply these value to itself, it's preferred not to modify directly its private variables * @zh 调用策略方法 - * @method apply - * @param {View} view - * @param {Size} designedResolution - * @return {Object} scaleAndViewportRect + * @return The result scale and viewport rect */ - public apply (_view, designedResolution) { + public apply (_view: View, designedResolution: Size): AdaptResult { return {scale: [1, 1]}; } /** - * @en - * Manipulation after applying the strategy + * @en Manipulation after applying the strategy * @zh 策略调用之后的操作 - * @method postApply - * @param {View} view - The target view + * @param view - The target view */ - public postApply (_view) { + public postApply (_view: View) { } - public _buildResult (containerW, containerH, contentW, contentH, scaleX, scaleY) { + public _buildResult (containerW, containerH, contentW, contentH, scaleX, scaleY): AdaptResult { // Makes content fit better the canvas if ( Math.abs(containerW - contentW) < 2 ) { contentW = containerW; @@ -1262,7 +1084,6 @@ class ContentStrategy { } (() => { - // Container scale strategys /** * @class EqualToFrame @@ -1348,7 +1169,7 @@ class ContentStrategy { // Content scale strategys class ExactFit extends ContentStrategy { public name = 'ExactFit'; - public apply (_view, designedResolution) { + public apply (_view: View, designedResolution: Size) { const containerW = cc.game.canvas.width; const containerH = cc.game.canvas.height; const scaleX = containerW / designedResolution.width; @@ -1440,25 +1261,45 @@ class ContentStrategy { })(); /** - *

ResolutionPolicy class is the root strategy class of scale strategy, + * ResolutionPolicy class is the root strategy class of scale strategy, * its main task is to maintain the compatibility with Cocos2d-x

- * - * @class ResolutionPolicy - */ -/** - * @method constructor - * @param {ContainerStrategy} containerStg The container strategy - * @param {ContentStrategy} contentStg The content strategy */ export class ResolutionPolicy { - public static EXACT_FIT: number; - public static SHOW_ALL: number; - public static NO_BORDER: number; - public static FIXED_HEIGHT: number; - public static FIXED_WIDTH: number; - public static UNKNOWN: number; - public static ContainerStrategy: typeof ContainerStrategy; - public static ContentStrategy: typeof ContentStrategy; + /** + * The entire application is visible in the specified area without trying to preserve the original aspect ratio.
+ * Distortion can occur, and the application may appear stretched or compressed. + */ + public static EXACT_FIT: number = 0; + /** + * The entire application fills the specified area, without distortion but possibly with some cropping,
+ * while maintaining the original aspect ratio of the application. + */ + public static NO_BORDER: number = 1; + /** + * The entire application is visible in the specified area without distortion while maintaining the original
+ * aspect ratio of the application. Borders can appear on two sides of the application. + */ + public static SHOW_ALL: number = 2; + /** + * The application takes the height of the design resolution size and modifies the width of the internal
+ * canvas so that it fits the aspect ratio of the device
+ * no distortion will occur however you must make sure your application works on different
+ * aspect ratios + */ + public static FIXED_HEIGHT: number = 3; + /** + * The application takes the width of the design resolution size and modifies the height of the internal
+ * canvas so that it fits the aspect ratio of the device
+ * no distortion will occur however you must make sure your application works on different
+ * aspect ratios + */ + public static FIXED_WIDTH: number = 4; + /** + * Unknown policy + */ + public static UNKNOWN: number = 5; + public static ContainerStrategy: typeof ContainerStrategy = ContainerStrategy; + public static ContentStrategy: typeof ContentStrategy = ContentStrategy; public name = 'ResolutionPolicy'; @@ -1467,10 +1308,10 @@ export class ResolutionPolicy { /** * Constructor of ResolutionPolicy - * @param {ContainerStrategy} containerStg - * @param {ContentStrategy} contentStg + * @param containerStg + * @param contentStg */ - constructor (containerStg, contentStg) { + constructor (containerStg: ContainerStrategy, contentStg: ContentStrategy) { this._containerStrategy = null; this._contentStrategy = null; this.setContainerStrategy(containerStg); @@ -1484,10 +1325,9 @@ export class ResolutionPolicy { /** * @en Manipulation before applying the resolution policy * @zh 策略应用前的操作 - * @method preApply - * @param {View} _view The target view + * @param _view The target view */ - public preApply (_view) { + public preApply (_view: View) { this._containerStrategy!.preApply(_view); this._contentStrategy!.preApply(_view); } @@ -1497,12 +1337,11 @@ export class ResolutionPolicy { * The return value is {scale: [scaleX, scaleY], viewport: {new Rect}}, * The target view can then apply these value to itself, it's preferred not to modify directly its private variables * @zh 调用策略方法 - * @method apply - * @param {View} _view - The target view - * @param {Size} designedResolution - The user defined design resolution - * @return {Object} An object contains the scale X/Y values and the viewport rect + * @param _view - The target view + * @param designedResolution - The user defined design resolution + * @return An object contains the scale X/Y values and the viewport rect */ - public apply (_view, designedResolution) { + public apply (_view: View, designedResolution: Size) { this._containerStrategy!.apply(_view, designedResolution); return this._contentStrategy!.apply(_view, designedResolution); } @@ -1510,114 +1349,45 @@ export class ResolutionPolicy { /** * @en Manipulation after appyling the strategy * @zh 策略应用之后的操作 - * @method postApply - * @param {View} _view - The target view + * @param _view - The target view */ - public postApply (_view) { + public postApply (_view: View) { this._containerStrategy!.postApply(_view); this._contentStrategy!.postApply(_view); } /** - * @en - * Setup the container's scale strategy + * @en Setup the container's scale strategy * @zh 设置容器的适配策略 - * @method setContainerStrategy - * @param {ContainerStrategy} containerStg + * @param containerStg The container strategy */ - public setContainerStrategy (containerStg) { + public setContainerStrategy (containerStg: ContainerStrategy) { if (containerStg instanceof ContainerStrategy) { this._containerStrategy = containerStg; } } /** - * @en - * Setup the content's scale strategy + * @en Setup the content's scale strategy * @zh 设置内容的适配策略 - * @method setContentStrategy - * @param {ContentStrategy} contentStg + * @param contentStg The content strategy */ - public setContentStrategy (contentStg) { + public setContentStrategy (contentStg: ContentStrategy) { if (contentStg instanceof ContentStrategy) { this._contentStrategy = contentStg; } } } - -/** - * The entire application is visible in the specified area without trying to preserve the original aspect ratio.
- * Distortion can occur, and the application may appear stretched or compressed. - * @property {Number} EXACT_FIT - * @readonly - * @static - */ -ResolutionPolicy.EXACT_FIT = 0; - -/** - * The entire application fills the specified area, without distortion but possibly with some cropping,
- * while maintaining the original aspect ratio of the application. - * @property {Number} NO_BORDER - * @readonly - * @static - */ -ResolutionPolicy.NO_BORDER = 1; - -/** - * The entire application is visible in the specified area without distortion while maintaining the original
- * aspect ratio of the application. Borders can appear on two sides of the application. - * @property {Number} SHOW_ALL - * @readonly - * @static - */ -ResolutionPolicy.SHOW_ALL = 2; - -/** - * The application takes the height of the design resolution size and modifies the width of the internal
- * canvas so that it fits the aspect ratio of the device
- * no distortion will occur however you must make sure your application works on different
- * aspect ratios - * @property {Number} FIXED_HEIGHT - * @readonly - * @static - */ -ResolutionPolicy.FIXED_HEIGHT = 3; - -/** - * The application takes the width of the design resolution size and modifies the height of the internal
- * canvas so that it fits the aspect ratio of the device
- * no distortion will occur however you must make sure your application works on different
- * aspect ratios - * @property {Number} FIXED_WIDTH - * @readonly - * @static - */ -ResolutionPolicy.FIXED_WIDTH = 4; - -/** - * Unknow policy - * @property {Number} UNKNOWN - * @readonly - * @static - */ -ResolutionPolicy.UNKNOWN = 5; - -ResolutionPolicy.ContainerStrategy = ContainerStrategy; -ResolutionPolicy.ContentStrategy = ContentStrategy; cc.ResolutionPolicy = ResolutionPolicy; /** - * @module cc - */ - -/** - * @en cc.view is the shared view object. - * @zh cc.view 是全局的视图对象。 + * @en view is the singleton view object. + * @zh view 是全局的视图单例对象。 */ export const view = View.instance = cc.view = new View(); /** - * @en cc.winSize is the alias object for the size of the current game window. - * @zh cc.winSize 为当前的游戏窗口的大小。 + * @en winSize is the alias object for the size of the current game window. + * @zh winSize 为当前的游戏窗口的大小。 */ -cc.winSize = cc.v2(); +cc.winSize = new Vec2(); diff --git a/cocos/core/splash-screen-webgl.ts b/cocos/core/splash-screen-webgl.ts index 525c673993..2f52aff563 100644 --- a/cocos/core/splash-screen-webgl.ts +++ b/cocos/core/splash-screen-webgl.ts @@ -6,7 +6,7 @@ import { IGFXColor } from "./gfx"; import { clamp01 } from "./math"; import { easing } from "./animation"; import { macro } from "./platform"; -import sys from "./platform/sys"; +import { sys } from "./platform/sys"; import { COCOSPLAY, XIAOMI, JSB } from 'internal:constants'; type SplashEffectType = 'none' | 'Fade-InOut'; diff --git a/cocos/ui/assembler/label/index.ts b/cocos/ui/assembler/label/index.ts index 2c2eee4612..01746124bd 100644 --- a/cocos/ui/assembler/label/index.ts +++ b/cocos/ui/assembler/label/index.ts @@ -34,7 +34,7 @@ import { bmfont } from './bmfont'; import { CanvasPool } from './font-utils'; import { letter } from './letter'; import { ttf } from './ttf'; -import sys from '../../../core/platform/sys'; +import { sys } from '../../../core/platform/sys'; import { warn } from '../../../core/platform/debug'; const labelAssembler: IAssemblerManager = { diff --git a/cocos/ui/components/editbox/edit-box-component.ts b/cocos/ui/components/editbox/edit-box-component.ts index 8508e0bc4b..138583292d 100644 --- a/cocos/ui/components/editbox/edit-box-component.ts +++ b/cocos/ui/components/editbox/edit-box-component.ts @@ -42,7 +42,7 @@ import { SpriteComponent } from '../sprite-component'; import { EditBoxImpl } from './edit-box-impl'; import { EditBoxImplBase } from './edit-box-impl-base'; import { InputFlag, InputMode, KeyboardReturnType } from './types'; -import sys from '../../../core/platform/sys'; +import { sys } from '../../../core/platform/sys'; import { EDITOR } from 'internal:constants'; const LEFT_PADDING = 2; diff --git a/cocos/ui/components/editbox/edit-box-impl.ts b/cocos/ui/components/editbox/edit-box-impl.ts index 2f6ae83553..4f9bb1dc8e 100644 --- a/cocos/ui/components/editbox/edit-box-impl.ts +++ b/cocos/ui/components/editbox/edit-box-impl.ts @@ -41,7 +41,7 @@ import { LabelComponent } from '../label-component'; import { EditBoxComponent} from './edit-box-component'; import { tabIndexUtil } from './tabIndexUtil'; import { InputFlag, InputMode, KeyboardReturnType } from './types'; -import sys from '../../../core/platform/sys'; +import { sys } from '../../../core/platform/sys'; import visibleRect from '../../../core/platform/visible-rect'; import { Node } from '../../../core'; import { EditBoxImplBase } from './edit-box-impl-base'; diff --git a/cocos/ui/components/label-component.ts b/cocos/ui/components/label-component.ts index a9f26e8735..a1f449c91d 100644 --- a/cocos/ui/components/label-component.ts +++ b/cocos/ui/components/label-component.ts @@ -37,7 +37,7 @@ import { CanvasPool, ISharedLabelData } from '../assembler/label/font-utils'; import { LetterRenderTexture } from '../assembler/label/letter-font'; import { UIRenderComponent } from '../../core/components/ui-base/ui-render-component'; import { warnID } from '../../core/platform/debug'; -import sys from '../../core/platform/sys'; +import { sys } from '../../core/platform/sys'; import { EDITOR } from 'internal:constants'; /** diff --git a/cocos/ui/components/webview/webview-impl.ts b/cocos/ui/components/webview/webview-impl.ts index 1958cd7b6f..19344b1074 100644 --- a/cocos/ui/components/webview/webview-impl.ts +++ b/cocos/ui/components/webview/webview-impl.ts @@ -28,7 +28,7 @@ */ import { ccclass } from '../../../core/data/class-decorator'; -import sys from '../../../core/platform/sys'; +import { sys } from '../../../core/platform/sys'; import { misc } from '../../../core/utils'; import { Mat4 } from '../../../core/math'; import { UIRenderComponent } from '../../../core/components/ui-base/ui-render-component'; diff --git a/cocos/ui/components/widget-manager.ts b/cocos/ui/components/widget-manager.ts index daa7c5c5f9..e29fc5eb86 100644 --- a/cocos/ui/components/widget-manager.ts +++ b/cocos/ui/components/widget-manager.ts @@ -29,10 +29,9 @@ */ import { CanvasComponent } from '../../core/components/ui-base/canvas-component'; -import { UIRenderComponent } from '../../core/components/ui-base/ui-render-component'; import { Director, director } from '../../core/director'; import { Vec2, Vec3 } from '../../core/math'; -import sys from '../../core/platform/sys'; +import { sys } from '../../core/platform/sys'; import { View } from '../../core/platform/view'; import visibleRect from '../../core/platform/visible-rect'; import { Scene } from '../../core/scene-graph';