桥接函数

桥接函数如何工作

桥接函数是你的 PHP 代码和原生平台代码之间的连接。当你调用像 MyPlugin::doSomething() 这样的方法时，NativePHP 将其路由到设备上运行的 Swift 或 Kotlin 实现。

流程：

1. PHP 调用 nativephp_call('MyPlugin.DoSomething', $params)
2. 原生桥接定位已注册的函数
3. 你的原生代码执行并返回响应
4. PHP 接收结果

声明桥接函数

在你的 nativephp.json 中，声明每个函数及其平台实现：

{
    "bridge_functions": [
        {
            "name": "MyPlugin.DoSomething",
            "ios": "MyPluginFunctions.DoSomething",
            "android": "com.myvendor.plugins.myplugin.MyPluginFunctions.DoSomething",
            "description": "Does something useful"
        }
    ]
}

name 是 PHP 使用的。平台特定的值指向你的原生类和方法。

命名约定

• name — 像 MyPlugin.DoSomething 这样的唯一标识符。这是 PHP 代码使用的。
• ios — Swift 枚举/类路径：EnumName.ClassName
• android — 包含供应商包的完整 Kotlin 类路径（例如 com.myvendor.plugins.myplugin.ClassName）

Swift 实现 (iOS)

在 resources/ios/Sources/ 中创建你的函数：

import Foundation

enum MyPluginFunctions {

    class DoSomething: BridgeFunction {
        func execute(parameters: [String: Any]) throws -> [String: Any] {
            let option = parameters["option"] as? String ?? ""

            // 在这里执行你的原生工作

            return BridgeResponse.success(data: [
                "result": "completed",
                "option": option
            ])
        }
    }
}

关键点：

• 实现 BridgeFunction 协议
• 参数作为字典传入
• 使用 BridgeResponse.success() 或 BridgeResponse.error() 返回

Kotlin 实现 (Android)

在 resources/android/src/ 中创建你的函数。使用你自己的供应商命名空间包：

package com.myvendor.plugins.myplugin

import com.nativephp.mobile.bridge.BridgeFunction
import com.nativephp.mobile.bridge.BridgeResponse

object MyPluginFunctions {

    class DoSomething : BridgeFunction {
        override fun execute(parameters: Map<String, Any>): Map<String, Any> {
            val option = parameters["option"] as? String ?: ""

            // 在这里执行你的原生工作

            return BridgeResponse.success(mapOf(
                "result" to "completed",
                "option" to option
            ))
        }
    }
}

包声明决定了你的文件在编译期间放置的位置。使用 com.myvendor.plugins.myplugin 确保你的代码与其他插件和核心 NativePHP 代码隔离。

从 PHP 调用

创建一个调用桥接函数的 facade 方法：

class MyPlugin
{
    public function doSomething(array $options = []): mixed
    {
        if (function_exists('nativephp_call')) {
            $result = nativephp_call('MyPlugin.DoSomething', json_encode($options));

            return json_decode($result)?->data;
        }

        return null;
    }
}

错误处理

使用 BridgeResponse.error() 从原生代码返回错误：

// Swift
return BridgeResponse.error(message: "Something went wrong")

// Kotlin
return BridgeResponse.error("Something went wrong")

错误消息通过响应在 PHP 中可用。

官方插件和开发工具包

需要原生功能但不想编写 Kotlin 或 Swift？浏览现成的插件或获取开发工具包来构建你自己的。 访问 NativePHP 插件市场 →