diff --git a/EngineErrorMap.md b/EngineErrorMap.md index 126c1c66c00..c31339ff6e8 100644 --- a/EngineErrorMap.md +++ b/EngineErrorMap.md @@ -38,7 +38,7 @@ loadScene: Unknown name type to load: '%s' ### 1208 -loadScene: Failed to load scene '%s' because '%s' is already loading +loadScene: Failed to load scene '%s' because '%s' is already being loaded. ### 1209 diff --git a/cocos/core/components/component-event-handler.ts b/cocos/core/components/component-event-handler.ts index 7f96af63697..9e9092606c6 100644 --- a/cocos/core/components/component-event-handler.ts +++ b/cocos/core/components/component-event-handler.ts @@ -33,11 +33,25 @@ import { Node } from '../scene-graph'; import { legacyCC } from '../global-exports'; /** + * @en + * Component will register a event to target component's handler. And it will trigger the handler when a certain event occurs. + * * @zh * “EventHandler” 类用来设置场景中的事件回调,该类允许用户设置回调目标节点,目标组件名,组件方法名,并可通过 emit 方法调用目标函数。 * * @example * ```ts + * // Let's say we have a MainMenu component on newTarget + * // file: MainMenu.ts + * @ccclass('MainMenu') + * export class MainMenu extends Component { + * // sender: the node MainMenu.ts belongs to + * // eventType: CustomEventData + * onClick (sender, eventType) { + * cc.log('click'); + * } + * } + * * import { Component } from 'cc'; * const eventHandler = new Component.EventHandler(); * eventHandler.target = newTarget; @@ -59,6 +73,8 @@ export class EventHandler { } /** + * @en + * For component event emit * @zh * 组件事件派发。 * @@ -76,14 +92,18 @@ export class EventHandler { } } /** + * @en + * The node that contains target callback, such as the node example script belongs to * @zh - * 目标节点。 + * 事件响应函数所在节点 ,比如例子中脚本归属的节点本身 */ @type(legacyCC.Node) public target: Node | null = null; /** + * @en + * The name of the component(script) that contains target callback, such as the name 'MainMenu' of script in example * @zh - * 目标组件名。 + * 事件响应函数所在组件名(脚本名), 比如例子中的脚本名 'MainMenu' */ // only for deserializing old project component field @property @@ -93,20 +113,26 @@ export class EventHandler { public _componentId = ''; /** + * @en + * Event handler, such as function's name 'onClick' in example * @zh - * 响应事件函数名。 + * 响应事件函数名,比如例子中的 'onClick' */ @property public handler = ''; /** + * @en + * Custom Event Data, such as 'eventType' in example * @zh - * 自定义事件数据。 + * 自定义事件数据,比如例子中的 eventType */ @property public customEventData = ''; /** + * @en + * Emit event with params * @zh * 触发目标组件上的指定 handler 函数,该参数是回调函数的参数值(可不填)。 * diff --git a/cocos/core/components/component.ts b/cocos/core/components/component.ts index 2663a5ae9b6..e0c8f189c8e 100644 --- a/cocos/core/components/component.ts +++ b/cocos/core/components/component.ts @@ -418,9 +418,10 @@ class Component extends CCObject { */ public schedule (callback, interval: number = 0, repeat: number = legacyCC.macro.REPEAT_FOREVER, delay: number = 0) { assertID(callback, 1619); - assertID(interval >= 0, 1620); interval = interval || 0; + assertID(interval >= 0, 1620); + repeat = isNaN(repeat) ? legacyCC.macro.REPEAT_FOREVER : repeat; delay = delay || 0; diff --git a/cocos/core/director.ts b/cocos/core/director.ts index 8fdc4f87e2f..215641c2d76 100644 --- a/cocos/core/director.ts +++ b/cocos/core/director.ts @@ -47,7 +47,7 @@ import { Scheduler } from './scheduler'; import { js } from './utils'; import { DEBUG, EDITOR, BUILD } from 'internal:constants'; import { legacyCC } from './global-exports'; -import { errorID, error, logID, assertID } from './platform/debug'; +import { errorID, error, logID, assertID, warnID } from './platform/debug'; // ---------------------------------------------------------------------------------------------------------------------- @@ -270,6 +270,7 @@ export class Director extends EventTarget { private _totalFrames: number; private _lastUpdate: number; private _deltaTime: number; + private _startTime: number; private _scheduler: Scheduler; private _systems: System[]; @@ -293,6 +294,7 @@ export class Director extends EventTarget { this._totalFrames = 0; this._lastUpdate = 0; this._deltaTime = 0.0; + this._startTime = 0.0; // Scheduler for user registration update this._scheduler = new Scheduler(); @@ -309,8 +311,8 @@ export class Director extends EventTarget { /** * calculates delta time since last time it was called */ - public calculateDeltaTime () { - const now = performance.now(); + public calculateDeltaTime (now) { + if (!now) now = performance.now(); this._deltaTime = now > this._lastUpdate ? (now - this._lastUpdate) / 1000 : 0; if (DEBUG && (this._deltaTime > 1)) { @@ -640,7 +642,7 @@ export class Director extends EventTarget { */ public loadScene (sceneName: string, onLaunched?: Director.OnSceneLaunched, onUnloaded?: Director.OnUnload) { if (this._loadingScene) { - errorID(1208, sceneName, this._loadingScene); + warnID(1208, sceneName, this._loadingScene); return false; } const info = this._getSceneUuid(sceneName); @@ -904,6 +906,14 @@ export class Director extends EventTarget { return this._deltaTime; } + /** + * @en Returns the total passed time since game start, unit: ms + * @zh 获取从游戏开始到现在总共经过的时间,单位为 ms + */ + public getTotalTime () { + return performance.now() - this._startTime; + } + /** * @en Returns the current time. * @zh 获取当前帧的时间。 @@ -1013,7 +1023,7 @@ export class Director extends EventTarget { } else if (!this._invalid) { // calculate "global" dt - this.calculateDeltaTime(); + this.calculateDeltaTime(time); const dt = this._deltaTime; // Update @@ -1053,6 +1063,7 @@ export class Director extends EventTarget { private _initOnRendererInitialized () { this._totalFrames = 0; this._lastUpdate = performance.now(); + this._startTime = this._lastUpdate; this._paused = false; this._purgeDirectorInNextLoop = false; diff --git a/cocos/core/game.ts b/cocos/core/game.ts index a9c1d6b6d9d..92bd7edef15 100644 --- a/cocos/core/game.ts +++ b/cocos/core/game.ts @@ -229,8 +229,7 @@ export interface IGameConfig { /** * @en An object to boot the game. * @zh 包含游戏主体信息并负责驱动游戏的游戏对象。 - * @class game - * @static + * @class Game */ export class Game extends EventTarget { /** @@ -987,10 +986,11 @@ export class Game extends EventTarget { legacyCC.game.emit(Game.EVENT_HIDE); } } - function onShown () { + // In order to adapt the most of platforms the onshow API. + function onShown (arg0?, arg1?, arg2?, arg3?, arg4?) { if (hidden) { hidden = false; - legacyCC.game.emit(Game.EVENT_SHOW); + legacyCC.game.emit(Game.EVENT_SHOW, arg0, arg1, arg2, arg3, arg4); } } @@ -1067,4 +1067,11 @@ export class Game extends EventTarget { } legacyCC.Game = Game; -export const game = legacyCC.game = new Game(); \ No newline at end of file + +/** + * @en + * This is a Game instance. + * @zh + * 这是一个 Game 类的实例,包含游戏主体信息并负责驱动游戏的游戏对象。 + */ +export const game = legacyCC.game = new Game(); diff --git a/cocos/core/platform/event-manager/events.ts b/cocos/core/platform/event-manager/events.ts index f3fd76308b9..b876842574b 100644 --- a/cocos/core/platform/event-manager/events.ts +++ b/cocos/core/platform/event-manager/events.ts @@ -535,7 +535,7 @@ export class EventTouch extends Event { /** * @en Returns the start touch location. - * @zh 获获取触点落下时的位置对象,对象包含 x 和 y 属性。 + * @zh 获取触点落下时的位置对象,对象包含 x 和 y 属性。 * @param out - Pass the out object to avoid object creation, very good practice */ public getStartLocation (out?: Vec2) { @@ -544,7 +544,7 @@ export class EventTouch extends Event { /** * @en Returns the start touch location in UI coordinates. - * @zh 获获取触点落下时的 UI 世界下位置对象,对象包含 x 和 y 属性。 + * @zh 获取触点落下时的 UI 世界下位置对象,对象包含 x 和 y 属性。 * @param out - Pass the out object to avoid object creation, very good practice */ public getUIStartLocation(out?: Vec2) { diff --git a/cocos/core/platform/event-manager/touch.ts b/cocos/core/platform/event-manager/touch.ts index 756d77db8d0..101453c3319 100644 --- a/cocos/core/platform/event-manager/touch.ts +++ b/cocos/core/platform/event-manager/touch.ts @@ -151,7 +151,7 @@ export class Touch { /** * @en Returns the start touch location. - * @zh 获获取触点落下时的位置对象,对象包含 x 和 y 属性。 + * @zh 获取触点落下时的位置对象,对象包含 x 和 y 属性。 * @param out - Pass the out object to avoid object creation, very good practice */ public getStartLocation (out?: Vec2) { @@ -165,7 +165,7 @@ export class Touch { /** * @en Returns the start touch location in UI coordinates. - * @zh 获获取触点落下时在 UI 坐标系中的位置对象,对象包含 x 和 y 属性。 + * @zh 获取触点落下时在 UI 坐标系中的位置对象,对象包含 x 和 y 属性。 * @param out - Pass the out object to avoid object creation, very good practice */ public getUIStartLocation (out?: Vec2) { diff --git a/cocos/core/scene-graph/node.ts b/cocos/core/scene-graph/node.ts index cbdbea49b33..eac4d0cc9bd 100644 --- a/cocos/core/scene-graph/node.ts +++ b/cocos/core/scene-graph/node.ts @@ -992,8 +992,13 @@ export class Node extends BaseNode { } /** - * @en Pause all system events which is dispatched by [[SystemEvent]] - * @zh 暂停所有 [[SystemEvent]] 派发的系统事件 + * @en + * Pause all system events which is dispatched by [[SystemEvent]]. + * If recursive is set to true, then this API will pause the node system events for the node and all nodes in its sub node tree. + * @zh + * 暂停所有 [[SystemEvent]] 派发的系统事件。 + * 如果传递 recursive 为 true,那么这个 API 将暂停本节点和它的子树上所有节点的节点系统事件。 + * * @param recursive Whether pause system events recursively for the child node tree */ public pauseSystemEvents (recursive: boolean): void { @@ -1002,8 +1007,14 @@ export class Node extends BaseNode { } /** - * @en Resume all paused system events which is dispatched by [[SystemEvent]] - * @zh 恢复所有 [[SystemEvent]] 派发的系统事件 + * @en + * Resume all paused system events which is dispatched by [[SystemEvent]]. + * If recursive is set to true, then this API will resume the node system events for the node and all nodes in its sub node tree. + * + * @zh + * 恢复所有 [[SystemEvent]] 派发的系统事件。 + * 如果传递 recursive 为 true,那么这个 API 将恢复本节点和它的子树上所有节点的节点系统事件。 + * * @param recursive Whether resume system events recursively for the child node tree */ public resumeSystemEvents (recursive: boolean): void { diff --git a/cocos/core/scheduler.ts b/cocos/core/scheduler.ts index f35d010a503..cf8f1039da9 100644 --- a/cocos/core/scheduler.ts +++ b/cocos/core/scheduler.ts @@ -683,10 +683,10 @@ export class Scheduler extends System { /** * @en - * Unschedules a callback for a callback and a given target.
+ * Unschedules a callback for a callback and a given target. * If you want to unschedule the "update", use `unscheduleUpdate()` * @zh - * 根据指定的回调函数和调用对象。
+ * 取消指定对象定时器。 * 如果需要取消 update 定时器,请使用 unscheduleUpdate()。 * @param {Function} callback The callback to be unscheduled * @param {Object} target The target bound to the callback. @@ -807,7 +807,7 @@ export class Scheduler extends System { * You should NEVER call this method, unless you know what you are doing. * @zh * 取消所有对象的所有定时器,包括系统定时器。
- * 不用调用此函数,除非你确定你在做什么。 + * 不要调用此函数,除非你确定你在做什么。 */ public unscheduleAll (){ this.unscheduleAllWithMinPriority(legacyCC.Scheduler.PRIORITY_SYSTEM); diff --git a/cocos/ui/components/button-component.ts b/cocos/ui/components/button-component.ts index 1fd6e0a7a4f..f8936698f09 100644 --- a/cocos/ui/components/button-component.ts +++ b/cocos/ui/components/button-component.ts @@ -109,27 +109,33 @@ export enum EventType { * User can get the current clicked node with 'event.target' from event object which is passed as parameter in the callback function of click event. * * @zh - * 按钮组件。可以被按下,或者点击。
+ * 按钮组件。可以被按下,或者点击。 * - * 按钮可以通过修改 Transition 来设置按钮状态过渡的方式:
- * - `Button.Transition.NONE` // 不做任何过渡
- * - `Button.Transition.COLOR` // 进行颜色之间过渡
- * - `Button.Transition.SPRITE` // 进行精灵之间过渡
- * - `Button.Transition.SCALE` // 进行缩放过渡
+ * 按钮可以通过修改 Transition 来设置按钮状态过渡的方式: + * + * - Button.Transition.NONE // 不做任何过渡 + * - Button.Transition.COLOR // 进行颜色之间过渡 + * - Button.Transition.SPRITE // 进行精灵之间过渡 + * - Button.Transition.SCALE // 进行缩放过渡 * * 按钮可以绑定事件(但是必须要在按钮的 Node 上才能绑定事件):
- * // 以下事件可以在全平台上都触发
- * - `Node.EventType.TOUCH_START` // 按下时事件
- * - `Node.EventType.TOUCH_Move` // 按住移动后事件
- * - `Node.EventType.TOUCH_END` // 按下后松开后事件
- * - `Node.EventType.TOUCH_CANCEL` // 按下取消事件
- * // 以下事件只在 PC 平台上触发
- * - `Node.EventType.MOUSE_DOWN` // 鼠标按下时事件
- * - `Node.EventType.MOUSE_MOVE` // 鼠标按住移动后事件
- * - `Node.EventType.MOUSE_ENTER` // 鼠标进入目标事件
- * - `Node.EventType.MOUSE_LEAVE` // 鼠标离开目标事件
- * - `Node.EventType.MOUSE_UP` // 鼠标松开事件
- * - `Node.EventType.MOUSE_WHEEL` // 鼠标滚轮事件
+ * 以下事件可以在全平台上都触发: + * + * - cc.Node.EventType.TOUCH_START // 按下时事件 + * - cc.Node.EventType.TOUCH_Move // 按住移动后事件 + * - cc.Node.EventType.TOUCH_END // 按下后松开后事件 + * - cc.Node.EventType.TOUCH_CANCEL // 按下取消事件 + * + * 以下事件只在 PC 平台上触发: + * + * - cc.Node.EventType.MOUSE_DOWN // 鼠标按下时事件 + * - cc.Node.EventType.MOUSE_MOVE // 鼠标按住移动后事件 + * - cc.Node.EventType.MOUSE_ENTER // 鼠标进入目标事件 + * - cc.Node.EventType.MOUSE_LEAVE // 鼠标离开目标事件 + * - cc.Node.EventType.MOUSE_UP // 鼠标松开事件 + * - cc.Node.EventType.MOUSE_WHEEL // 鼠标滚轮事件 + * + * 用户可以通过获取 __点击事件__ 回调函数的参数 event 的 target 属性获取当前点击对象。 * * @example * ```ts diff --git a/cocos/ui/components/label-component.ts b/cocos/ui/components/label-component.ts index 0a7d31d2a6a..9df157b75a1 100644 --- a/cocos/ui/components/label-component.ts +++ b/cocos/ui/components/label-component.ts @@ -119,7 +119,7 @@ export enum Overflow { * @en In SHRINK mode, the font size will change dynamically to adapt the content size. * This mode may takes up more CPU resources when the label is refreshed. * - * @zh SHRINK 模式,字体大小会动态变化,以适应内容大小。 + * @zh SHRINK 模式,字体大小会动态变化,以适应内容大小。这个模式在文本刷新的时候可能会占用较多 CPU 资源。 */ SHRINK = 2, /** diff --git a/cocos/ui/components/slider-component.ts b/cocos/ui/components/slider-component.ts index 49193f59b9e..152e86aa9c8 100644 --- a/cocos/ui/components/slider-component.ts +++ b/cocos/ui/components/slider-component.ts @@ -157,7 +157,7 @@ export class SliderComponent extends Component { * The slider slide events' callback array. * * @zh - * 滑动器组件事件回调函数。 + * 滑动器组件滑动事件回调函数数组。 */ @type([EventHandler]) @tooltip('滑动器组件事件回调函数')