自定义 JSAPI

要从页面发起 Native 功能调用，例如显示一个 ActionSheet，或显示联系人对话框，您需要扩展一个 JavaScript API（JSAPI）。使用 JSAPI，可以让您在 H5 页面增加 Native 功能调用入口。通过实现自定义 JSAPI 类中的 handler 方法，以 Native 的形式实现特定功能。

H5 容器组件提供以下能力：

• 丰富的内置 JSAPI，实现例如页面 push、pop、标题设置等功能。更多信息，参考 内置 JSAPI。
• 支持用户自定义 JSAPI 和插件功能，扩展业务需求。

本文介绍如何实现自定义 JSAPI 功能。

关于此任务

自定义一个 JSAPI 可以有以下两种方式：

• Plist 注册
• 代码注册

操作步骤

Plist 注册

1. 创建 JSAPI 类：

   • 命名规范：为与容器默认提供的插件命名保持一致，创建的 JSAPI 类命名以 XXJsApi4 开头，其中 XX为自定义的前缀。
   • 基类：所有 JSAPI 均继承自 PSDJsApiHandler。

   • 实现基础方法：在 .m文件中，需重写方法 -(void)handler:context:callback:。当在前端调用此 JSAPI 时，会转发到此方法。

     

     

   • 该方法的参数含义如下：

     参数名	含义
     data	H5 页面调用此 JSAPI 时传入的参数。
     context	当前 H5 页面的上下文，具体可参考 PSDContext.h。
     callback	调用此 JSAPI 完成后的回调方法，以字典方式传递调用结果到 H5 页面。

2. 注册 JSAPI。在自定义的 Plist 文件中注册此 JSAPI。更多具体内容，查看 接入 iOS。

   • 为统一管理自定义的 JSAPI 和 Plugin，新建一个 plsit 文件，内容如下。在 JsApis 数组下注册上一步创建的 JSAPI 类：

     

   • 注册的 JSAPI 是一个字典类型，包含以下两项内容：

     名称	含义
     jsApi	在 H5 页面中调用的 JSAPI 接口名。 注意： 为防止自定义的 JSAPI 与容器内置 JSAPI 相互影响导致不可用，请给自定义 JSAPI 名加上前缀予以区分。
     name	创建的 JSAPI 的类名。

   • 同时需在初始化容器配置时，指定自定义的 Plist 文件的路径。

     • 在 10.1.32 及以上版本中初始化 H5 容器，参见 管理 H5 容器 > 版本 ≥ 10.1.32。

       // 自定义插件配置
       NSString *plist_filePath = [[NSBundle mainBundle].bundlePath stringByAppendingFormat:@"/%@/%@", @"DemoPlugins.bundle", @"Poseidon-Extra-Config.plist"];
       [NBServiceConfigurationGet() setExtraPluginsFilePath:plist_filePath];

代码注册

除使用 Plist 方式自定义一个 JSAPI 外，容器也支持直接调用 Nebula 容器提供的接口方法注册一个自定义的 JSAPI。更多具体内容，查看 代码示例 中 H5Plugin4DemoTest 类里的 addJSApis 方法：

```objective-c
    // 这种 JSAPI 注册是在 plist 中配置之外的另一种方式
    PSDJsApi *jsApi4DemoTest2 = [PSDJsApi jsApi:@"demoTest2"
                                          handler:^(NSDictionary *data, PSDContext *context, PSDJsApiResponseCallbackBlock responseCallbackBlock) {
                                              responseCallbackBlock(@{@"result":@"jsapi-demoTest2调用 Native 的处理结果"});
                                          }
                                      checkParams:NO
                                        isPrivate:NO
                                            scope:self.scope];
    [self registerJsApi2Target:jsApi4DemoTest2];
```

• 下表列出注册时各参数及其含义：

后续操作

1. 在 H5 页面中调用自定义的 JSAPI。
   

   

2. 在 handler 方法中添加断点，观察 H5 页面提供的参数是否符合预期。
   

   

3. 查看 H5 页面返回的结果是否符合预期。
   

相关链接

• 内置 JSAPI：启动参数
• 代码示例