diff --git a/cocos/core/platform/debug.ts b/cocos/core/platform/debug.ts index 6d89d513c1..4eedf05074 100644 --- a/cocos/core/platform/debug.ts +++ b/cocos/core/platform/debug.ts @@ -49,17 +49,22 @@ let ccAssert = (condition: any, message?: any, ...optionalParams: any[]) => { let ccDebug = ccLog; +/** + * @en Format a string. + * @zh 格式化字符串。 + * @param message @zh 包含零个或多个需要替换的JavaScript字符串。@en JavaScript objects to replace substitution strings in msg. + * @param optionalParams @zh 用来替换在message中需要替换的JavaScript对象。@en JavaScript objects with which to replace substitution strings within msg. + */ function formatString (message?: any, ...optionalParams: any[]) { // eslint-disable-next-line @typescript-eslint/no-unsafe-return return legacyCC.js.formatStr.apply(null, [message].concat(optionalParams)); } /** - * @en Outputs a message to the Cocos Creator Console (editor) or Web Console (runtime). - * @zh 输出一条消息到 Cocos Creator 编辑器的 Console 或运行时 Web 端的 Console 中。 - * @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. + * @en Outputs a message to the Cocos Creator Console (editor) or Web Console (runtime). This gives you additional control over the format of the output. + * @zh 输出一条消息到 Cocos Creator 编辑器的 Console 或运行时 Web 端的 Console 中。这为你提供了对输出格式的额外控制。 + * @param message @zh 包含零个或多个需要替换的JavaScript字符串。@en JavaScript objects to replace substitution strings in msg. + * @param optionalParams @zh 用来替换在message中需要替换的JavaScript对象。@en JavaScript objects with which to replace substitution strings within msg. */ export function log (message?: any, ...optionalParams: any[]) { return ccLog(message, ...optionalParams); @@ -74,8 +79,8 @@ export function log (message?: any, ...optionalParams: any[]) { * 输出警告消息到 Cocos Creator 编辑器的 Console 或运行时 Web 端的 Console 中。
* - 在 Cocos Creator 中,警告信息显示是黄色的。
* - 在 Chrome 中,警告信息有着黄色的图标以及黄色的消息文本。
- * @param message - A JavaScript string containing zero or more substitution strings. - * @param optionalParams - JavaScript objects with which to replace substitution strings within msg. + * @param message @zh 包含零个或多个需要替换的JavaScript字符串。@en JavaScript objects to replace substitution strings in msg. + * @param optionalParams @zh 用来替换在message中需要替换的JavaScript对象。@en JavaScript objects with which to replace substitution strings within msg. * This gives you additional control over the format of the output. */ export function warn (message?: any, ...optionalParams: any[]) { @@ -91,8 +96,8 @@ export function warn (message?: any, ...optionalParams: any[]) { * 输出错误消息到 Cocos Creator 编辑器的 Console 或运行时页面端的 Console 中。
* - 在 Cocos Creator 中,错误信息显示是红色的。
* - 在 Chrome 中,错误信息有红色的图标以及红色的消息文本。
- * @param message - A JavaScript string containing zero or more substitution strings. - * @param optionalParams - JavaScript objects with which to replace substitution strings within msg. + * @param message @zh 包含零个或多个需要替换的JavaScript字符串。@en JavaScript objects to replace substitution strings in msg. + * @param optionalParams @zh 用来替换在message中需要替换的JavaScript对象。@en JavaScript objects with which to replace substitution strings within msg. * This gives you additional control over the format of the output. */ export function error (message?: any, ...optionalParams: any[]) { @@ -104,9 +109,9 @@ export function error (message?: any, ...optionalParams: any[]) { * 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. + * @param value @zh 需要检查的条件。 @en The condition to check on. + * @param message @zh 包含零个或多个需要替换的JavaScript字符串。@en JavaScript objects to replace substitution strings in msg. + * @param optionalParams @zh 用来替换在message中需要替换的JavaScript对象。@en 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[]): asserts value { @@ -116,6 +121,7 @@ export function assert (value: any, message?: string, ...optionalParams: any[]): /** * @en Outputs a message at the "debug" log level. * @zh 输出一条“调试”日志等级的消息。 + * @param data @zh 输出的消息对象。 @en The output message object. */ export function debug (...data: any[]) { return ccDebug(...data); @@ -361,6 +367,8 @@ export enum DebugMode { /** * @en Gets error message with the error id and possible parameters. * @zh 通过 error id 和必要的参数来获取错误信息。 + * @param errorId @zh 错误的ID。@en Error id. + * @param param @zh 输出日志。@en Output log. */ export function getError (errorId: number, ...param: any[]): string { // eslint-disable-next-line @typescript-eslint/no-unsafe-return @@ -370,7 +378,7 @@ export function getError (errorId: number, ...param: any[]): string { /** * @en Returns whether or not to display the FPS and debug information. * @zh 是否显示 FPS 信息和部分调试信息。 - * @deprecated Since v3.6, Please use profiler.isShowingStates instead + * @deprecated @zh 从v3.6开始不再支持,请使用 profiler.isShowingStates。@en Since v3.6, Please use profiler.isShowingStates instead. */ export function isDisplayStats (): boolean { // eslint-disable-next-line @typescript-eslint/no-unsafe-return @@ -380,7 +388,7 @@ export function isDisplayStats (): boolean { /** * @en Sets whether display the FPS and debug informations on the bottom-left corner. * @zh 设置是否在左下角显示 FPS 和部分调试。 - * @deprecated Since v3.6, Please use profiler.showStats instead + * @deprecated @zh 从v3.6开始不再支持,请使用 profiler.showStats。@en Since v3.6, Please use profiler.showStats instead. */ export function setDisplayStats (displayStats: boolean) { if (legacyCC.profiler) { diff --git a/cocos/core/platform/screen.ts b/cocos/core/platform/screen.ts index c853ec93fb..f73c355286 100644 --- a/cocos/core/platform/screen.ts +++ b/cocos/core/platform/screen.ts @@ -57,7 +57,7 @@ class Screen { * @en the ratio of the resolution in physical pixels to the resolution in CSS pixels for the current display device * NOTE: For performance reasons, the engine will limit the maximum value of DPR on some platforms. * This property returns the DPR after the engine limit. - * @zh 当前显示设备的物理像素分辨率与 CSS 像素分辨率之比 + * @zh 当前显示设备的物理像素分辨率与 CSS 像素分辨率之比。 * 注意:出于性能考虑,引擎在一些平台会限制 DPR 的最高值,这个属性返回的是引擎限制后的 DPR。 */ public get devicePixelRatio () { @@ -108,8 +108,8 @@ class Screen { // } /** - * @en Whether it supports full screen? - * @zh 是否支持全屏? + * @en Whether it supports full screen. + * @zh 是否支持全屏。 * @returns {Boolean} */ public get supportsFullScreen (): boolean { @@ -118,7 +118,7 @@ class Screen { /** * @en Return true if it's in full screen state now. - * @zh 当前是否处在全屏状态下 + * @zh 当前是否处在全屏状态下。 * @returns {boolean} */ public fullScreen (): boolean { @@ -131,9 +131,9 @@ class Screen { * If failed to request fullscreen, another attempt will be made to request fullscreen the next time a user interaction occurs. * @zh 尝试使当前节点进入全屏模式,很多浏览器不允许程序触发这样的行为,必须在一个用户交互回调中才会生效。 * 如果进入全屏失败,会在下一次用户发生交互时,再次尝试进入全屏。 - * @param element The element to request full screen state - * @param onFullScreenChange callback function when full screen state changed - * @param onFullScreenError callback function when full screen error + * @param element @zh 请求全屏状态的html元素。 @en The element to request full screen state. + * @param onFullScreenChange @zh 全屏状态改变的回调函数。 @en callback function when full screen state changed. + * @param onFullScreenError @zh 全屏错误的回调函数。 @en callback function when full screen error. * @return {Promise|undefined} * @deprecated since v3.3, please use `screen.requestFullScreen(): Promise` instead. */ @@ -144,6 +144,9 @@ class Screen { * If failed to request fullscreen, another attempt will be made to request fullscreen the next time a user interaction occurs. * @zh 尝试使当前屏幕进入全屏模式,很多浏览器不允许程序触发这样的行为,必须在一个用户交互回调中才会生效。 * 如果进入全屏失败,会在下一次用户发生交互时,再次尝试进入全屏。 + * @param element @zh 请求全屏状态的html元素。 @en The element to request full screen state. + * @param onFullScreenChange @zh 全屏状态改变的回调函数。 @en callback function when full screen state changed. + * @param onFullScreenError @zh 全屏错误的回调函数。 @en callback function when full screen error. * @return {Promise} */ public requestFullScreen (): Promise; @@ -163,7 +166,7 @@ class Screen { /** * @en Exit the full mode. - * @zh 退出全屏模式 + * @zh 退出全屏模式。 * @return {Promise} */ public exitFullScreen (): Promise { @@ -171,10 +174,10 @@ class Screen { } /** - * @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 + * @en Automatically request full screen during the next touch/click event. + * @zh 自动监听触摸、鼠标事件并在下一次事件触发时尝试进入全屏模式。 + * @param element @zh 请求全屏状态的html元素。 @en The element to request full screen state. + * @param onFullScreenChange @zh 全屏状态改变的回调函数。 @en callback function when full screen state changed. * * @deprecated since v3.3, please use screen.requestFullScreen() instead. */ diff --git a/cocos/core/platform/sys.ts b/cocos/core/platform/sys.ts index cef014fc9e..adee21bab3 100644 --- a/cocos/core/platform/sys.ts +++ b/cocos/core/platform/sys.ts @@ -45,8 +45,8 @@ export declare namespace sys { } /** - * @en A set of system related variables - * @zh 一系列系统相关环境变量 + * @en A set of system related variables. + * @zh 一系列系统相关环境变量。 */ export const sys = { Feature, @@ -56,6 +56,7 @@ export const sys = { * Returns if the specified platform related feature is supported. * @zh * 返回指定的平台相关的特性是否支持。 + * @param feature @zh 系统的特性。 @en Feature of the system. */ hasFeature (feature: sys.Feature): boolean { return systemInfo.hasFeature(feature); @@ -63,77 +64,77 @@ export const sys = { /** * @en - * Network type enumeration + * Network type enumeration. * @zh - * 网络类型枚举 + * 网络类型枚举。 */ NetworkType, /** * @en - * LanguageCode type enumeration + * LanguageCode type enumeration. * @zh - * 语言码类型枚举 + * 语言码类型枚举。 */ Language, /** * @en - * OS type enumeration + * OS type enumeration. * @zh - * 操作系统类型枚举 + * 操作系统类型枚举。 */ OS, /** * @en - * Platform type enumeration + * Platform type enumeration. * @zh - * 平台类型枚举 + * 平台类型枚举。 */ Platform, /** * @en - * Browser type enumeration + * Browser type enumeration. * @zh - * 浏览器类型枚举 + * 浏览器类型枚举。 */ BrowserType, /** - * @en Whether the running platform is native app - * @zh 指示运行平台是否是原生平台 + * @en Whether the running platform is native app. + * @zh 指示运行平台是否是原生平台。 */ isNative: systemInfo.isNative, /** - * @en Whether the running platform is browser - * @zh 指示运行平台是否是浏览器 + * @en Whether the running platform is browser. + * @zh 指示运行平台是否是浏览器。 */ isBrowser: systemInfo.isBrowser, /** - * @en Indicate whether the current running context is a mobile system - * @zh 指示当前运行平台是否是移动端平台 + * @en Indicate whether the current running context is a mobile system. + * @zh 指示当前运行平台是否是移动端平台。 */ isMobile: systemInfo.isMobile, /** - * @en Whether the endianness of current platform is little endian - * @zh 当前平台字节顺序是否是小端序 + * @en Whether the endianness of current platform is little endian. + * @zh 当前平台字节顺序是否是小端序。 */ isLittleEndian: systemInfo.isLittleEndian, /** - * @en The running platform - * @zh 当前运行平台或环境 + * @en The running platform. + * @zh 当前运行平台或环境。 */ platform: systemInfo.platform, /** - * @en Indicate the current language of the running system - * @zh 指示当前运行环境的语言 + * @en Indicate the current language of the running system. + * @zh 指示当前运行环境的语言。 */ language: systemInfo.language, @@ -151,52 +152,52 @@ export const sys = { languageCode: systemInfo.nativeLanguage, /** - * @en Indicate the running os name - * @zh 指示当前运行系统 + * @en Indicate the running os name. + * @zh 指示当前运行系统。 */ os: systemInfo.os, /** - * @en Indicate the running os version string - * @zh 指示当前运行系统版本字符串 + * @en Indicate the running os version string. + * @zh 指示当前运行系统版本字符串。 */ osVersion: systemInfo.osVersion, /** - * @en Indicate the running os main version - * @zh 指示当前系统主版本 + * @en Indicate the running os main version. + * @zh 指示当前系统主版本。 */ osMainVersion: systemInfo.osMainVersion, /** - * @en Indicate the running browser type - * @zh 指示当前运行的浏览器类型 + * @en Indicate the running browser type. + * @zh 指示当前运行的浏览器类型。 */ browserType: systemInfo.browserType, /** - * @en Indicate the running browser version - * @zh 指示当前运行的浏览器版本 + * @en Indicate the running browser version. + * @zh 指示当前运行的浏览器版本。 */ browserVersion: systemInfo.browserVersion, /** - * @en Whether the running platform is xr app - * @zh 指示运行平台是否是XR平台 + * @en Whether the running platform is xr app. + * @zh 指示运行平台是否是XR平台。 */ isXR: systemInfo.isXR, /** - * @en Indicate the real pixel resolution of the whole game window - * @zh 指示游戏窗口的像素分辨率 + * @en Indicate the real pixel resolution of the whole game window. + * @zh 指示游戏窗口的像素分辨率。 * * @deprecated since v3.4.0, please use screen.windowSize instead. */ windowPixelResolution: screen.windowSize, /** - * @en The capabilities of the current platform - * @zh 当前平台的功能可用性 + * @en The capabilities of the current platform. + * @zh 当前平台的功能可用性。 * * @deprecated since v3.4.0, please use sys.hasFeature() instead. */ @@ -212,14 +213,15 @@ export const sys = { }, /** - * @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 + * @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: {} as Storage, /** * @en Get the network type of current device, return `sys.NetworkType.LAN` if failure. - * @zh 获取当前设备的网络类型, 如果网络类型无法获取,默认将返回 `sys.NetworkType.LAN` + * @zh 获取当前设备的网络类型, 如果网络类型无法获取,默认将返回 `sys.NetworkType.LAN`。 + * @return @zh 返回 LAN 或 WWAN。 @en LAN or WWAN. */ getNetworkType (): NetworkType { return systemInfo.networkType; @@ -227,7 +229,7 @@ export const sys = { /** * @en Get the battery level of current device, return 1.0 if failure. - * @zh 获取当前设备的电池电量,如果电量无法获取,默认将返回 1 + * @zh 获取当前设备的电池电量,如果电量无法获取,默认将返回 1。 * @return - 0.0 ~ 1.0 */ getBatteryLevel (): number { @@ -235,8 +237,8 @@ export const sys = { }, /** - * @en Forces the garbage collection, only available in native platforms - * @zh 强制进行 JS 内存垃圾回收,尽在原生平台有效 + * @en Forces the garbage collection, only available in native platforms. + * @zh 强制进行 JS 内存垃圾回收,尽在原生平台有效。 */ garbageCollect () { systemInfo.triggerGC(); @@ -247,8 +249,8 @@ export const sys = { * 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 + * 在 Web 平台,只要对象非空或非 Undefined 就会返回 true,在原生平台,我们会检查当前 JS 对象和其绑定的原生对象是否都有效。 + * @param obj @zh 校验的对象。@en The object to be checked. */ isObjectValid (obj: any): boolean { if (obj === null || obj === undefined) { @@ -259,8 +261,8 @@ export const sys = { }, /** - * @en Dump systemInfo informations - * @zh 在控制台打印当前的主要系统信息 + * @en Dump systemInfo informations. + * @zh 在控制台打印当前的主要系统信息。 */ dump () { let str = ''; @@ -282,8 +284,9 @@ export const sys = { }, /** - * @en Try to open a url in browser, may not work in some platforms - * @zh 尝试打开一个 web 页面,并非在所有平台都有效 + * @en Try to open a url in browser, may not work in some platforms. + * @zh 尝试打开一个 web 页面,并非在所有平台都有效。 + * @param url @zh 访问的链接。 @en Visited links. */ openURL (url) { systemInfo.openURL(url); @@ -327,15 +330,16 @@ export const sys = { }, /** - * @en Get the current time in milliseconds - * @zh 获取当前时间(毫秒为单位) + * @en Get the current time in milliseconds. + * @zh 获取当前时间(毫秒为单位)。 */ now () { return systemInfo.now(); }, /** - * Restart the JS VM, only available in native platforms + * @en Restart the JS VM, only available in native platforms. + * @zh 重启JS虚拟机,仅仅在原生平台有效。 * @private */ restartVM () { @@ -348,7 +352,8 @@ export const sys = { * If the screen is not notched, this method returns a Rect of the same size as visibleSize by default. * Currently supports Android, iOS and WeChat, ByteDance Mini Game platform. * @zh - * 返回基于游戏视图坐标系的手机屏幕安全区域(设计分辨率为单位),如果不是异形屏将默认返回一个和 visibleSize 一样大的 Rect。目前支持安卓、iOS 原生平台和微信、字节小游戏平台。 + * 返回基于游戏视图坐标系的手机屏幕安全区域(设计分辨率为单位),如果不是异形屏将默认返回一个和 visibleSize 一样大的 Rect。 + * 目前支持安卓、iOS 原生平台和微信、字节小游戏平台。 * @method getSafeAreaRect * @return {Rect} */ diff --git a/cocos/core/platform/visible-rect.ts b/cocos/core/platform/visible-rect.ts index 5bde6a915c..878651dc4b 100644 --- a/cocos/core/platform/visible-rect.ts +++ b/cocos/core/platform/visible-rect.ts @@ -28,67 +28,82 @@ import { Rect } from '../math'; import { legacyCC } from '../global-exports'; /** - * `visibleRect` is a singleton object which defines the actual visible rect of the current view + * @zh `visibleRect` is a singleton object which defines the actual visible rect of the current view. + * @en `visibleRect` 是一个定义当前视图的实际可见矩形的单例对象。 * @engineInternal */ export const visibleRect = { /** - * Top left coordinate of the screen related to the game scene. + * @zh 与游戏场景有关的屏幕左上方坐标。 + * @en Top left coordinate of the screen related to the game scene. */ topLeft: legacyCC.v2(0, 0), /** - * Top right coordinate of the screen related to the game scene. + * @zh 与游戏场景有关的屏幕右上方坐标。 + * @en Top right coordinate of the screen related to the game scene. */ topRight: legacyCC.v2(0, 0), /** - * Top center coordinate of the screen related to the game scene. + * @zh 与游戏场景有关的屏幕上方中心坐标。 + * @en Top center coordinate of the screen related to the game scene. */ top: legacyCC.v2(0, 0), /** - * Bottom left coordinate of the screen related to the game scene. + * @zh 与游戏场景有关的屏幕左下坐标。 + * @en Bottom left coordinate of the screen related to the game scene. */ bottomLeft: legacyCC.v2(0, 0), /** - * Bottom right coordinate of the screen related to the game scene. + * @zh 与游戏场景有关的屏幕右下坐标。 + * @en Bottom right coordinate of the screen related to the game scene. */ bottomRight: legacyCC.v2(0, 0), /** - * Bottom center coordinate of the screen related to the game scene. + * @zh 与游戏场景有关的屏幕下方中心坐标。 + * @en Bottom center coordinate of the screen related to the game scene. */ bottom: legacyCC.v2(0, 0), /** - * Center coordinate of the screen related to the game scene. + * @zh 与游戏场景有关的屏幕中心坐标。 + * @en Center coordinate of the screen related to the game scene. */ center: legacyCC.v2(0, 0), /** - * Left center coordinate of the screen related to the game scene. + * @zh 与游戏场景有关的屏幕左边中心坐标。 + * @en Left center coordinate of the screen related to the game scene. */ left: legacyCC.v2(0, 0), /** - * Right center coordinate of the screen related to the game scene. + * @zh 与游戏场景有关的屏幕右边中心坐标。 + * @en Right center coordinate of the screen related to the game scene. */ right: legacyCC.v2(0, 0), /** - * Width of the screen. + * @zh 屏幕宽度。 + * @en Width of the screen. */ width: 0, /** - * Height of the screen. + * @zh 屏幕高度。 + * @en Height of the screen. */ height: 0, /** - * initialize + * @zh 初始化函数。 + * @en Initialization function. + * @param visibleRect_ @zh 当前视图的实际可见区域。@en The actual visible area of the current view. + * @NOTE: @zh 必须是有效的区域。例如区域大小不能为负数。@en It must be a valid region. For example, the region size cannot be negative. */ init (visibleRect_: Rect) { const w = this.width = visibleRect_.width;