diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000000000000000000000000000000000000..7bbfcd224ec61e58723728555621bf7370ec39ea --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,8 @@ +# Changelog +## [v1.0.0] 2023-10 + +基于[mockHTTP](https://github.com/ChrisSkeldon/mockHTTP) 原库0.0.1版本进行适配，使其可以运行在 OpenHarmony，并沿用其现有用法和特性。已支持： +- 建立js与artkTS互相调用的机制 +- 允许通过 `jsbridge.call("func",xxx)` 从js调用arkts方法及 `jsbridge.post("func",xxx)` ,从arkts调用js方法 +- 支持在js侧动态添加删除被调用函数 +- 支持通过js函数或脚本的形式调用arkts方法 \ No newline at end of file diff --git a/Readme.md b/Readme.md index 9fa85409ed59f1dfe4b3fe65fc39e20f6132058c..d3f1880e314540233b11ff683b506a25c308c57e 100644 --- a/Readme.md +++ b/Readme.md @@ -1,4 +1,4 @@ -# ohos_jsbridge +# jsbridge ## 简介 @@ -10,6 +10,24 @@ JSBridge 是在 OpenHarmony API 10 Beta2 上开发的三方库，提供了 bridg ohpm install @ncc/jsbridge ``` +//![](./screenshots/axios.gif) + +OpenHarmony ohpm 环境配置等更多内容，请参考[如何安装 OpenHarmony ohpm 包](https://gitee.com/openharmony-tpc/docs/blob/master/OpenHarmony_har_usage.md) + +## 接口列表 + + +| **接口** | 参数 | 功能 | +|-------------------------------------|--------------------------------------------------|--------------------------------------| +| attachController(controller) | controller：需要关联的 `web_webview.WebviewController` | 关联一个 `web_webview.WebviewController` | +| initBridge(jsbridgeName) | jsbridgeName：Web 侧调用时使用JSBridge名 | 初始化JSBridge | +| removeBridge() | | 取消注册JSBridge | +| setNotFoundHandler(notFoundHandler) | notFoundHandler：回调函数对象 | 设置 jsbridge.call 找不到目标函数时的回调函数 | +| register(methods) | methods：支持的函数对象 | 添加支持的函数 | +| unregister(methods) | methods：支持的函数对象 | 移除支持的函数 | +| postJS(jsCommand, callback) | jsCommand：JS脚本
callback：返回执行结果 | 异步执行 JS 脚本 | +| post(funcName, ...params) | funcName：JS函数名 | 异步调用 JS 函数 | + ## 使用说明 ### 引用库 @@ -36,7 +54,7 @@ let jsbridge = new JSBridge(webviewController); 初始化需要在 webviewController 与 Web 组件关联后。初始化会向 WebviewController 注册一个 Bridge Object，用于 Web 端调用本地 ArkTS 函数。 -示例： +示例如下： ```extendtypescript try { @@ -103,7 +121,7 @@ jsbridge.register({'getName1': stu.getName1.bind(stu)}); jsbridge.register({'getName2': stu.getName2}); ``` -移除函数可以使用 unregister 接口。 +移除函数可以使用 unregister 接口： ```extendtypescript // 支持传入方法名列表 @@ -118,7 +136,7 @@ jsbridge.unregister('getName1'); 默认情况下，该 handler 会在控制台打印一条: "xxx is not found!"。 -我们可以通过下面的接口配置它： +可以通过下面的接口进行配置： ```extendtypescript jsbridge.setNotFoundHandler( @@ -140,3 +158,32 @@ jsbridge.postJS("jsFunctionA('param1', 1, 2);"); // 使用此接口传入的参数，都会被自动序列化后拼接起来 jsbridge.post('jsFunctionA', string1, number1, number2); ``` + +## 约束与限制 + +在下述版本验证通过： +DevEco Studio: 4.0 Beta2(4.0.0.400), SDK: API10(4.0.9.6) + +## 目录结构 + +```text +|---- ohos_jsbridge +| |---- AppScrope # 示例代码文件夹 +| |---- entry # 示例代码文件夹 +| |---- screenshots # 截图 +| |---- jsbridge # jsbridge库文件夹 +| |---- build # jsbridge模块打包后的文件 +| |---- src # 模块代码 +| |---- main +| |---- ets/components # jsbridge核心代码 +| |---- index.js # 入口文件 +| |---- index.d.ts # 声明文件 +| |---- *.json5 # 配置文件 +| |---- README.md # 安装使用方法 +| |---- README.OpenSource # 开源说明 +| |---- CHANGELOG.md # 更新日志 +``` + +## 开源协议 + +本项目基于 [Apache-2.0](./LICENSE) ，请自由地享受和参与开源。 \ No newline at end of file diff --git a/TEST.md b/TEST.md new file mode 100644 index 0000000000000000000000000000000000000000..ec240006f6c5f0beeb18802960261c2b3f383c1f --- /dev/null +++ b/TEST.md @@ -0,0 +1,11 @@ +# 测试情况 + +测试用例基于 OpenHarmony 系统下。 + +## 覆盖情况 + +| 测试用例名 | 是否通过 | +|-------------------|------| +| callExistMethod | 是 | +| notFoundHandler | 是 | +| unregisterMethod | 是 | \ No newline at end of file diff --git a/entry/src/main/ets/entryability/EntryAbility.ts b/entry/src/main/ets/entryability/EntryAbility.ts index 7af23678e43bb102a056c06178b4a0d274a6cdf5..4f521b27d39752c3b203c7800fa19977b52158db 100644 --- a/entry/src/main/ets/entryability/EntryAbility.ts +++ b/entry/src/main/ets/entryability/EntryAbility.ts @@ -1,3 +1,20 @@ +/* + * Apache License, Version 2.0 (Apache-2.0) + * Copyright 2023 Huawei Device Co., Ltd. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + import AbilityConstant from '@ohos.app.ability.AbilityConstant'; import hilog from '@ohos.hilog'; import UIAbility from '@ohos.app.ability.UIAbility'; diff --git a/entry/src/main/ets/pages/Index.ets b/entry/src/main/ets/pages/Index.ets index 636c314bd256ce36dc2a3d1d21a9b99aa29a1404..d2856eeaa6b41a1483a0823ab819fae6de1d1e36 100644 --- a/entry/src/main/ets/pages/Index.ets +++ b/entry/src/main/ets/pages/Index.ets @@ -1,3 +1,19 @@ +/* + * Apache License, Version 2.0 (Apache-2.0) + * Copyright 2023 Huawei Device Co., Ltd. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ import web_webview from '@ohos.web.webview' import JSBridge from '@ncc/jsbridge' diff --git a/entry/src/ohosTest/ets/test/Ability.test.ets b/entry/src/ohosTest/ets/test/Ability.test.ets index 8abf7f2f44c0e56110df8c09b2524a4ca37bc993..4c83e0a3a2db301253eab36ff18ffb79189594d8 100644 --- a/entry/src/ohosTest/ets/test/Ability.test.ets +++ b/entry/src/ohosTest/ets/test/Ability.test.ets @@ -1,3 +1,19 @@ +/* + * Apache License, Version 2.0 (Apache-2.0) + * Copyright 2023 Huawei Device Co., Ltd. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ import hilog from '@ohos.hilog'; import { describe, beforeAll, beforeEach, afterEach, afterAll, it, expect } from '@ohos/hypium' diff --git a/entry/src/ohosTest/ets/test/JSBridgeBasic.test.ets b/entry/src/ohosTest/ets/test/JSBridgeBasic.test.ets index aa37db3c77f26b4a4f15bddda57de749509b9cc0..8158ff0ccb6fa1421a372ac84f0d4303beaefb27 100644 --- a/entry/src/ohosTest/ets/test/JSBridgeBasic.test.ets +++ b/entry/src/ohosTest/ets/test/JSBridgeBasic.test.ets @@ -1,11 +1,47 @@ +/* + * Apache License, Version 2.0 (Apache-2.0) + * Copyright 2023 Huawei Device Co., Ltd. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ import JSBridge from '@ncc/jsbridge' import { describe, beforeAll, beforeEach, afterEach, afterAll, it, expect } from '@ohos/hypium' export default function jsbridgeBasicTest() { describe('jsbridgeBasicTest', function () { - it('methodsModify', 0, function () { + it('callExistMethod', 0, function () { let jsbridge = new JSBridge(); - let jsbridgeObj = jsbridge.jsbridgeObj; + const jsbridgeObj = jsbridge.jsbridgeObj; + jsbridge.register({ + 'funcA': () => { return 1; }, + 'funcB': (a: number, b: number) => { return 2 + a + b; } + }); + expect(jsbridgeObj.call('funcA')).assertEqual(1); + expect(jsbridgeObj.call('funcB', 3, 4)).assertEqual(2 + 3 + 4); + }) + + it('notFoundHandler', 0, function() { + let jsbridge = new JSBridge(); + const jsbridgeObj = jsbridge.jsbridgeObj; + jsbridge.setNotFoundHandler((name: string) => { + return name + ' not found!'; + }); + expect(jsbridgeObj.call('funcA')).assertEqual('funcA not found!'); + }) + + it('unregisterMethod', 0, function() { + let jsbridge = new JSBridge(); + const jsbridgeObj = jsbridge.jsbridgeObj; jsbridge.register({ 'funcA': () => { return 1; }, 'funcB': (a: number, b: number) => { return 2 + a + b; } @@ -13,7 +49,9 @@ export default function jsbridgeBasicTest() { jsbridge.setNotFoundHandler((name: string) => { return name + ' not found!'; }); - jsbridge.unregister('funcA'); + expect(jsbridgeObj.call('funcA')).assertEqual(1); + expect(jsbridgeObj.call('funcB', 3, 4)).assertEqual(2 + 3 + 4); + jsbridge.unregister('funcA') expect(jsbridgeObj.call('funcA')).assertEqual('funcA not found!'); expect(jsbridgeObj.call('funcB', 3, 4)).assertEqual(2 + 3 + 4); }) diff --git a/entry/src/ohosTest/ets/test/List.test.ets b/entry/src/ohosTest/ets/test/List.test.ets index 7406f5b291bebc8cb24096d4997caf0e037110a0..c0ca279e6b6e5957464fded449c54bd327453038 100644 --- a/entry/src/ohosTest/ets/test/List.test.ets +++ b/entry/src/ohosTest/ets/test/List.test.ets @@ -1,3 +1,19 @@ +/* + * Apache License, Version 2.0 (Apache-2.0) + * Copyright 2023 Huawei Device Co., Ltd. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ import jsbridgeBasicTest from './JSBridgeBasic.test' import abilityTest from './Ability.test' diff --git a/entry/src/ohosTest/ets/testability/TestAbility.ets b/entry/src/ohosTest/ets/testability/TestAbility.ets index 4af32a834ce057f50e30d5a85472db2eb3e9871c..2e46c96d3b1bcf9a8804b679e359a246c53fbcfc 100644 --- a/entry/src/ohosTest/ets/testability/TestAbility.ets +++ b/entry/src/ohosTest/ets/testability/TestAbility.ets @@ -1,3 +1,19 @@ +/* + * Apache License, Version 2.0 (Apache-2.0) + * Copyright 2023 Huawei Device Co., Ltd. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ import UIAbility from '@ohos.app.ability.UIAbility'; import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; import hilog from '@ohos.hilog'; diff --git a/entry/src/ohosTest/ets/testability/pages/Index.ets b/entry/src/ohosTest/ets/testability/pages/Index.ets index 166366593a7e55ef17e6619f68a4c46214814858..bbc9fc6fa5ff67bb6dce09bafb0caa88251e6603 100644 --- a/entry/src/ohosTest/ets/testability/pages/Index.ets +++ b/entry/src/ohosTest/ets/testability/pages/Index.ets @@ -1,3 +1,19 @@ +/* + * Apache License, Version 2.0 (Apache-2.0) + * Copyright 2023 Huawei Device Co., Ltd. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ import hilog from '@ohos.hilog'; @Entry diff --git a/entry/src/ohosTest/ets/testrunner/OpenHarmonyTestRunner.ts b/entry/src/ohosTest/ets/testrunner/OpenHarmonyTestRunner.ts index 2d6786fe80269615a071e30b0c40743726292ee6..565ec0de8cc12cf0cb3cb8db2c3609fcf84db65d 100644 --- a/entry/src/ohosTest/ets/testrunner/OpenHarmonyTestRunner.ts +++ b/entry/src/ohosTest/ets/testrunner/OpenHarmonyTestRunner.ts @@ -1,3 +1,19 @@ +/* + * Apache License, Version 2.0 (Apache-2.0) + * Copyright 2023 Huawei Device Co., Ltd. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ import hilog from '@ohos.hilog'; import TestRunner from '@ohos.application.testRunner'; import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; diff --git a/jsbridge/CHANGELOG.md b/jsbridge/CHANGELOG.md new file mode 100644 index 0000000000000000000000000000000000000000..7bbfcd224ec61e58723728555621bf7370ec39ea --- /dev/null +++ b/jsbridge/CHANGELOG.md @@ -0,0 +1,8 @@ +# Changelog +## [v1.0.0] 2023-10 + +基于[mockHTTP](https://github.com/ChrisSkeldon/mockHTTP) 原库0.0.1版本进行适配，使其可以运行在 OpenHarmony，并沿用其现有用法和特性。已支持： +- 建立js与artkTS互相调用的机制 +- 允许通过 `jsbridge.call("func",xxx)` 从js调用arkts方法及 `jsbridge.post("func",xxx)` ,从arkts调用js方法 +- 支持在js侧动态添加删除被调用函数 +- 支持通过js函数或脚本的形式调用arkts方法 \ No newline at end of file diff --git a/jsbridge/LICENSE b/jsbridge/LICENSE new file mode 100644 index 0000000000000000000000000000000000000000..261eeb9e9f8b2b4b0d119366dda99c6fd7d35c64 --- /dev/null +++ b/jsbridge/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/jsbridge/Readme.md b/jsbridge/Readme.md new file mode 100644 index 0000000000000000000000000000000000000000..d3f1880e314540233b11ff683b506a25c308c57e --- /dev/null +++ b/jsbridge/Readme.md @@ -0,0 +1,189 @@ +# jsbridge + +## 简介 + +JSBridge 是在 OpenHarmony API 10 Beta2 上开发的三方库，提供了 bridge 形式的 ArkTS 和 JavaScript 相互调用接口。 + +## 下载安装 + +```bash +ohpm install @ncc/jsbridge +``` + +//![](./screenshots/axios.gif) + +OpenHarmony ohpm 环境配置等更多内容，请参考[如何安装 OpenHarmony ohpm 包](https://gitee.com/openharmony-tpc/docs/blob/master/OpenHarmony_har_usage.md) + +## 接口列表 + + +| **接口** | 参数 | 功能 | +|-------------------------------------|--------------------------------------------------|--------------------------------------| +| attachController(controller) | controller：需要关联的 `web_webview.WebviewController` | 关联一个 `web_webview.WebviewController` | +| initBridge(jsbridgeName) | jsbridgeName：Web 侧调用时使用JSBridge名 | 初始化JSBridge | +| removeBridge() | | 取消注册JSBridge | +| setNotFoundHandler(notFoundHandler) | notFoundHandler：回调函数对象 | 设置 jsbridge.call 找不到目标函数时的回调函数 | +| register(methods) | methods：支持的函数对象 | 添加支持的函数 | +| unregister(methods) | methods：支持的函数对象 | 移除支持的函数 | +| postJS(jsCommand, callback) | jsCommand：JS脚本
callback：返回执行结果 | 异步执行 JS 脚本 | +| post(funcName, ...params) | funcName：JS函数名 | 异步调用 JS 函数 | + +## 使用说明 + +### 引用库 + +```extendtypescript +import JSBridge from '@ncc/jsbridge' +``` + +### 实例创建与关联 + +创建的实例需要与一个 `web_webview.WebviewController` 关联。 + +示例： + +```extendtypescript +// 方式一：创建后关联 +let jsbridge = new JSBridge(); +jsbridge.attachController(webviewController); +// 方式二：创建时关联 +let jsbridge = new JSBridge(webviewController); +``` + +### Bridge初始化/移除 + +初始化需要在 webviewController 与 Web 组件关联后。初始化会向 WebviewController 注册一个 Bridge Object，用于 Web 端调用本地 ArkTS 函数。 + +示例如下： + +```extendtypescript +try { + // 传入参数为 Web 侧的 Bridge Object 名 + // 下面的示例中，初始化后，Web 侧可以使用下面的方式进行调用 + // jsbridgeName.call(xxx, ...) + jsbridge.initBridge('jsbridgeName'); +} catch (error) { + // 如果在 controller 未与 Web 组件关联时调用会抛出错误 + console.log(error.message); +} +``` + +想要取消这一注册，可以使用下面的接口： + +```extendtypescript +try { + jsbridge.removeBridge(); +} catch (error) { + console.log(error.message); +} +``` + +### 添加/移除可调用的应用侧函数 + +可以使用 register 函数向 jsbridge 添加支持的函数。该函数可以多次调用。 + +函数同名时，后注册的会覆盖先注册的。示例如下： + +```extendtypescript +// 下面的注册完成后，我们可以在 Web 侧使用 js 调用这两个方法： +// jsbridgeName.call('functionA', 'this is a string', 1) +// jsbridgeName.call('funcB') +jsbridge.register({ + 'functionA': functionA, + 'funcB': functionB, +}); + +// 方法可以有任意的参数数量 +// 但是传入参数和返回值仅支持 string/number/boolean +// 对 Object 类型的传入/返回需求可以尝试用 JSON 序列化解决 +function functionA(param1: string, param2: number) { + // do something +} +function functionB() { + // do something +} +``` + +如果注册的是成员函数等需要上下文的函数，会存在上下文(this)丢失的风险。在定义时使用箭头函数或手动绑定实体是一种不错的解决方案： + +```extendtypescript +class Student { + name: string = "Alice"; + getName1() { + return this.name; + } + getName2 = () => { + return this.name; + } +} +let stu = new Student; +jsbridge.register({'getName1': stu.getName1.bind(stu)}); +jsbridge.register({'getName2': stu.getName2}); +``` + +移除函数可以使用 unregister 接口： + +```extendtypescript +// 支持传入方法名列表 +jsbridge.unregister(['getName1', 'getName2']) +// 也支持只传入一个方法名 +jsbridge.unregister('getName1'); +``` + +### (可选)配置回调函数 + +在 Web 侧使用 jsbridge.call 时，如果调用的函数不被支持，call 会代替的以 notFoundHandler 作为回调函数。 + +默认情况下，该 handler 会在控制台打印一条: "xxx is not found!"。 + +可以通过下面的接口进行配置： + +```extendtypescript +jsbridge.setNotFoundHandler( + // 传入的函数必须接收一个 string 参数 + // 且返回值类型必须是 void | string | number | boolean + (funcName: string) => {return funcName + ' is not found!';} +); +``` + +### 应用侧调用JS + +JSBridge 还基于 WebviewController 的 runJavaScript 接口封装了 post 函数，用于应用侧调用 Web 侧函数。 + +```extendtypescript +// 支持直接传入 JS 代码 +jsbridge.postJS("jsFunctionA('param1', 1, 2);"); + +// 也支持 post('xxx', xxx) 的调用形式 +// 使用此接口传入的参数，都会被自动序列化后拼接起来 +jsbridge.post('jsFunctionA', string1, number1, number2); +``` + +## 约束与限制 + +在下述版本验证通过： +DevEco Studio: 4.0 Beta2(4.0.0.400), SDK: API10(4.0.9.6) + +## 目录结构 + +```text +|---- ohos_jsbridge +| |---- AppScrope # 示例代码文件夹 +| |---- entry # 示例代码文件夹 +| |---- screenshots # 截图 +| |---- jsbridge # jsbridge库文件夹 +| |---- build # jsbridge模块打包后的文件 +| |---- src # 模块代码 +| |---- main +| |---- ets/components # jsbridge核心代码 +| |---- index.js # 入口文件 +| |---- index.d.ts # 声明文件 +| |---- *.json5 # 配置文件 +| |---- README.md # 安装使用方法 +| |---- README.OpenSource # 开源说明 +| |---- CHANGELOG.md # 更新日志 +``` + +## 开源协议 + +本项目基于 [Apache-2.0](./LICENSE) ，请自由地享受和参与开源。 \ No newline at end of file diff --git a/jsbridge/oh-package.json5 b/jsbridge/oh-package.json5 index 421783b372836019bfec321bd04ac393e4cec531..a725212e429ea9224f59cdef44f304f118a8b37d 100644 --- a/jsbridge/oh-package.json5 +++ b/jsbridge/oh-package.json5 @@ -1,11 +1,16 @@ { - "name": "jsbridge", + "license": "Apache-2.0", "types": "index.d.ts", - "keywords": ["OpenHarmony", "jsbridge", "web"], - "version": "1.0.0", + "devDependencies": {}, + "keywords": [ + "OpenHarmony", + "jsbridge", + "web" + ], + "author": "qing-lkyi leezhenxiang", + "name": "jsbridge", "description": "通过 jsbridge，实现便捷的 ArkTS 和 js 间相互调用。", "main": "Index.ts", - "author": "qing-lkyi leezhenxiang", - "license": "Apache-2.0", + "version": "1.0.0", "dependencies": {} } diff --git a/jsbridge/src/main/ets/components/jsbridge.ts b/jsbridge/src/main/ets/components/jsbridge.ts index 5e300dce6f819cef73a75e5da13c70b0c4c6bd92..64d67d4747565e05f514fc1e7bccea3c2805d420 100644 --- a/jsbridge/src/main/ets/components/jsbridge.ts +++ b/jsbridge/src/main/ets/components/jsbridge.ts @@ -1,3 +1,19 @@ +/* + * Apache License, Version 2.0 (Apache-2.0) + * Copyright 2023 Huawei Device Co., Ltd. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ import webview from '@ohos.web.webview'; import { AsyncCallback } from '@ohos.base'; import hilog from '@ohos.hilog'; diff --git a/oh-package.json5 b/oh-package.json5 index 78491cab6de0ee55792ec6d51cdea3a645a51ea5..596db645aed27cc0008e6e895d3e6211ec29d5f1 100644 --- a/oh-package.json5 +++ b/oh-package.json5 @@ -1,13 +1,12 @@ { - "name": "ohos_jsbridge", - "version": "1.0.0", - "description": "Please describe the basic information.", - "main": "", - "author": "", "license": "", - "dependencies": { - }, "devDependencies": { "@ohos/hypium": "1.0.6" - } + }, + "author": "", + "name": "jsbridge", + "description": "Please describe the basic information.", + "main": "", + "version": "1.0.0", + "dependencies": {} }