Skip to content

Commit

Permalink
update documentations of reflection, bridge and jsbBridgeWrapper (#12097
Browse files Browse the repository at this point in the history 
)
  • Loading branch information
@timlyeee
timlyeee committed Jul 21, 2022
1 parent d09963b commit fc4f024
Show file tree
Hide file tree
Showing 7 changed files with 255 additions and 232 deletions.
51 changes: 0 additions & 51 deletions @types/jsb.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
126 changes: 126 additions & 0 deletions cocos/native-binding/impl.ts
View file
Original file line number Diff line number Diff line change
@@ -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,
Expand Down
131 changes: 129 additions & 2 deletions cocos/native-binding/index.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 获取调试渲染器实例
Expand All @@ -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();
}
}
3 changes: 0 additions & 3 deletions platforms/native/engine/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand Down
Loading

0 comments on commit fc4f024

Please sign in to comment.