# WebF 本机插件构建 WebF 应用程序时，您通常需要访问本机平台功能，例如共享内容、访问摄像头、处理付款或使用地理位置。 WebF 提供**本机插件**，将 JavaScript 代码与本机平台 API 桥接起来。 ## 什么是本机插件？本机插件是具有以下功能的软件包： * **提供原生平台能力**（共享、摄像头、支付、传感器等） * **跨 iOS、Android、macOS 和其他平台工作** * **在代码中使用 JavaScript API** * **需要安装 Flutter 和 npm 包** * **通过 Flutter 桥接到原生平台 API** ## 何时使用本机插件当您需要标准 Web API 中不可用的功能时，请使用本机插件： ### 使用本机插件： * 与其他应用程序共享内容 * 访问设备相机或照片库 * 处理付款 * 获取本地精度的地理定位 * 推送通知 * 生物特征认证（Face ID、指纹） * 设备传感器（加速度计、陀螺仪） * Web 存储之外的文件系统访问 * 原生日历/联系人集成 ### 标准 Web API 无需插件即可工作： * 用于 HTTP 请求的 `fetch()` * `localStorage` 用于本地存储 * 用于图形的 Canvas 2D * 地理定位API（基本） * 响应式设计的媒体查询 ## 查找可用的插件在实现功能之前，**始终检查**是否存在预构建的本机插件： 1.访问官方插件注册表：**** 2. 按类别浏览可用插件 3.查看插件文档了解安装步骤 ## 安装过程每个本机插件都需要**两次安装**： 1. **Flutter 端**（在您的 Flutter 主机应用程序中） 2. **JavaScript 端**（在您的 Web 项目中） ### 第 1 步：检查插件可用性访问并搜索您需要的功能： * 点击插件查看详情 * 记下 Flutter 包名称（例如 `webf_share`） * 记下 npm 包名称（例如，`@openwebf/webf-share`） ### 步骤 2：安装 Flutter 包如果您有权访问托管 WebF 应用程序的 Flutter 项目： 1.打开Flutter项目的`pubspec.yaml` 2.添加插件依赖：依赖项： webf_share: ^1.0.0 # 替换为实际插件名称 3. 运行 `flutter pub get` 4. 在主 Dart 文件中注册插件：导入'包：webf/webf.dart'；导入'包：webf_share / webf_share.dart'； // 导入插件无效主（）{ // 初始化WebFControllerManager WebFControllerManager.instance.initialize(WebFControllerManagerConfig( 最大活动实例数：2，最大附加实例数：1，））； // 注册原生插件模块 WebF.defineModule((上下文) => ShareModule(上下文)); runApp(MyApp()); } ### 步骤 3：安装 npm 包在您的 JavaScript/TypeScript 项目中： # 对于共享插件示例 npm 安装@openwebf/webf-share # 或者用纱线纱线添加@openwebf/webf-share ### 步骤 4：在 JavaScript 代码中使用在您的应用程序中导入并使用该插件：从'@openwebf/webf-share'导入{WebFShare}； // 使用插件API const success = 等待 WebFShare.shareText({ 标题：“我的应用程序”， text: '看看这个精彩的内容！', 网址：'https://example.com' }); ## 可用插件 ### 分享插件 (webf_share) **描述**：通过原生平台分享来分享内容、文字、图片 **能力**： * 与其他应用程序共享文本、URL 和标题 * 使用原生共享机制共享图像 * 将屏幕截图保存到设备存储中 * 创建预览图像以供临时显示 **颤振包** : `webf_share: ^1.0.0` **npm 包**：`@openwebf/webf-share` **用法示例**：从 '@openwebf/webf-share' 导入 { WebFShare, ShareHelpers }； // 分享文本内容等待 WebFShare.shareText({ title: '文章标题', text: '看看这篇文章！', 网址：'https://example.com/article' }); // 分享画布上的图像 const canvas = document.getElementById('myCanvas'); const imageData = ShareHelpers.canvasToArrayBuffer(canvas); 等待 WebFShare.shareImage(imageData); // 保存截图等待 WebFShare.saveScreenshot(imageData); **存储位置**： * Android：下载文件夹（`/storage/emulated/0/Download/`） * iOS：应用程序文档目录（可通过文件应用程序访问） * macOS：应用程序文档目录（可通过 Finder 访问）有关更多可用插件，请参阅[本机插件参考]()。 ## 常见模式 ### 1\.特征检测在使用插件之前始终检查插件是否可用： // 检查插件是否加载 if (typeof WebFShare !== '未定义') { 等待 WebFShare.shareText({ text: 'Hello' }); } 否则{ // 回退或显示消息 console.log('共享插件不可用'); } ### 2\.错误处理将插件调用包装在 try-catch 块中：尝试{ const success = 等待 WebFShare.shareText({ 标题：“我的应用程序”，文字：“看看这个！” }); 如果（成功）{ console.log('内容分享成功'); } } 捕获（错误）{ console.error('分享失败：', error); // 向用户显示错误信息 } ### 3\. TypeScript 类型安全所有插件都包含 TypeScript 定义：从 '@openwebf/webf-share' 导入类型 { ShareTextOptions }； const shareOptions: ShareTextOptions = { 标题：'文章'， text: '阅读这篇文章', 网址：'https://example.com' }; 等待 WebFShare.shareText(shareOptions); ## 创建自定义插件如果您需要现有插件未提供的功能，您可以创建自己的： 1. **阅读插件开发指南**： 2. **研究现有插件** : 3. **遵循插件架构**： * 创建一个实现原生功能的Flutter包 * 创建一个公开 JavaScript API 的 npm 包 * 使用WebF的模块系统来桥接它们 ## 故障排除 ### 问题：在 JavaScript 中找不到插件 **原因**：Flutter 包未安装或模块未注册 **解决方案**： 1.检查Flutter包是否在`pubspec.yaml`中 2. 验证模块是否已在 main.dart 中的“WebF.defineModule()”中注册 3. 运行 `flutter pub get` 4. 重建 Flutter 应用 5. 重新启动 WebF Go 或您的应用程序 ### 问题：TypeScript 错误 **原因**：npm 软件包未正确安装 **解决方案**： # 重新安装包 npm install @openwebf/webf-share --save # 清除缓存并重新安装 rm -rf node_modules package-lock.json npm 安装 ### 问题：插件适用于 iOS，但不适用于 Android **原因**：缺少特定于平台的权限或配置 **解决方案**： 1.检查插件文档以获得所需的权限 2. 在`AndroidManifest.xml`或`Info.plist`中添加必要的权限 3. 部分插件需要额外的原生配置 ### 问题：“模块未定义”错误 **原因**：插件模块未在 Flutter 中注册 **解决方案**：确保在 Flutter `main()` 函数中 `runApp()` 之前调用 `WebF.defineModule()`：无效主（）{ WebF.defineModule((上下文) => ShareModule(上下文)); runApp(MyApp()); } ## 最佳实践 ### 1\.首先检查插件可用性在实现功能之前，请访问查看插件是否已存在。不要重新发明轮子。 ### 2\.多平台测试本机插件在 iOS、Android 和 macOS 上的行为可能有所不同： * 在所有目标平台上进行测试 * 优雅地处理特定于平台的行为 * 阅读插件文档以了解平台差异 ### 3\.提供后备方案并非所有用户都可能安装该插件（尤其是在开发期间）： if (typeof WebFShare !== '未定义') { // 使用原生共享等待 WebFShare.shareText({ text: 'Hello' }); } 否则{ // 后备：复制到剪贴板或显示链接 navigator.clipboard.writeText('你好'); } ### 4\.正确处理权限有些插件需要用户权限（相机、位置等）： * 在适当的时候请求权限 * 解释为什么你需要许可 * 优雅地处理权限拒绝 * 检查插件文档以了解权限要求 ### 5\.保持插件更新更新了本机插件以支持新的平台功能并修复错误： * 定期检查插件更新 * 更新前阅读变更日志 * 更新后彻底测试 ## 生产部署部署到生产时： 1. **Flutter App** ：确保所有必需的插件都在`pubspec.yaml`中 2. **npm Packages** : 在 `package.json` 中包含所有插件包 3. **权限** ：在应用程序清单中配置所有必需的权限 4. **测试** ：在所有目标平台的真实设备上进行测试 5. **文档**：记录您的应用程序需要哪些插件 ## 资源 * **插件注册表**： * **插件开发指南** : * **示例插件** : * **WebF 文档** ： ## 后续步骤安装本机插件后： 1. **阅读插件文档**：每个插件都有特定的API和要求 2. **在设备上测试**：本机功能的工作方式与 Web API 不同 3. **处理错误**：本机调用可能由于权限或平台限制而失败 4. **考虑替代方案**：检查 Web API 替代方案的“webf-api-compatibility” ## 总结 * 本机插件提供对 Web API 之外的平台功能的访问 * 检查是否有可用插件 * 安装 Flutter 包 (pubspec.yaml) 和 npm 包 * 在main.dart中使用`WebF.defineModule()`注册插件 * 在 JavaScript 中使用特征检测和错误处理 * 在所有目标平台上进行测试 * 如果需要，使用插件开发指南创建自定义插件

Webf 本机插件

包含技能