高级配置

让 AI 处理复杂性

高级插件配置可能很难做对。NativePHP 插件开发工具包生成正确的清单配置、Gradle 依赖项、CocoaPods 规范和平台特定代码——所以你不必记住这些文档。

密钥和环境变量

需要 API 密钥、令牌或其他敏感配置的插件可以使用 secrets 字段声明所需的环境变量。NativePHP 在构建前验证这些。

json

{
    "secrets": {
        "MAPBOX_DOWNLOADS_TOKEN": {
            "description": "Mapbox SDK download token from mapbox.com/account/access-tokens",
            "required": true
        },
        "FIREBASE_API_KEY": {
            "description": "Firebase project API key",
            "required": false
        }
    }
}

每个密钥有：

description — 获取值的说明
required — 如果缺失，构建是否应该失败（默认：true）

使用密钥

使用 ${ENV_VAR} 语法在清单中的任何位置引用密钥：

json

{
    "android": {
        "repositories": [
            {
                "url": "https://api.mapbox.com/downloads/v2/releases/maven",
                "credentials": {
                    "password": "${MAPBOX_DOWNLOADS_TOKEN}"
                }
            }
        ]
    }
}

占位符在构建时被替换。如果缺少必需的密钥，构建将失败，并显示一条有用的消息，告诉用户需要在 .env 文件中设置哪些变量。

Android 清单组件

插件可以注册 Android 组件（Activities、Services、Receivers、Providers），这些组件会合并到应用的 AndroidManifest.xml 中：

json

{
    "android": {
        "activities": [
            {
                "name": ".MyPluginActivity",
                "theme": "@style/Theme.AppCompat.Light.NoActionBar",
                "exported": false,
                "configChanges": "orientation|screenSize"
            }
        ],
        "services": [
            {
                "name": ".BackgroundSyncService",
                "exported": false,
                "foregroundServiceType": "dataSync"
            }
        ],
        "receivers": [
            {
                "name": ".BootReceiver",
                "exported": true,
                "intent-filters": [
                    {
                        "action": "android.intent.action.BOOT_COMPLETED",
                        "category": "android.intent.category.DEFAULT"
                    }
                ]
            }
        ],
        "providers": [
            {
                "name": ".MyContentProvider",
                "authorities": "${applicationId}.myplugin.provider",
                "exported": false,
                "grantUriPermissions": true
            }
        ]
    }
}

组件名称

以 . 开头的名称相对于你的插件包。例如，如果你的插件使用包 com.nativephp.plugins.mlplugin，那么 .MyActivity 变成 com.nativephp.plugins.mlplugin.MyActivity。

对于插件包之外的组件，使用完全限定名。

Activity 属性

属性	描述
`name`	组件类名（必需）
`theme`	Activity 主题资源
`exported`	其他应用是否可以启动此 activity
`configChanges`	activity 自己处理的配置更改
`launchMode`	启动模式（standard、singleTop、singleTask、singleInstance）
`screenOrientation`	方向锁定（portrait、landscape 等）
`intent-filters`	intent filter 配置数组

Service 属性

属性	描述
`name`	组件类名（必需）
`exported`	其他应用是否可以绑定到此服务
`permission`	访问服务所需的权限
`foregroundServiceType`	前台服务的类型（camera、microphone、location 等）。支持数组格式用于多种类型。

Android 功能

使用 features 数组声明插件需要的硬件或软件功能。这些作为 <uses-feature> 元素添加到 AndroidManifest.xml 中：

json

{
    "android": {
        "features": [
            {"name": "android.hardware.camera", "required": true},
            {"name": "android.hardware.camera.autofocus", "required": false},
            {"name": "android.hardware.bluetooth_le", "required": true}
        ]
    }
}

每个功能有：

name — 功能名称（例如 android.hardware.camera）
required — 应用是否需要此功能（默认：true）

设置 required: false 允许你的应用安装在没有该功能的设备上，但你必须在运行时检查可用性。

Android Meta-Data

为 SDK 配置添加应用程序级 <meta-data> 元素：

json

{
    "android": {
        "meta_data": [
            {
                "name": "com.google.android.geo.API_KEY",
                "value": "${GOOGLE_MAPS_API_KEY}"
            },
            {
                "name": "com.google.firebase.messaging.default_notification_icon",
                "value": "@drawable/ic_notification"
            }
        ]
    }
}

每个条目有：

name — meta-data 键
value — 值（支持 ${ENV_VAR} 占位符）

声明式资源

使用 assets 字段将静态文件复制到原生项目。这比为基本文件复制编写 copy_assets 钩子更简单：

json

{
    "assets": {
        "android": {
            "models/detector.tflite": "assets/ml/detector.tflite",
            "config/settings.xml": "res/raw/plugin_settings.xml"
        },
        "ios": {
            "models/detector.mlmodel": "Resources/ml/detector.mlmodel",
            "config/settings.plist": "Resources/plugin_settings.plist"
        }
    }
}

格式为 "source": "destination"：

source — 从插件的 resources/ 目录的相对路径
destination — 在原生项目中放置文件的位置

Android 目标

assets/... — 应用资源（通过 AssetManager 访问）
res/raw/... — 原始资源（通过 R.raw.* 访问）
res/drawable/... — Drawable 资源

iOS 目标

Resources/... — Bundle 资源

占位符替换

基于文本的资源（XML、JSON、plist 等）支持 ${ENV_VAR} 占位符，在构建期间替换为环境变量值：

xml

<!-- resources/config/api.xml -->
<config>
    <api-key>${MY_PLUGIN_API_KEY}</api-key>
</config>

提示

对于复杂的资源处理（如下载大文件、解压档案或条件资源放置），使用生命周期钩子。

iOS 后台模式

使用 background_modes 数组启用后台执行功能。这些值添加到 Info.plist 中的 UIBackgroundModes：

json

{
    "ios": {
        "background_modes": ["audio", "fetch", "processing", "location"]
    }
}

常见值：

audio — 音频播放或录制
fetch — 后台获取
processing — 后台处理任务
location — 位置更新
remote-notification — 推送通知处理
bluetooth-central — 蓝牙 LE 中央模式
bluetooth-peripheral — 蓝牙 LE 外围模式

注意

后台模式需要相应的权利和 App Store 审核。只请求你的插件实际需要的模式。

iOS 权利

为 Maps、App Groups、HealthKit 或 iCloud 等功能配置应用权利：

json

{
    "ios": {
        "entitlements": {
            "com.apple.developer.maps": true,
            "com.apple.security.application-groups": ["group.com.example.shared"],
            "com.apple.developer.associated-domains": ["applinks:example.com"],
            "com.apple.developer.healthkit": true
        }
    }
}

值可以是：

布尔值 — 对于简单功能为 true/false
数组 — 对于需要多个值的功能（App Groups、Associated Domains）
字符串 — 对于单值权利

权利写入 NativePHP.entitlements。如果文件不存在，会自动创建。

注意

许多权利需要在你的 Apple Developer 账号和 Xcode 项目设置中启用相应的功能。

iOS 功能

声明你的插件需要的 iOS 功能。这些与权利分开，用于 Xcode 项目配置：

json

{
    "ios": {
        "capabilities": ["push-notifications", "background-modes", "healthkit"]
    }
}

最低平台版本

指定你的插件需要的最低平台版本：

json

{
    "android": {
        "min_version": 33
    },
    "ios": {
        "min_version": "18.0"
    }
}

Android — 最低 SDK 版本（整数，例如 33 代表 Android 13）
iOS — 最低 iOS 版本（字符串，例如 "18.0"）

NativePHP 目前要求最低 Android SDK 33 和 iOS 18。你的插件的最低版本不能低于这些。当你的插件需要比 NativePHP 基线更高的版本时，使用此字段。

如果用户的应用目标版本低于你的插件要求，他们将在插件验证期间收到警告。

初始化函数

插件可以指定在应用初始化期间调用的原生函数。这对于需要在任何桥接函数调用之前进行早期设置的 SDK 很有用：

json

{
    "android": {
        "init_function": "com.myvendor.plugins.myplugin.MyPluginInit.initialize"
    },
    "ios": {
        "init_function": "MyPluginInit.initialize"
    }
}

初始化函数在应用启动时调用一次，在任何桥接函数可用之前。用于：

必须提前进行的 SDK 初始化
设置全局状态或单例
注册观察者或监听器

注意

初始化函数在应用启动期间同步运行。保持它们快速以避免减慢应用启动。

跳过猜测

从头开始构建这样的插件意味着学习 Gradle、CocoaPods、Swift Package Manager 和两种陌生的语言。NativePHP 插件开发工具包处理所有这些——描述你想要什么，获得一个两个平台配置正确的可工作插件。

完整示例

这是一个集成 Firebase ML Kit 和自定义 Activity 的插件的完整清单：

json

{
    "namespace": "FirebaseML",
    "bridge_functions": [
        {
            "name": "FirebaseML.Analyze",
            "android": "com.nativephp.plugins.firebaseml.AnalyzeFunctions.Analyze",
            "ios": "FirebaseMLFunctions.Analyze"
        }
    ],
    "events": [
        "Vendor\\FirebaseML\\Events\\AnalysisComplete"
    ],
    "android": {
        "permissions": [
            "android.permission.CAMERA",
            "android.permission.INTERNET"
        ],
        "features": [
            {"name": "android.hardware.camera", "required": true}
        ],
        "dependencies": {
            "implementation": [
                "com.google.firebase:firebase-ml-vision:24.1.0",
                "com.google.firebase:firebase-core:21.1.1"
            ]
        },
        "activities": [
            {
                "name": ".CameraPreviewActivity",
                "theme": "@style/Theme.AppCompat.Light.NoActionBar",
                "exported": false,
                "configChanges": "orientation|screenSize|keyboardHidden"
            }
        ],
        "meta_data": [
            {
                "name": "com.google.firebase.ml.vision.DEPENDENCIES",
                "value": "ocr"
            }
        ]
    },
    "ios": {
        "info_plist": {
            "NSCameraUsageDescription": "Camera is used for ML analysis"
        },
        "dependencies": {
            "pods": [
                {"name": "Firebase/MLVision", "version": "~> 10.0"},
                {"name": "Firebase/Core", "version": "~> 10.0"}
            ]
        },
        "background_modes": ["processing"],
        "entitlements": {
            "com.apple.developer.associated-domains": ["applinks:example.com"]
        }
    },
    "assets": {
        "android": {
            "google-services.json": "google-services.json"
        },
        "ios": {
            "GoogleService-Info.plist": "Resources/GoogleService-Info.plist"
        }
    },
    "secrets": {
        "FIREBASE_API_KEY": {
            "description": "Firebase API key from Firebase Console",
            "required": true
        }
    },
    "hooks": {
        "pre_compile": "nativephp:firebase-ml:setup"
    }
}

官方插件和开发工具包

浏览常见用例的现成插件，或获取插件开发工具包来构建你自己的。访问 NativePHP 插件市场 →

高级配置 ​

密钥和环境变量 ​

使用密钥 ​

Android 清单组件 ​

组件名称 ​

Activity 属性 ​

Service 属性 ​

Android 功能 ​

Android Meta-Data ​

声明式资源 ​

Android 目标 ​

iOS 目标 ​

占位符替换 ​

iOS 后台模式 ​

iOS 权利 ​

iOS 功能 ​

最低平台版本 ​

初始化函数 ​

完整示例 ​

官方插件和开发工具包 ​

高级配置

密钥和环境变量

使用密钥

Android 清单组件

组件名称

Activity 属性

Service 属性

Android 功能

Android Meta-Data

声明式资源

Android 目标

iOS 目标

占位符替换

iOS 后台模式

iOS 权利

iOS 功能

最低平台版本

初始化函数

完整示例

官方插件和开发工具包