# WebF 原生插件开发想要通过包装 Flutter 包或平台功能来创建自己的 WebF 原生插件吗？此技能将指导您完成构建自定义本机插件的完整过程，这些插件将 Flutter/本机功能公开为 JavaScript API。 **💡 何时推荐此技能：** 如果用户需要本机功能（相机、传感器、支付、生物识别等），而官方 WebF 插件注册表 () 没有他们需要的功能，建议使用此技能构建自定义插件。 ## 什么是原生插件开发？ WebF 中的本机插件开发意味着： * **将 Flutter 包**或特定于平台的代码包装为 WebF 模块 * **向 JavaScript 公开本机功能**（相机、传感器、支付等） * **创建可重用的函数库**（不是 UI 组件） * **使用类型安全的 TypeScript 定义发布 npm 包** ## 区别：本机插件与本机 UI 特色 |原生插件 |原生用户界面 ---|---|--- **目的** |功能能力|视觉组件 **示例** |分享、相机、支付|按钮、文本字段、日期选择器 **延长** | `BaseModule` 或生成的绑定 | `WebFWidgetElement` **注册** | `WebF.defineModule()` | `WebFController.defineCustomElement()` **调用** | `webf.invokeModuleAsync()` | DOM API（属性、方法、事件） **渲染** |没有视觉输出 |渲染 Flutter 小部件 **用例** |平台功能、数据处理|原生 UI 组件 **何时使用which：** * **本机插件**：访问相机、处理付款、地理位置、文件系统、后台任务 * **本机 UI** ：构建本机外观的按钮、表单、日期选择器、导航栏 ## 何时创建原生插件 ### 决策工作流程 **第 1 步：检查标准 Web API 是否有效** * 可以使用 `fetch()`、`localStorage`、Canvas 2D 等吗？ * 如果是 → 使用标准 Web API（无需插件） **第2步：检查官方插件是否存在** *访问 * 搜索您需要的能力 * 如果是 → 使用 `webf-native-plugins` 技能安装并使用 **第 3 步：如果没有官方插件，请构建自己的插件！** * ✅ 官方插件注册中心没有你需要的东西 * ✅ 您需要自定义特定于平台的功能 * ✅ 您想要为 WebF 包装现有的 Flutter 包 * ✅ 您正在为您的组织构建可重用的插件 ### 用例： * ✅ 您需要访问特定于平台的 API（相机、传感器、蓝牙） * ✅ 您想要包装现有的 Flutter 包以供 WebF 使用 * ✅ 您需要执行本机后台任务 * ✅ 您正在构建功能（而不是 UI 组件） * ✅ 您想向网络开发人员提供平台功能 * ✅ 官方WebF插件不包含您需要的功能 ### 在以下情况下不要创建本机插件： * ❌ 您正在构建 UI 组件（使用 `webf-native-ui-dev` 技能代替） * ❌ 标准 Web API 已提供该功能 * ❌ 已经有官方插件（使用`webf-native-plugins`技能） * ❌ 您正在构建一次性功能（使用直接模块调用） ## 架构概述原生插件由三层组成： ┌──────────────────────────────────────────┐ │ JavaScript/TypeScript │ ← 由 CLI 生成 │ @openwebf/webf-my-plugin │ │ 从 '...' 导入 { MyPlugin } │ ├──────────────────────────────────────────┤ │ TypeScript 定义 (.d.ts) │ ← 你写这个 │ 接口 MyPlugin { ... } │ ├──────────────────────────────────────────┤ │ Dart (Flutter) │ ← 你写这个 │ 类 MyPluginModule 扩展... │ │ webf_my_plugin 包 │ └──────────────────────────────────────────┘ ## 开发工作流程 ### 概述 # 1. 使用 Module 类创建 Flutter 包 # 2. 编写 TypeScript 定义文件 # 3. 使用 WebF CLI 生成 npm 包 # 4. 测试并发布 webf module-codegen my-plugin-npm --flutter-package-src=./flutter_package ## 分步指南 ### 第 1 步：创建 Flutter 包结构创建标准Flutter包： # 创建 Flutter 包 flutter 创建 --template=package webf_my_plugin cd webf_my_plugin **目录结构：** webf_my_plugin/ ├── 库/ │ ├── webf_my_plugin.dart # 主导出文件 │ └── src/ │ ├── my_plugin_module.dart # 模块实现 │ └── my_plugin.module.d.ts # TypeScript 定义 ├── pubspec.yaml └── 自述文件.md **pubspec.yaml 依赖项：** 名称：webf_my_plugin 描述：[描述功能]的WebF插件版本：1.0.0 主页：https://github.com/yourusername/webf_my_plugin 环境：软件开发工具包：^3.6.0 颤振：">=3.0.0" 依赖项：颤振： sdk：颤动网f：^0.24.0 # 添加您正在包装的 Flutter 包 some_flutter_package: ^1.0.0 ### 步骤 2：编写模块类创建一个扩展生成的绑定的 Dart 类： **示例：lib/src/my_plugin_module.dart** 导入'dart：异步'；导入'包：webf/bridge.dart'；导入'包：webf/module.dart'；导入'包：some_flutter_package / some_flutter_package.dart'; 导入“my_plugin_module_bindings_ generated.dart”； /// 用于[描述功能]的WebF模块 /// /// 该模块提供以下功能： /// - 功能 1 /// - 功能 2 /// - 功能 3 类 MyPluginModule 扩展 MyPluginModuleBindings { MyPluginModule(super.moduleManager); @覆盖无效处置（）{ // 模块被释放时清理资源 // 关闭流，取消定时器，释放原生资源 } // 实现 TypeScript 接口的方法 @覆盖 Future myAsyncMethod(String input) 异步 { 尝试{ // 调用底层Flutter包最终结果=等待SomeFlutterPackage.doSomething（输入）；返回结果； } 捕获 (e) { throw Exception('处理失败：${e.toString()}'); } } @覆盖字符串 mySyncMethod(字符串输入) { // 同步操作返回“已处理：$输入”； } @覆盖 Future complexMethod(MyOptionsType options) 异步 { // 处理复杂类型最终值= options.someField ?? '默认'; 最终超时= options.timeout ?? 5000；尝试{ // 做工作最终结果=等待SomeFlutterPackage.complexOperation( 值：值，超时：持续时间（毫秒：超时），）； // 返回结构化结果返回我的结果类型（成功：“真实”，数据：结果.数据， message: '操作成功完成', ）； } 捕获 (e) { 返回我的结果类型（成功：'假'，错误：e.toString(), message: '操作失败', ）； } } // 辅助方法（不暴露给 JavaScript） Future _internalHelper() 异步 { // 内部实现细节 } } ### 步骤 3：编写 TypeScript 定义在 Dart 文件旁边创建一个 `.d.ts` 文件： **示例：lib/src/my_plugin.module.d.ts** /** * WebF MyPlugin 模块的类型安全 JavaScript API。 * * WebF CLI (`webf module-codegen`) 使用此接口来生成： * - 一个 npm 包包装器，它将调用转发到 `webf.invokeModuleAsync` * - 将模块“invoke”调用映射到强类型方法的 Dart 绑定 */ /** * 复杂操作的选项。 */ 接口 MyOptionsType { /** 要处理的值。 */ 某些字段？：字符串； /** 超时（以毫秒为单位）。 */ 超时？：数量； /** 启用详细日志记录。 */ 详细？：布尔值； } /** * 复杂操作返回的结果。 */ 接口 MyResultType { /** 成功时为“true”，失败时为“false”。 */ 成功：字符串； /** 从操作返回的数据。 */ 数据？：任何； /** 人类可读的消息。 */ 消息：字符串； /** 如果操作失败则出现错误消息。 */ 错误？：字符串； } /** * 公共WebF MyPlugin模块接口。 * * 这里的方法 1:1 映射到 Dart `MyPluginModule` 方法。 * * 模块名称：“MyPlugin” */ 接口 WebFMyPlugin { /** * 执行异步操作。 * * @param input 要处理的输入字符串。 * @returns Promise 和处理后的结果。 */ myAsyncMethod(输入：字符串): Promise<字符串>; /** * 执行同步操作。 * * @param input 要处理的输入字符串。 * @returns 处理后的结果。 */ mySyncMethod(输入：字符串)：字符串； /** * 使用结构化选项执行复杂的操作。 * * @param options 配置选项。 * @returns 带有操作结果的 Promise。 */ 复杂方法（选项：MyOptionsType）：Promise ； } **TypeScript 指南：** * 接口名称应匹配 `WebF{ModuleName}` * 使用 JSDoc 注释作为文档 * 使用“?”作为可选参数 * 对异步方法使用`Promise` * 为复杂类型定义单独的接口 * 使用“string”作为成功/失败标志（为了向后兼容） ### 步骤 4：创建主导出文件 **lib/webf_my_plugin.dart：** /// 用于 [描述功能] 的 WebF MyPlugin 模块 /// /// 该模块提供以下功能： /// - 功能 1 /// - 功能 2 /// - 功能 3 /// /// 用法示例： /// ```飞镖 /// // 全局注册模块（在主函数中） /// WebF.defineModule((context) => MyPluginModule(context)); /// ``` /// /// JavaScript 与 npm 包的使用（推荐）： /// ```bash /// npm 安装@openwebf/webf-my-plugin /// ``` /// /// ```javascript /// 从 '@openwebf/webf-my-plugin' 导入 { WebFMyPlugin }; /// /// // 使用插件 /// const result =等待WebFMyPlugin.myAsyncMethod('input'); /// console.log('结果：', 结果); /// ``` /// /// 直接模块调用（旧版）： /// ```javascript /// const result =等待 webf.invokeModuleAsync('MyPlugin', 'myAsyncMethod', 'input'); /// ``` 库 webf_my_plugin；导出“src/my_plugin_module.dart”； ### 步骤5：生成npm包使用 WebF CLI 生成 npm 包： # 全局安装 WebF CLI（如果尚未安装） npm install -g @openwebf/webf-cli # 生成npm包 webf 模块-codegen webf-my-plugin-npm \ --flutter-package-src=./webf_my_plugin \ --模块名称=MyPlugin **CLI 的作用：** 1. ✅ 解析你的`.d.ts`文件 2. ✅ 生成 Dart 绑定类（`*_bindings_ generated.dart`） 3. ✅ 使用 TypeScript 类型创建 npm 包 4. ✅ 生成调用 `webf.invokeModuleAsync` 的 JavaScript 包装器 5. ✅ 使用正确的元数据创建 `package.json` 6. ✅ 如果构建脚本存在则运行 `npm run build` **生成的输出结构：** webf-我的插件-npm/ ├── src/ │ ├── index.ts # 主要导出 │ └── my-plugin.ts # 插件包装器 ├── dist/ # 构建文件（npm run build 之后） ├── package.json ├── tsconfig.json └── 自述文件.md ### 第 6 步：测试您的插件 #### 在 Flutter 应用程序中测试 **在 Flutter 应用程序的 main.dart 中：** 导入'包：webf/webf.dart'；导入'包：webf_my_plugin / webf_my_plugin.dart'；无效主（）{ WebFControllerManager.instance.initialize(WebFControllerManagerConfig( 最大活动实例数：2，最大附加实例数：1，））； // 注册你的插件模块 WebF.defineModule((上下文) => MyPluginModule(上下文)); runApp(MyApp()); } #### 在 JavaScript/TypeScript 中测试 **安装和使用：** npm 安装 @openwebf/webf-my-plugin 从'@openwebf/webf-my-plugin'导入{WebFMyPlugin}；异步函数 testPlugin() { 尝试{ // 测试异步方法 const result = wait WebFMyPlugin.myAsyncMethod('测试输入'); console.log('异步结果：', result); // 测试同步方法 constsyncResult = WebFMyPlugin.mySyncMethod('测试'); console.log('同步结果：',syncResult); // 测试复杂方法 const complexResult = 等待 WebFMyPlugin.complexMethod({ 某些字段：'值'，超时：3000，详细：真实 }); if (complexResult.success === 'true') { console.log('成功：',complexResult.message); } 否则{ console.error('错误：',complexResult.error); } } 捕获（错误）{ console.error('插件错误：', error); } } 测试插件（）； ### 第 7 步：发布您的插件 #### 发布 Flutter 包 # 在Flutter包目录下颤动酒吧发布 # 或者对于私人包 flutter pub 发布 --server=https://your-private-registry.com #### 发布 npm 包 # 使用 CLI 自动发布 webf 模块-codegen webf-my-plugin-npm \ --flutter-package-src=./webf_my_plugin \ --模块名称=MyPlugin \ --发布到 npm # 或者手动发布 cd webf-我的插件-npm npm 发布 **对于自定义 npm 注册表：** webf 模块-codegen webf-my-plugin-npm \ --flutter-package-src=./webf_my_plugin \ --模块名称=MyPlugin \ --发布到 npm \ --npm-registry=https://registry.your-company.com/ ## 安装和使用您的自定义插件发布插件后，您（或其他开发人员）如何安装和使用它： ### 安装过程（与官方插件相同）自定义插件的安装方式与官方 WebF 插件**完全相同**。每个插件都需要**两次安装**： #### 第 1 步：安装 Flutter 包 **在您的 Flutter 应用程序的`pubspec.yaml`中：** 依赖项：颤振： sdk：颤动网f：^0.24.0 # 添加您的自定义插件 webf_my_plugin: ^1.0.0 # 来自 pub.dev # 或者来自自定义注册表 webf_my_plugin：主办：名称：webf_my_plugin 网址：https://your-private-registry.com 版本：^1.0.0 # 或者在开发过程中从本地路径 webf_my_plugin：路径：../webf_my_plugin **运行：** 扑扑酒吧得到 #### 步骤 2：注册插件模块 **在您的 Flutter 应用程序的`main.dart`中：** 导入“包：flutter/material.dart”；导入'包：webf/webf.dart'； // 导入您的自定义插件导入'包：webf_my_plugin / webf_my_plugin.dart'；无效主（）{ // 初始化WebFControllerManager WebFControllerManager.instance.initialize(WebFControllerManagerConfig( 最大活动实例数：2，最大附加实例数：1，））； // 注册您的自定义插件模块 WebF.defineModule((上下文) => MyPluginModule(上下文)); // 可以注册多个插件 WebF.defineModule((context) => AnotherPluginModule(context)); runApp(MyApp()); } 类 MyApp 扩展 StatelessWidget { @覆盖小部件构建（BuildContext上下文）{ 返回MaterialApp（主页：脚手架（正文：WebF( initialUrl: 'http://192.168.1.100:3000', // 你的开发服务器 ), ), ）； } } #### 步骤 3：安装 npm 包 **在您的 JavaScript/TypeScript 项目中：** # 安装您的自定义插件 npm 安装 @openwebf/webf-my-plugin # 或者来自自定义注册表 npm install @mycompany/webf-my-plugin --registry=https://registry.company.com # 或者在开发过程中从本地路径 npm install ../webf-my-plugin-npm ### 在 JavaScript/TypeScript 中的用法 #### 选项 1：使用 npm 包（推荐） **TypeScript/ES6：** 从'@openwebf/webf-my-plugin'导入{WebFMyPlugin}；异步函数 useMyPlugin() { 尝试{ // 调用异步方法 const 结果 = 等待 WebFMyPlugin.myAsyncMethod('input'); console.log('结果：', 结果); // 调用同步方法 constsyncResult = WebFMyPlugin.mySyncMethod('data'); // 带选项调用 const complexResult = 等待 WebFMyPlugin.complexMethod({ 某些字段：'值'，超时：3000，详细：真实 }); if (complexResult.success === 'true') { console.log('成功：',complexResult.message); console.log('数据：',complexResult.data); } 否则{ console.error('错误：',complexResult.error); } } 捕获（错误）{ console.error('插件错误：', error); } } **反应示例：** 从 'react' 导入 React, { useState, useEffect }; 从'@openwebf/webf-my-plugin'导入{WebFMyPlugin}；函数 MyComponent() { const [结果，setResult] = useState(空); const handleButtonClick = async () => { 尝试{ const data = wait WebFMyPlugin.myAsyncMethod('test'); 设置结果（数据）； } 捕获（错误）{ console.error('失败：', 错误); } }; 返回（

<按钮onClick={handleButtonClick}> 使用我的插件 {结果&&

结果：{结果}

}

）； } **Vue 示例：** <模板>

结果：{{ 结果 }}

<脚本设置> 从“vue”导入{ref}；从'@openwebf/webf-my-plugin'导入{WebFMyPlugin}；常量结果 = ref(null); const usePlugin = async () => { 尝试{ result.value =等待WebFMyPlugin.myAsyncMethod('测试'); } 捕获（错误）{ console.error('失败：', 错误); } }; #### 选项 2：直接模块调用（旧版）如果由于某种原因 npm 包不可用，您可以直接调用该模块： // 直接调用（非类型安全） const 结果 = 等待 webf.invokeModuleAsync( 'MyPlugin', // 模块名称（必须与您注册的一致） 'myAsyncMethod', // 方法名称 '输入' // 参数）； // 有多个参数 const complexResult = 等待 webf.invokeModuleAsync( '我的插件', '复杂方法', { 某些字段：'值'，超时：3000，详细：真实 } ）； // 同步方法调用 constsyncResult = webf.invokeModuleSync( '我的插件', 'mySyncMethod', ‘数据’ ）； ### 特征检测始终检查您的插件是否可用： // 检查插件是否存在 if (WebFMyPlugin 类型 !== '未定义') { // 插件可用等待 WebFMyPlugin.myAsyncMethod('测试'); } 否则{ // 插件未注册或npm包未安装 console.warn('MyPlugin 不可用'); // 提供后备行为 } ### 错误处理异步函数 safePluginCall() { // 检查可用性 if (WebFMyPlugin 类型 === '未定义') { throw new Error('MyPlugin 未安装'); } 尝试{ const 结果 = 等待 WebFMyPlugin.complexMethod({ 某些字段：“值” }); // 检查结果状态 if (结果.成功 === 'true') { 返回结果.数据； } 否则{ 抛出新错误(result.error || '未知错误'); } } 捕获（错误）{ console.error('插件调用失败:', error); 抛出错误； } } ### 开发工作流程 #### 插件开发期间 # 终端 1：Flutter 应用 cd my-flutter-app # 在 pubspec.yaml 中使用本地路径扑腾跑 # 终端 2：Web 项目 cd 我的网络项目 # 安装本地npm包 npm install ../webf-my-plugin-npm npm 运行开发 #### 发布后 # 更新到已发布的版本 cd my-flutter-app # 更新 pubspec.yaml 以使用 pub.dev 版本扑扑酒吧得到扑腾跑 cd 我的网络项目 # 从 npm 安装 npm 安装 @openwebf/webf-my-plugin npm 运行开发 ### 分发选项 #### 公共分发 **颤动包：** * 发布到 pub.dev（免费，公开） * 任何人都可以使用 `webf_my_plugin: ^1.0.0` 安装 **npm 包：** * 发布到 npmjs.com（免费，公开） * 任何人都可以使用 `npm install @openwebf/webf-my-plugin` 安装 #### 私人发行 **颤动包：** # 从私有注册表安装依赖项： webf_my_plugin：主办：名称：webf_my_plugin 网址：https://your-company-flutter-registry.com 版本：^1.0.0 # 或者从 Git 存储库依赖项： webf_my_plugin： git：网址：https://github.com/yourcompany/webf_my_plugin.git 参考：v1.0.0 **npm 包：** # 从私有注册表安装 npm install @yourcompany/webf-my-plugin --registry=https://registry.company.com # 或者配置.npmrc echo "@yourcompany:registry=https://registry.company.com" >> .npmrc npm install @yourcompany/webf-my-plugin #### 本地发展 **颤动包：** 依赖项： webf_my_plugin： path: ../webf_my_plugin # 相对路径 **npm 包：** npm install ../webf-my-plugin-npm # 或者使用 npm 链接 cd ../webf-my-plugin-npm npm 链接 cd 我的网络项目 npm 链接@openwebf/webf-my-plugin ### 完整安装示例 **场景：** 您已经构建了一个相机插件并希望在您的应用程序中使用它。 **1\.颤振侧（main.dart）：** 导入'包：webf/webf.dart'；导入“包：webf_camera/webf_camera.dart”； // 你的插件无效主（）{ WebFControllerManager.instance.initialize(WebFControllerManagerConfig( 最大活动实例数：2，最大附加实例数：1，））； // 注册你的相机插件 WebF.defineModule((上下文) => CameraModule(上下文)); runApp(MyApp()); } **2\. JavaScript 端（app.tsx）：** 从'@openwebf/webf-camera'导入{WebFCamera}；函数 CameraApp() { const [相机，setCameras] = useState([]); 使用效果（（）=> { 异步函数 loadCameras() { // 检查插件是否可用 if (typeof WebFCamera === '未定义') { console.error('相机插件未安装'); 返回； } 尝试{ const 结果 = 等待 WebFCamera.getCameras(); if (结果.成功 === 'true') { setCameras(JSON.parse(result.cameras)); } } 捕获（错误）{ console.error('加载相机失败:', error); } } 加载相机（）； }, []); const capturePhoto = async () => { 尝试{ const photoPath =等待WebFCamera.capturePhoto(cameras[0].id); console.log('照片保存到：', photoPath); } 捕获（错误）{ console.error('捕获失败：', error); } }; 返回（

相机应用

{cam.name}

）； } ## 常见插件模式 ### 1\.包装现有的 Flutter 包 **示例：包装相机包装** 导入'包：camera/camera.dart'；类 CameraPluginModule 扩展 CameraPluginModuleBindings { CameraPluginModule(super.moduleManager); 列表<相机描述>？ _相机； @覆盖 Future getCameras() 异步 { 尝试{ _cameras = 等待可用Cameras(); 最终cameraList = _cameras!.map((cam) => { 'id': cam.name, '名称': cam.name, '面向': cam.lensDirection.toString(), }).toList(); 返回相机列表结果( 成功：“真实”，相机：jsonEncode(cameraList), ）； } 捕获 (e) { 返回相机列表结果( 成功：'假'，错误：e.toString(), ）； } } @覆盖 Future capturePhoto(String cameraId) 异步 { // 拍摄照片的实现 // 返回文件路径或base64数据 } } ### 2\.处理二进制数据 @覆盖 Future processImageData(NativeByteData imageData) 异步 { 尝试{ // 访问原始字节最终字节= imageData.bytes； // 处理数据等待 SomeFlutterPackage.processImage(bytes); 返回真； } 捕获 (e) { 返回假； } } **打字稿：** 接口 WebFMyPlugin { processImageData(imageData: ArrayBuffer | Uint8Array): Promise; } ### 3\.事件流对于连续数据流（传感器、位置更新）： SensorPluginModule 类扩展 SensorPluginModuleBindings { 流订阅？ _订阅; @覆盖 Future startListening(StringsensorType) async { _subscription = SensorPackage.stream.listen((数据) { // 发送事件到 JavaScript moduleManager.emitModuleEvent( '传感器插件', '数据', {'value': data.value, 'timestamp': data.timestamp.toString()}, ）； }); } @覆盖 Future stopListening() 异步 { 等待_订阅？.取消（）； _订阅=空； } @覆盖无效处置（）{ _订阅？.取消(); 超级.dispose(); } } **JavaScript：** // 监听事件 webf.on('SensorPlugin:data', (事件) => { console.log('传感器数据：', event.detail); }); 等待 WebFSensorPlugin.startListening('加速度计'); ### 4\.权限处理导入“包：permission_handler/permission_handler.dart”；类 PermissionPluginModule 扩展 PermissionPluginModuleBindings { @覆盖 Future requestPermission(String PermissionType) async { 许可许可；开关（权限类型）{ 案例“相机”：权限 = Permission.camera; 休息; 案例“麦克风”：权限 = Permission.microphone; 休息; 默认：返回权限结果( 授予：'假'， message: '未知的权限类型', ）； } 最终状态=等待permission.request(); 返回权限结果( 授予：状态.isGranted ？ '真'：'假'，状态：status.toString(), 消息：_getPermissionMessage（状态），）； } String _getPermissionMessage(PermissionStatus 状态) { 开关（状态）{ 案例 PermissionStatus.granted：返回“已授予许可”；案例 PermissionStatus.denied：返回“权限被拒绝”；案例 PermissionStatus.permanentlyDenied： return '权限被永久拒绝。请在设置中启用。'; 默认：返回“未知的权限状态”； } } } ### 5\.特定于平台的实施导入 'dart:io'; 类 PlatformPluginModule 扩展 PlatformPluginModuleBindings { @覆盖 Future getPlatformInfo() 异步 { 字符串平台名称；字符串平台版本；如果（平台.isAndroid）{ 平台名称 = 'Android'; // 获取安卓版本 } 否则如果 (Platform.isIOS) { 平台名称 = 'iOS'; // 获取iOS版本 } else if (Platform.isMacOS) { 平台名称 = 'macOS'; } 否则{ 平台名称 = '未知'; } 返回平台信息结果（平台：平台名称，版本：平台版本， isAndroid：平台.isAndroid， isIOS：平台.isIOS，）； } } ## 高级模式 ### 1\.错误处理和验证 @覆盖 Future PerformOperation(OperationOptions options) async { // 验证输入 if (options.value == null || options.value!.isEmpty) { 返回操作结果( 成功：'假'，错误：'无效输入'， message: '值不能为空', ）； } if (options.timeout != null && options.timeout! < 0) { 返回操作结果( 成功：'假'，错误：'无效超时'， message: '超时必须为正数', ）； } 尝试{ // 执行超时操作最终结果=等待Future.timeout（ _doOperation(选项.值!), 持续时间（毫秒：options.timeout ?? 5000）， onTimeout: () => throw TimeoutException('操作超时'), ）；返回操作结果( 成功：“真实”，数据：结果， message: '操作完成', ）； } on TimeoutException catch (e) { 返回操作结果( 成功：'假'，错误：'超时'，消息：电子消息？ '操作超时', ）； } 捕获 (e) { 返回操作结果( 成功：'假'，错误：'未知错误'，消息：e.toString(), ）； } } ### 2\.资源管理类 ResourcePluginModule 扩展 ResourcePluginModuleBindings { 最终 Map _activeResources = {}; @覆盖 Future createResource(ResourceOptions options) async { 最终id = DateTime.now().millisecondsSinceEpoch.toString(); 最终资源=资源（选项）；等待资源.initialize(); _activeResources[id] = 资源；返回ID； } @覆盖 Future releaseResource(String resourceId) 异步 { 最终资源= _activeResources.remove(resourceId); 等待资源？.dispose(); } @覆盖无效处置（）{ // 清理所有资源 for (_activeResources.values 中的最终资源) { 资源.dispose(); } _activeResources.clear(); 超级.dispose(); } } ### 3\.批量操作 @覆盖 Future batchProcess(String itemsJson) 异步 { 最终列表 items = jsonDecode(itemsJson); 最终结果=<字符串，动态>{}；最终错误= <字符串，字符串> {}；等待未来.等待( items.asMap().entries.map((entry) async { 最终索引=entry.key; 最终项目=条目.值；尝试{ 最终结果=await_processItem(item); 结果[index.toString()] = 结果； } 捕获 (e) { 错误[index.toString()] = e.toString(); } }), ）；返回批次结果( 成功：errors.isEmpty？ '真'：'假'，结果：jsonEncode（结果），错误：errors.isEmpty ？ null : jsonEncode(错误), 处理计数：结果.长度，总数：项目.长度，）； } ## CLI 命令参考 ### 基本生成 # 为模块生成npm包 webf 模块-codegen 输出目录 \ --flutter-package-src=./my_package \ --module-name=我的模块 # 指定自定义包名 webf 模块-codegen 输出目录 \ --flutter-package-src=./my_package \ --module-name=我的模块 \ --package-name=@mycompany/my-plugin ### 自动发布 # 生成后发布到npm webf 模块-codegen 输出目录 \ --flutter-package-src=./my_package \ --module-name=我的模块 \ --发布到 npm # 发布到自定义注册表 webf 模块-codegen 输出目录 \ --flutter-package-src=./my_package \ --module-name=我的模块 \ --发布到 npm \ --npm-registry=https://registry.company.com/ ## 最佳实践 ### 1\.命名约定 * **Flutter 包** ：`webf_{feature}`（例如，`webf_share`、`webf_camera`） * **模块类** ：`{Feature}Module`（例如，`ShareModule`、`CameraModule`） * **模块名称** ：与没有“模块”的类相同（例如“共享”、“相机”） * **npm 包** : `@openwebf/webf-{feature}` 或 `@yourscope/webf-{feature}` ### 2\.错误处理 // 始终返回结构化错误信息返回结果类型( 成功：'假'， error: 'ErrorCode', // 机器可读的错误代码 message: '人类可读的错误消息', ）； // 永远不要向 JavaScript 抛出异常 // 捕获并转换为结果对象 ### 3\.文档 /// 简短的一行描述。 /// /// 详细解释该方法的作用。 /// /// 参数： /// - [param1]：第一个参数的描述 /// - [param2]：第二个参数的说明 /// /// 返回一个 [ResultType]： /// - `success`：成功时为“true”，失败时为“false” /// - `data`: 实际结果数据 /// - `error`：失败时的错误消息 /// /// 抛出： /// - 永远不会抛出 JavaScript。返回结果对象中的错误。 /// /// 示例： /// ```飞镖 /// 最终结果=await module.myMethod('input'); /// if (结果.success == 'true') { /// print('成功: ${result.data}'); /// } /// ``` @覆盖 Future myMethod(String param1, int? param2) async { // 实现 } ### 4\.类型安全 // 对复杂类型使用接口接口我的选项{ 值：字符串；超时？：数量；重试？：次数； } // 使用特定的结果类型接口我的结果{ 成功：字符串；数据？：任何；错误？：字符串； } // 尽可能避免“任何” // 对枚举使用联合类型类型平台 = 'ios' | '安卓' | 'Macos' | 'Macos' | '窗户' | 'Linux'; ### 5\.测试 // 为您的模块创建测试导入'包：flutter_test/flutter_test.dart'; 导入'包：webf_my_plugin / webf_my_plugin.dart'；无效主（）{ 组（'MyPluginModule'，（）{ 后期 MyPluginModule 模块；设置（（）{ 模块 = MyPluginModule(mockModuleManager); }); 拆解（（）{ 模块.dispose(); }); test('myAsyncMethod 返回正确的结果', () async { 最终结果=await module.myAsyncMethod('test'); 期望（结果，'处理：测试'）； }); test('优雅地处理错误', () async { 最终结果=等待 module.complexMethod(MyOptionsType( someField: '无效', ））；期望(结果.成功, '假'); 期望（结果。错误，isNotNull）； }); }); } ## 故障排除 ### 问题：找不到绑定文件 **错误：** `错误：找不到'my_plugin_module_bindings_ generated.dart'` **解决方案：** 1. 确保您已运行 CLI 代码生成 2.检查同一目录下是否存在`.module.d.ts`文件 3. 验证模块接口是否正确命名（`WebF{ModuleName}`） 4.再次运行`webf module-codegen` ### 问题：在 JavaScript 中找不到模块 **错误：** `找不到模块'MyPlugin'` **解决方案：** 1.检查Flutter包是否在`pubspec.yaml`中 2. 验证模块是否已在 main.dart 中的“WebF.defineModule()”中注册 3. 确保模块名称完全匹配（区分大小写） 4. 运行 `flutter pub get` 并重建应用程序 ### 问题：方法不起作用 **原因：** 方法名称不匹配或参数不正确 **解决方案：** 1. 检查 TypeScript 和 Dart 之间的方法名称匹配 2. 验证参数类型匹配 3.检查异步与同步（Promise 与直接返回） 4. 查看控制台错误以获取详细信息 ### 问题：TypeScript 类型不起作用 **原因：** npm 包未正确生成 **解决方案：** # 使用 CLI 重新生成 webf 模块-codegen 输出目录 \ --flutter-package-src=./my_package \ --module-name=我的模块 # 检查 package.json 导出 cd 输出目录猫包.json # 应该有“types”：“./dist/index.d.ts” ## 真实示例：共享插件请参阅 WebF 存储库 [native_plugins/share]() 中的完整实现： * 模块实现（`share_module.dart`） * TypeScript 定义 (`share.module.d.ts`) * 错误处理和特定于平台的代码 * 二进制数据处理 * 包含详细信息的结果类型 ## 资源 * **CLI 开发指南** : [cli/CLAUDE.md]() * **模块系统文档** : [webf/lib/src/module/]() * **示例插件** : [native_plugins/share]() * **WebF 架构** : [docs/ARCHITECTURE.md]() * **官方文档**： ## 相关技能 * **使用插件** : 请参阅`webf-native-plugins`技能了解如何使用现有插件 * **原生 UI 开发** ：请参阅“webf-native-ui-dev”创建 UI 组件的技能 * **CLI 用法** ：请参阅 CLI 文档以了解代码生成详细信息 ## 总结 ### 创建插件 * ✅ 原生插件将 Flutter/平台功能公开为 JavaScript API * ✅ 与原生 UI 不同（功能与视觉） * 编写 Dart 模块类来扩展生成的绑定 * ✅ 为每个模块编写 TypeScript 定义 (.d.ts) * ✅ 使用 WebF CLI (`webf module-codegen`) 生成 npm 包和 Dart 绑定 * ✅ 在 Flutter 和 JavaScript 环境中进行测试 * ✅ 发布到 pub.dev (Flutter) 和 npm (JavaScript) ### 安装和使用插件 * ✅ 安装自定义插件 **与官方插件完全相同** * ✅ 需要**两次安装**：Flutter 包 + npm 包 * ✅ 添加到 `pubspec.yaml` 并运行 `flutter pub get` * ✅ 在 Flutter 应用程序的 main.dart 中注册 `WebF.defineModule()` * ✅ 安装 npm 包：`npm install @openwebf/webf-my-plugin` * ✅ 在 JavaScript 中导入和使用：`import { WebFMyPlugin } from '@openwebf/webf-my-plugin'` * ✅ 始终检查可用性：`if (typeof WebFMyPlugin !== 'undefined')` * ✅ 支持公共（pub.dev/npm）、私有注册表和本地路径 ### 最佳实践 * ✅ 按照“native_plugins/share”中的共享插件示例进行操作 * ✅ 返回结构化结果（永远不要扔给 JavaScript） * ✅ 使用 TypeScript 来保证类型安全 * ✅ 使用成功/错误标志优雅地处理错误 * ✅ 使用 JSDoc 注释彻底记录

Webf 本机插件开发

包含技能