HarmonyOS Next: A Comprehensive Guide to Frontend Page Calls to ArkTS Functions
JavaScriptProxy: The Bridge Between Frontend and ArkTS Interaction
(I) Functional Overview
JavaScriptProxy is a powerful mechanism provided by ArkWeb that acts as a bridge, allowing developers to register ArkTS objects to the frontend page. This enables seamless function calls to these objects from the frontend, significantly enhancing the interaction capabilities between the frontend and the application side in HarmonyOS app development.
(II) Interface Introduction
- javaScriptProxy() Interface: This interface is called during the initialization phase of the Web component. Its primary role is to inject the specified object into the frontend page early in the page loading process, ensuring that the necessary ArkTS object support is available from the start.
- registerJavaScriptProxy() Interface: This interface takes effect after the Web component initialization is complete. It allows for dynamic registration of objects to the frontend page, adding flexibility to the application.
Practical Example: Frontend Calling ArkTS Functions
(I) Application-Side Code (ArkTS) Analysis
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
// Define the test class
class testClass {
constructor() {}
// Test function that returns a string
test(): string {
return 'ArkTS Hello World!';
}
// Function that logs the input string
toString(param: string): void {
console.log('Web Component toString' + param);
}
}
// Define the Web component
@Entry
@Component
struct WebComponent {
webviewController: webview.WebviewController = new webview.WebviewController();
// Declare and initialize the testObj object to be registered to the frontend
@State testObj: testClass = new testClass();
build() {
Column() {
// Web component loading the local index.html page
Web({ src: $rawfile('index.html'), controller: this.webviewController})
// Use the javaScriptProxy interface to register the testObj object to the frontend
.javaScriptProxy({
object: this.testObj,
name: "testObjName",
methodList: ["test", "toString"],
controller: this.webviewController,
// Optional parameters
asyncMethodList: [],
permission: '{"javascriptProxyPermission":{"urlPermissionList":[{"scheme":"resource","host":"rawfile","port":"","path":""},' +
'{"scheme":"e","host":"f","port":"g","path":"h"}],"methodList":[{"methodName":"test","urlPermissionList":' +
'[{"scheme":"https","host":"xxx.com","port":"","path":""},{"scheme":"resource","host":"rawfile","port":"","path":""}]},' +
'{"methodName":"test11","urlPermissionList":[{"scheme":"q","host":"r","port":"","path":"t"},' +
'{"scheme":"u","host":"v","port":"","path":""}]}]}}'
})
}
}
}
(II) Frontend Page Code (HTML) Analysis
<!-- index.html -->
<!DOCTYPE html>
<html>
<body>
<button type="button" onclick="callArkTS()">Click Me!</button>
<p id="demo"></p>
<script>
function callArkTS() {
// Call the test function of the registered testObjName object and get the return value
let str = testObjName.test();
document.getElementById("demo").innerHTML = str;
console.info('ArkTS Hello World! :' + str);
// Call the toString function of testObjName with the obtained string
testObjName.toString(str);
}
</script>
</body>
</html>
Permission Configuration: Safeguarding Application Security
(I) Permission Configuration Principle
Permission configuration is crucial when calling ArkTS functions from the frontend page. It is defined through a JSON string, covering both object-level and method-level permissions. Object-level permissions specify which URLs can access all methods of the object, while method-level permissions are more granular, defining which URLs can access specific methods of the object. This detailed permission division helps effectively prevent malicious attacks and ensures the security of the application.
(II) Permission Configuration Example
{
"javascriptProxyPermission": {
"urlPermissionList": [
{
"scheme": "resource", // Must be an exact match, cannot be empty, specifies the resource type
"host": "rawfile", // Must be an exact match, cannot be empty, specifies the hostname
"port": "", // Exact match, if empty, port is not checked
"path": "" // Prefix match, if empty, path is not checked
},
{
"scheme": "https", // Exact match, cannot be empty
"host": "xxx.com", // Exact match, cannot be empty
"port": "8080", // Exact match, if empty, port is not checked
"path": "a/b/c" // Prefix match, if empty, path is not checked
}
],
"methodList": [
{
"methodName": "test",
"urlPermissionList": [ // Permission list for the test method
{
"scheme": "https", // Exact match, cannot be empty
"host": "xxx.com", // Exact match, cannot be empty
"port": "", // Exact match, if empty, port is not checked
"path": "" // Prefix match, if empty, path is not checked
},
{
"scheme": "resource",// Exact match, cannot be empty
"host": "rawfile", // Exact match, cannot be empty
"port": "", // Exact match, if empty, port is not checked
"path": "" // Prefix match, if empty, path is not checked
}
]
},
{
"methodName": "test11",
"urlPermissionList": [ // Permission list for the test11 method
{
"scheme": "q", // Exact match, cannot be empty
"host": "r", // Exact match, cannot be empty
"port": "", // Exact match, if empty, port is not checked
"path": "t" // Prefix match, if empty, path is not checked
},
{
"scheme": "u", // Exact match, cannot be empty
"host": "v", // Exact match, cannot be empty
"port": "", // Exact match, if empty, port is not checked
"path": "" // Prefix match, if empty, path is not checked
}
]
}
]
}
}
Complex Type Passing: Beyond Basic Data Interaction
(I) Passing Arrays Example
In practical development, complex data types such as arrays may need to be passed between the frontend and ArkTS. Here is an example of passing an array:
class testClass {
constructor() {}
// Function that returns an array of numbers
test(): Array<number> {
return [1, 2, 3, 4];
}
toString(param: string): void {
console.log('Web Component toString' + param);
}
}
(II) Passing Objects Example
In addition to arrays, passing objects is also very common:
class student {
name: string = '';
age: string = '';
}
class testClass {
constructor() {}
// Function that returns a student object
test(): student {
let st: student = { name: "jeck", age: "12" };
return st;
}
toString(param: string): void {
console.log('Web Component toString' + param);
}
}
Top comments (0)