From fc4f02432744696ee2d18c2e32692c41f2feb627 Mon Sep 17 00:00:00 2001 From: timlyeee <43355299+timlyeee@users.noreply.github.com> Date: Thu, 21 Jul 2022 18:31:30 +0800 Subject: [PATCH] update documentations of reflection, bridge and jsbBridgeWrapper (#12097) --- @types/jsb.d.ts | 51 ------- cocos/native-binding/impl.ts | 126 +++++++++++++++++ cocos/native-binding/index.ts | 131 +++++++++++++++++- platforms/native/engine/index.js | 3 - platforms/native/engine/jsb-bridge-wrapper.js | 88 ------------ platforms/native/engine/jsb-bridge.js | 43 ------ platforms/native/engine/jsb-reflection.js | 45 ------ 7 files changed, 255 insertions(+), 232 deletions(-) delete mode 100644 platforms/native/engine/jsb-bridge-wrapper.js delete mode 100644 platforms/native/engine/jsb-bridge.js delete mode 100644 platforms/native/engine/jsb-reflection.js diff --git a/@types/jsb.d.ts b/@types/jsb.d.ts index 588f5e757c5..f8c0a5a4f53 100644 --- a/@types/jsb.d.ts +++ b/@types/jsb.d.ts @@ -148,57 +148,6 @@ declare namespace jsb { export function getOriginalPCMBuffer (url: string, channelID: number): ArrayBuffer | undefined; } - export namespace reflection{ - /** - * https://docs.cocos.com/creator/manual/zh/advanced-topics/java-reflection.html - * call OBJC/Java static methods - * - * @param className - * @param methodName - * @param methodSignature - * @param parameters - */ - export function callStaticMethod (className: string, methodName: string, methodSignature: string, ...parameters:any): any; - } - export namespace bridge{ - /** - * send to native with at least one argument. - */ - export function sendToNative(arg0: string, arg1?: string): void; - /** - * save your own callback controller with a js function, - * use jsb.bridge.onNative = (arg0: String, arg1: String)=>{...} - * @param args : received from native - */ - export function onNative(arg0: string, arg1?: string|null): void; - } - /** - * Listener for jsbBridgeWrapper's event. - * It takes one argument as string which is transferred by jsbBridge. - */ - export type OnNativeEventListener = (arg: string) => void; - export namespace jsbBridgeWrapper { - /** If there's no event registered, the wrapper will create one */ - export function addNativeEventListener(eventName: string, listener: OnNativeEventListener); - /** - * Dispatch the event registered on Objective-C, Java etc. - * No return value in JS to tell you if it works. - */ - export function dispatchEventToNative(eventName: string, arg?: string); - /** - * Remove all listeners relative. - */ - export function removeAllListenersForEvent(eventName: string); - /** - * Remove the listener specified - */ - export function removeNativeEventListener(eventName: string, listener: OnNativeEventListener); - /** - * Remove all events, use it carefully! - */ - export function removeAllListeners(); - } - export interface ManifestAsset { md5: string; path: string; diff --git a/cocos/native-binding/impl.ts b/cocos/native-binding/impl.ts index 8f143d55bce..b2ac5a301c9 100644 --- a/cocos/native-binding/impl.ts +++ b/cocos/native-binding/impl.ts @@ -1,4 +1,130 @@ +/* + Copyright (c) 2022 Xiamen Yaji Software Co., Ltd. + + https://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. + */ +import { sys } from "../core/platform/sys"; +import { NATIVE } from 'internal:constants'; const globalJsb = globalThis.jsb ?? {}; +if( NATIVE ){ + Object.defineProperty(globalJsb, 'reflection', { + get () { + if (globalJsb.__bridge !== undefined) return globalJsb.__bridge; + if (globalThis.JavascriptJavaBridge && (sys.os === sys.OS.ANDROID || sys.os === sys.OS.OHOS)) { + globalJsb.__bridge = new globalThis.JavascriptJavaBridge(); + } else if (globalThis.JavaScriptObjCBridge && (sys.os === sys.OS.IOS || sys.os === sys.OS.OSX)) { + globalJsb.__bridge = new globalThis.JavaScriptObjCBridge(); + } else { + globalJsb.__bridge = null; + } + return globalJsb.__bridge; + }, + enumerable: true, + configurable: true, + set (value) { + globalJsb.__bridge = value; + }, + }); + Object.defineProperty(globalJsb, 'bridge', { + get () { + if (globalJsb.__ccbridge !== undefined) return globalJsb.__ccbridge; + if (window.ScriptNativeBridge && sys.os === sys.OS.ANDROID || sys.os === sys.OS.IOS || sys.os === sys.OS.OSX || sys.os === sys.OS.OHOS) { + globalJsb.__ccbridge = new ScriptNativeBridge(); + } else { + globalJsb.__ccbridge = null; + } + return globalJsb.__ccbridge; + }, + enumerable: true, + configurable: true, + set (value) { + globalJsb.__ccbridge = value; + }, + }); + const JsbBridgeWrapper = { + eventMap: new Map(), + addNativeEventListener (eventName, listener) { + if (!this.eventMap.get(eventName)) { + this.eventMap.set(eventName, []); + } + const arr = this.eventMap.get(eventName); + if (!arr.find(listener)) { + arr.push(listener); + } + }, + dispatchEventToNative (eventName, arg) { + globalJsb.bridge.sendToNative(eventName, arg); + }, + removeAllListenersForEvent (eventName) { + return this.eventMap.delete(eventName); + }, + removeNativeEventListener (eventName, listener) { + const arr = this.eventMap.get(eventName); + if (!arr) { + return false; + } + for (let i = 0, l = arr.length; i < l; i++) { + if (arr[i] === listener) { + arr.splice(i, 1); + return true; + } + } + return true; + }, + removeAllListeners () { + this.eventMap.clear(); + }, + triggerEvent (eventName, arg) { + const arr = this.eventMap.get(eventName); + if (!arr) { + console.error(`${eventName} does not exist`); + return; + } + arr.map((listener) => listener.call(null, arg)); + }, + }; + + Object.defineProperty(globalJsb, 'jsbBridgeWrapper', { + get () { + if (globalJsb.__JsbBridgeWrapper !== undefined) return globalJsb.__JsbBridgeWrapper; + + if (window.ScriptNativeBridge && sys.os === sys.OS.ANDROID || sys.os === sys.OS.IOS || sys.os === sys.OS.OSX || sys.os === sys.OS.OHOS) { + globalJsb.__JsbBridgeWrapper = JsbBridgeWrapper; + globalJsb.bridge.onNative = (methodName, arg1) => { + console.log(`Trigger event: ${methodName} with argeter: ${arg1}`); + globalJsb.__JsbBridgeWrapper.triggerEvent(methodName, arg1); + }; + } else { + globalJsb.__JsbBridgeWrapper = null; + } + return globalJsb.__JsbBridgeWrapper; + }, + enumerable: true, + configurable: true, + set (value) { + globalJsb.__JsbBridgeWrapper = value; + }, + }); +} export const native = { DownloaderHints: globalJsb.DownloaderHints, diff --git a/cocos/native-binding/index.ts b/cocos/native-binding/index.ts index b9f5c76f43b..5a19c2764eb 100644 --- a/cocos/native-binding/index.ts +++ b/cocos/native-binding/index.ts @@ -853,7 +853,7 @@ export declare namespace native { * @en DebugRenderer class used to output debug text on screen * @zh 用于输出屏幕调试文字的调试渲染器类 */ - export class DebugRenderer { + export class DebugRenderer { /** * @en get DebugRenderer instance * @zh 获取调试渲染器实例 @@ -869,5 +869,132 @@ export declare namespace native { * @param info @en the output text information @zh 输出的文本属性 */ addText(text:string, screenPos: Vec2, info?: DebugTextInfo): void; - } + } + + export namespace reflection { + /** + * https://docs.cocos.com/creator/manual/zh/advanced-topics/java-reflection.html + * @en call Objective-C/Java static methods + * @zh 调用 Objective-C/Java 静态方法 + * + * @param className : @en the class name of the Objective-C/Java class @zh Objective-C/Java 类的类名 + * @param methodName : @en the method name of the Objective-C/Java class @zh Objective-C/Java 类的方法名 + * @param methodSignature : @en the method signature of the Objective-C/Java class @zh Objective-C/Java 方法签名 + * @param parameters : @en the parameters of the Objective-C/Java class to translate @zh 传递至该 Objective-C/Java 方法的参数 + */ + export function callStaticMethod (methodName: string, methodSignature: string, ...parameters:any): any; + } + + /** + * @en + * The API to listen and dispatch events on Objc/JAVA without reflection, + * Function onNative can only be overriden once by time. + * https://docs.cocos.com/creator/manual/en/advanced-topics/js-java-bridge.html + * Sample: + * ``` + * native.bridge.onNative = (event, data) => { + * if (event === 'send_message') { + * console.log(data); + * } + * } + * ``` + * ``` + * // Java codes + * JsbBridge.sendToScript('send_message', 'hello world'); + * ``` + * @zh + * 不使用反射机制来调用和监听Objc/JAVA事件的接口, + * 同一时间只能重载一个onNative函数 + * https://docs.cocos.com/creator/manual/zh/advanced-topics/js-java-bridge.html + * 示例: + * ``` + * native.bridge.onNative = (event, data) => { + * if (event === 'send_message') { + * console.log(data); + * } + * } + * ``` + * ```java + * JsbBridge.sendToScript('send_message', 'hello world'); + * ``` + */ + export namespace bridge { + /** + * @en send to native with maxmimum of 2 parameters + * @zh 向原生发送消息，可接受1到2个参数。 + * @param arg0 : @en the first parameter @zh 第一个参数 + * @param arg1 : @en the second parameter @zh 第二个参数 + */ + export function sendToNative(arg0: string, arg1?: string): void; + /** + * @en + * Define your own js callback function. When native scripts run sendToScript, this callback will be called. + * usage: jsb.bridge.onNative = (arg0: String, arg1: String) => {...} + * @zh + * 定义自己的js回调函数，当原生调用 sendToScript 时，该回调函数被触发。 + * 使用 jsb.bridge.onNative = (arg0: String, arg1: String) => {...} + * + * @param arg0 : @en the first parameter @zh 第一个参数 + * @param arg1 : @en the second parameter @zh 第二个参数 + */ + export function onNative(arg0: string, arg1?: string|null): void; + } + /** + * @en + * Listener for jsbBridgeWrapper's event. + * It takes one argument as data which is transferred by jsbBridge. + * @zh + * jsbBridgeWrapper 的事件监听器， + * 它接受一个字符串参数，这个参数是通过 jsbBridge 进行传递的数据 + * @param arg: @en the data transferred by jsbBridge @zh jsbBridge 进行传递的数据 + */ + export type OnNativeEventListener = (arg: string) => void; + /** + * @en + * A high level API to call Objc/JAVA methods. + * Use bridge to implement it. If use jsbBridgeWrapper, bridge should not be used. + * https://docs.cocos.com/creator/manual/en/advanced-topics/jsb-bridge-wrapper.html + * @zh + * 高级 API，用于调用 Objc/JAVA 方法。 + * 该方法封装在bridge之上，如果使用 jsbBridgeWrapper，bridge 不应该被使用。 + * https://docs.cocos.com/creator/manual/zh/advanced-topics/jsb-bridge-wrapper.html + */ + export namespace jsbBridgeWrapper { + /** + * @en + * Register one listener to the event + * @zh + * 给事件注册一个监听 + * @param event : @en the event name @zh 事件名称 + * @param listener : @en the listener @zh 监听器 + */ + export function addNativeEventListener(event: string, listener: OnNativeEventListener); + /** + * @en + * Dispatch the event registered on Objective-C, Java etc. + * @zh + * 调用 Objective-C、Java 等的注册的事件。 + * @param event : @en the event name @zh 事件名称 + * @param data : @en the data @zh 数据 + */ + export function dispatchEventToNative(event: string, arg?: string); + /** + * @en Remove all listeners listennig to event. + * @zh 移除指定事件的所有监听。 + * @param event : @en the event name @zh 事件名称 + */ + export function removeAllListenersForEvent(event: string); + /** + * @en Remove the listener specified. + * @zh 移除指定的事件监听器 + * @param event : @en the event name @zh 事件名称 + */ + export function removeNativeEventListener(event: string, listener: OnNativeEventListener); + /** + * @en Remove all events, use it carefully! + * @zh 移除所有事件，请小心使用！ + * @param event : @en the event name @zh 事件名称 + */ + export function removeAllListeners(); + } } diff --git a/platforms/native/engine/index.js b/platforms/native/engine/index.js index 7af523b66b4..19871391214 100644 --- a/platforms/native/engine/index.js +++ b/platforms/native/engine/index.js @@ -22,9 +22,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ****************************************************************************/ -require('./jsb-reflection.js'); -require('./jsb-bridge.js'); -require('./jsb-bridge-wrapper.js'); require('./jsb-assets-manager.js'); require('./jsb-game.js'); diff --git a/platforms/native/engine/jsb-bridge-wrapper.js b/platforms/native/engine/jsb-bridge-wrapper.js deleted file mode 100644 index 6a71e32f5c4..00000000000 --- a/platforms/native/engine/jsb-bridge-wrapper.js +++ /dev/null @@ -1,88 +0,0 @@ -/**************************************************************************** - Copyright (c) 2021 Xiamen Yaji Software Co., Ltd. - - https://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. - ****************************************************************************/ -const JsbBridgeWrapper = { - eventMap: new Map(), - addNativeEventListener (eventName, listener) { - if (!this.eventMap.get(eventName)) { - this.eventMap.set(eventName, []); - } - const arr = this.eventMap.get(eventName); - if (!arr.find(listener)) { - arr.push(listener); - } - }, - dispatchEventToNative (eventName, arg) { - jsb.bridge.sendToNative(eventName, arg); - }, - removeAllListenersForEvent (eventName) { - return this.eventMap.delete(eventName); - }, - removeNativeEventListener (eventName, listener) { - const arr = this.eventMap.get(eventName); - if (!arr) { - return false; - } - for (let i = 0, l = arr.length; i < l; i++) { - if (arr[i] === listener) { - arr.splice(i, 1); - return true; - } - } - return true; - }, - removeAllListeners () { - this.eventMap.clear(); - }, - triggerEvent (eventName, arg) { - const arr = this.eventMap.get(eventName); - if (!arr) { - console.error(`${eventName} does not exist`); - return; - } - arr.map((listener) => listener.call(null, arg)); - }, -}; - -Object.defineProperty(jsb, 'jsbBridgeWrapper', { - get () { - if (jsb.__JsbBridgeWrapper !== undefined) return jsb.__JsbBridgeWrapper; - - if (window.ScriptNativeBridge && cc.sys.os === cc.sys.OS.ANDROID || cc.sys.os === cc.sys.OS.IOS || cc.sys.os === cc.sys.OS.OSX || cc.sys.os === cc.sys.OS.OHOS) { - jsb.__JsbBridgeWrapper = JsbBridgeWrapper; - jsb.bridge.onNative = (methodName, arg1) => { - console.log(`Trigger event: ${methodName} with argeter: ${arg1}`); - jsb.__JsbBridgeWrapper.triggerEvent(methodName, arg1); - }; - } else { - jsb.__JsbBridgeWrapper = null; - } - return jsb.__JsbBridgeWrapper; - }, - enumerable: true, - configurable: true, - set (value) { - jsb.__JsbBridgeWrapper = value; - }, -}); diff --git a/platforms/native/engine/jsb-bridge.js b/platforms/native/engine/jsb-bridge.js deleted file mode 100644 index 2f9643ad52e..00000000000 --- a/platforms/native/engine/jsb-bridge.js +++ /dev/null @@ -1,43 +0,0 @@ -/**************************************************************************** - Copyright (c) 2018 Xiamen Yaji Software Co., Ltd. - - https://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. - ****************************************************************************/ - -// JS to Native bridges -// set to lazy -Object.defineProperty(jsb, 'bridge', { - get () { - if (jsb.__ccbridge !== undefined) return jsb.__ccbridge; - if (window.ScriptNativeBridge && cc.sys.os === cc.sys.OS.ANDROID || cc.sys.os === cc.sys.OS.IOS || cc.sys.os === cc.sys.OS.OSX || cc.sys.os === cc.sys.OS.OHOS) { - jsb.__ccbridge = new ScriptNativeBridge(); - } else { - jsb.__ccbridge = null; - } - return jsb.__ccbridge; - }, - enumerable: true, - configurable: true, - set (value) { - jsb.__ccbridge = value; - }, -}); diff --git a/platforms/native/engine/jsb-reflection.js b/platforms/native/engine/jsb-reflection.js deleted file mode 100644 index c68a3940cd8..00000000000 --- a/platforms/native/engine/jsb-reflection.js +++ /dev/null @@ -1,45 +0,0 @@ -/**************************************************************************** - Copyright (c) 2018 Xiamen Yaji Software Co., Ltd. - - https://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. - ****************************************************************************/ - -// JS to Native bridges -// set to lazy -Object.defineProperty(jsb, 'reflection', { - get () { - if (jsb.__bridge !== undefined) return jsb.__bridge; - if (window.JavascriptJavaBridge && (cc.sys.os === cc.sys.OS.ANDROID || cc.sys.os === cc.sys.OS.OHOS)) { - jsb.__bridge = new JavascriptJavaBridge(); - } else if (window.JavaScriptObjCBridge && (cc.sys.os === cc.sys.OS.IOS || cc.sys.os === cc.sys.OS.OSX)) { - jsb.__bridge = new JavaScriptObjCBridge(); - } else { - jsb.__bridge = null; - } - return jsb.__bridge; - }, - enumerable: true, - configurable: true, - set (value) { - jsb.__bridge = value; - }, -});