Improve api doc (#13882)

This commit is contained in:
qiuguohua
2022-12-26 09:54:33 +08:00
committed by GitHub
parent 4b108dba16
commit f1e82d94c8
4 changed files with 126 additions and 95 deletions
+22 -14
View File
@@ -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 中。<br/>
* - 在 Cocos Creator 中,警告信息显示是黄色的。<br/>
* - 在 Chrome 中,警告信息有着黄色的图标以及黄色的消息文本。<br/>
* @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 中。<br/>
* - 在 Cocos Creator 中,错误信息显示是红色的。<br/>
* - 在 Chrome 中,错误信息有红色的图标以及红色的消息文本。<br/>
* @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) {
+15 -12
View File
@@ -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<void>` 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<void>;
@@ -163,7 +166,7 @@ class Screen {
/**
* @en Exit the full mode.
* @zh 退出全屏模式
* @zh 退出全屏模式。
* @return {Promise}
*/
public exitFullScreen (): Promise<any> {
@@ -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.
*/
+61 -56
View File
@@ -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}
*/
+28 -13
View File
@@ -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;