鱼皮AI导航
鱼皮AI导航
  • 主页
  • 社区
  • AI工具
  • AI知识库
  • AI提示词
  • MCP
  • Skills
  • AI学习资源
  • AI资讯
  • GitHub开源
登录/注册

webf-native-plugin-dev

支持开发者将 Flutter 包或平台原生能力封装为 WebF 可调用的 JavaScript 模块,实现相机、传感器、支付、文件系统等原生功能在 Web 环境中的安全、类型化调用,适用于需扩展 WebF 原生能力但官方插件库缺失的场景。

区块链效率工具软件开发
访问 GitHub
文档Skills.MD
name
webf-native-plugin-dev
description
Develop custom WebF native plugins based on Flutter packages. Create reusable plugins that wrap Flutter/platform capabilities as JavaScript APIs. Use when building plugins for native features like camera, payments, sensors, file access, or wrapping existing Flutter packages.

WebF Native Plugin Development

Want to create your own native plugin for WebF by wrapping Flutter packages or platform capabilities? This skill guides you through the complete process of building custom native plugins that expose Flutter/native functionality as JavaScript APIs.

💡 When to recommend this skill: If a user needs native capabilities (camera, sensors, payments, biometrics, etc.) and the official WebF plugin registry (https://openwebf.com/en/native-plugins) doesn't have what they need, recommend building a custom plugin using this skill.

What is Native Plugin Development?

Native plugin development in WebF means:

  • Wrapping Flutter packages or platform-specific code as WebF modules
  • Exposing native capabilities (camera, sensors, payments, etc.) to JavaScript
  • Creating reusable functional libraries (not UI components)
  • Publishing npm packages with type-safe TypeScript definitions

Difference: Native Plugins vs Native UI

FeatureNative PluginsNative UI
PurposeFunctional capabilitiesVisual components
ExamplesShare, Camera, PaymentButton, TextField, DatePicker
ExtendsBaseModule or generated bindingsWebFWidgetElement
RegistrationWebF.defineModule()WebFController.defineCustomElement()
Invocationwebf.invokeModuleAsync()DOM APIs (properties, methods, events)
RenderingNo visual outputRenders Flutter widgets
Use CasePlatform features, data processingNative-looking UI components

When to use which:

  • Native Plugin: Accessing camera, handling payments, geolocation, file system, background tasks
  • Native UI: Building native-looking buttons, forms, date pickers, navigation bars

When to Create a Native Plugin

Decision Workflow

Step 1: Check if standard web APIs work

  • Can you use fetch(), localStorage, Canvas 2D, etc.?
  • If YES → Use standard web APIs (no plugin needed)

Step 2: Check if an official plugin exists

  • Visit https://openwebf.com/en/native-plugins
  • Search for the capability you need
  • If YES → Use the webf-native-plugins skill to install and use it

Step 3: If no official plugin exists, build your own!

  • ✅ The official plugin registry doesn't have what you need
  • ✅ You need a custom platform-specific capability
  • ✅ You want to wrap an existing Flutter package for WebF
  • ✅ You're building a reusable plugin for your organization

Use Cases:

  • ✅ You need to access platform-specific APIs (camera, sensors, Bluetooth)
  • ✅ You want to wrap an existing Flutter package for WebF use
  • ✅ You need to perform native background tasks
  • ✅ You're building a functional capability (not a UI component)
  • ✅ You want to provide platform features to web developers
  • ✅ Official WebF plugins don't include the feature you need

Don't Create a Native Plugin When:

  • ❌ You're building UI components (use webf-native-ui-dev skill instead)
  • ❌ Standard web APIs already provide the functionality
  • ❌ An official plugin already exists (use webf-native-plugins skill)
  • ❌ You're building a one-off feature (use direct module invocation)

Architecture Overview

A native plugin consists of three layers:

▼
text
复制代码
┌─────────────────────────────────────────┐ │ JavaScript/TypeScript │ ← Generated by CLI │ @openwebf/webf-my-plugin │ │ import { MyPlugin } from '...' │ ├─────────────────────────────────────────┤ │ TypeScript Definitions (.d.ts) │ ← You write this │ interface MyPlugin { ... } │ ├─────────────────────────────────────────┤ │ Dart (Flutter) │ ← You write this │ class MyPluginModule extends ... │ │ webf_my_plugin package │ └─────────────────────────────────────────┘

Development Workflow

Overview

▼
bash
复制代码
# 1. Create Flutter package with Module class # 2. Write TypeScript definition file # 3. Generate npm package with WebF CLI # 4. Test and publish webf module-codegen my-plugin-npm --flutter-package-src=./flutter_package

Step-by-Step Guide

Step 1: Create Flutter Package Structure

Create a standard Flutter package:

▼
bash
复制代码
# Create Flutter package flutter create --template=package webf_my_plugin cd webf_my_plugin

Directory structure:

▼
text
复制代码
webf_my_plugin/ ├── lib/ │ ├── webf_my_plugin.dart # Main export file │ └── src/ │ ├── my_plugin_module.dart # Module implementation │ └── my_plugin.module.d.ts # TypeScript definitions ├── pubspec.yaml └── README.md

pubspec.yaml dependencies:

▼
yaml
复制代码
name: webf_my_plugin description: WebF plugin for [describe functionality] version: 1.0.0 homepage: https://github.com/yourusername/webf_my_plugin environment: sdk: ^3.6.0 flutter: ">=3.0.0" dependencies: flutter: sdk: flutter webf: ^0.24.0 # Add the Flutter package you're wrapping some_flutter_package: ^1.0.0

Step 2: Write the Module Class

Create a Dart class that extends the generated bindings:

Example: lib/src/my_plugin_module.dart

▼
dart
复制代码
import 'dart:async'; import 'package:webf/bridge.dart'; import 'package:webf/module.dart'; import 'package:some_flutter_package/some_flutter_package.dart'; import 'my_plugin_module_bindings_generated.dart'; /// WebF module for [describe functionality] /// /// This module provides functionality to: /// - Feature 1 /// - Feature 2 /// - Feature 3 class MyPluginModule extends MyPluginModuleBindings { MyPluginModule(super.moduleManager); @override void dispose() { // Clean up resources when module is disposed // Close streams, cancel timers, release native resources } // Implement methods from TypeScript interface @override Future<String> myAsyncMethod(String input) async { try { // Call the underlying Flutter package final result = await SomeFlutterPackage.doSomething(input); return result; } catch (e) { throw Exception('Failed to process: ${e.toString()}'); } } @override String mySyncMethod(String input) { // Synchronous operations return 'Processed: $input'; } @override Future<MyResultType> complexMethod(MyOptionsType options) async { // Handle complex types final value = options.someField ?? 'default'; final timeout = options.timeout ?? 5000; try { // Do the work final result = await SomeFlutterPackage.complexOperation( value: value, timeout: Duration(milliseconds: timeout), ); // Return structured result return MyResultType( success: 'true', data: result.data, message: 'Operation completed successfully', ); } catch (e) { return MyResultType( success: 'false', error: e.toString(), message: 'Operation failed', ); } } // Helper methods (not exposed to JavaScript) Future<void> _internalHelper() async { // Internal implementation details } }

Step 3: Write TypeScript Definitions

Create a .d.ts file alongside your Dart file:

Example: lib/src/my_plugin.module.d.ts

▼
typescript
复制代码
/** * Type-safe JavaScript API for the WebF MyPlugin module. * * This interface is used by the WebF CLI (`webf module-codegen`) to generate: * - An npm package wrapper that forwards calls to `webf.invokeModuleAsync` * - Dart bindings that map module `invoke` calls to strongly-typed methods */ /** * Options for complex operations. */ interface MyOptionsType { /** The value to process. */ someField?: string; /** Timeout in milliseconds. */ timeout?: number; /** Enable verbose logging. */ verbose?: boolean; } /** * Result returned from complex operations. */ interface MyResultType { /** "true" on success, "false" on failure. */ success: string; /** Data returned from the operation. */ data?: any; /** Human-readable message. */ message: string; /** Error message if operation failed. */ error?: string; } /** * Public WebF MyPlugin module interface. * * Methods here map 1:1 to the Dart `MyPluginModule` methods. * * Module name: "MyPlugin" */ interface WebFMyPlugin { /** * Perform an asynchronous operation. * * @param input Input string to process. * @returns Promise with processed result. */ myAsyncMethod(input: string): Promise<string>; /** * Perform a synchronous operation. * * @param input Input string to process. * @returns Processed result. */ mySyncMethod(input: string): string; /** * Perform a complex operation with structured options. * * @param options Configuration options. * @returns Promise with operation result. */ complexMethod(options: MyOptionsType): Promise<MyResultType>; }

TypeScript Guidelines:

  • Interface name should match WebF{ModuleName}
  • Use JSDoc comments for documentation
  • Use ? for optional parameters
  • Use Promise<T> for async methods
  • Define separate interfaces for complex types
  • Use string for success/failure flags (for backward compatibility)

Step 4: Create Main Export File

lib/webf_my_plugin.dart:

▼
dart
复制代码
/// WebF MyPlugin module for [describe functionality] /// /// This module provides functionality to: /// - Feature 1 /// - Feature 2 /// - Feature 3 /// /// Example usage: /// ```dart /// // Register module globally (in main function) /// WebF.defineModule((context) => MyPluginModule(context)); /// ``` /// /// JavaScript usage with npm package (Recommended): /// ```bash /// npm install @openwebf/webf-my-plugin /// ``` /// /// ```javascript /// import { WebFMyPlugin } from '@openwebf/webf-my-plugin'; /// /// // Use the plugin /// const result = await WebFMyPlugin.myAsyncMethod('input'); /// console.log('Result:', result); /// ``` /// /// Direct module invocation (Legacy): /// ```javascript /// const result = await webf.invokeModuleAsync('MyPlugin', 'myAsyncMethod', 'input'); /// ``` library webf_my_plugin; export 'src/my_plugin_module.dart';

Step 5: Generate npm Package

Use the WebF CLI to generate the npm package:

▼
bash
复制代码
# Install WebF CLI globally (if not already installed) npm install -g @openwebf/webf-cli # Generate npm package webf module-codegen webf-my-plugin-npm \ --flutter-package-src=./webf_my_plugin \ --module-name=MyPlugin

What the CLI does:

  1. ✅ Parses your .d.ts file
  2. ✅ Generates Dart binding classes (*_bindings_generated.dart)
  3. ✅ Creates npm package with TypeScript types
  4. ✅ Generates JavaScript wrapper that calls webf.invokeModuleAsync
  5. ✅ Creates package.json with correct metadata
  6. ✅ Runs npm run build if a build script exists

Generated output structure:

▼
text
复制代码
webf-my-plugin-npm/ ├── src/ │ ├── index.ts # Main export │ └── my-plugin.ts # Plugin wrapper ├── dist/ # Built files (after npm run build) ├── package.json ├── tsconfig.json └── README.md

Step 6: Test Your Plugin

Test in Flutter App

In your Flutter app's main.dart:

▼
dart
复制代码
import 'package:webf/webf.dart'; import 'package:webf_my_plugin/webf_my_plugin.dart'; void main() { WebFControllerManager.instance.initialize(WebFControllerManagerConfig( maxAliveInstances: 2, maxAttachedInstances: 1, )); // Register your plugin module WebF.defineModule((context) => MyPluginModule(context)); runApp(MyApp()); }

Test in JavaScript/TypeScript

Install and use:

▼
bash
复制代码
npm install @openwebf/webf-my-plugin
▼
typescript
复制代码
import { WebFMyPlugin } from '@openwebf/webf-my-plugin'; async function testPlugin() { try { // Test async method const result = await WebFMyPlugin.myAsyncMethod('test input'); console.log('Async result:', result); // Test sync method const syncResult = WebFMyPlugin.mySyncMethod('test'); console.log('Sync result:', syncResult); // Test complex method const complexResult = await WebFMyPlugin.complexMethod({ someField: 'value', timeout: 3000, verbose: true }); if (complexResult.success === 'true') { console.log('Success:', complexResult.message); } else { console.error('Error:', complexResult.error); } } catch (error) { console.error('Plugin error:', error); } } testPlugin();

Step 7: Publish Your Plugin

Publish Flutter Package

▼
bash
复制代码
# In Flutter package directory flutter pub publish # Or for private packages flutter pub publish --server=https://your-private-registry.com

Publish npm Package

▼
bash
复制代码
# Automatic publishing with CLI webf module-codegen webf-my-plugin-npm \ --flutter-package-src=./webf_my_plugin \ --module-name=MyPlugin \ --publish-to-npm # Or manual publishing cd webf-my-plugin-npm npm publish

For custom npm registry:

▼
bash
复制代码
webf module-codegen webf-my-plugin-npm \ --flutter-package-src=./webf_my_plugin \ --module-name=MyPlugin \ --publish-to-npm \ --npm-registry=https://registry.your-company.com/

Installing and Using Your Custom Plugin

After publishing your plugin, here's how you (or other developers) install and use it:

Installation Process (Same as Official Plugins)

Custom plugins are installed exactly the same way as official WebF plugins. Every plugin requires TWO installations:

Step 1: Install Flutter Package

In your Flutter app's pubspec.yaml:

▼
yaml
复制代码
dependencies: flutter: sdk: flutter webf: ^0.24.0 # Add your custom plugin webf_my_plugin: ^1.0.0 # From pub.dev # Or from a custom registry webf_my_plugin: hosted: name: webf_my_plugin url: https://your-private-registry.com version: ^1.0.0 # Or from a local path during development webf_my_plugin: path: ../webf_my_plugin

Run:

▼
bash
复制代码
flutter pub get

Step 2: Register the Plugin Module

In your Flutter app's main.dart:

▼
dart
复制代码
import 'package:flutter/material.dart'; import 'package:webf/webf.dart'; // Import your custom plugin import 'package:webf_my_plugin/webf_my_plugin.dart'; void main() { // Initialize WebFControllerManager WebFControllerManager.instance.initialize(WebFControllerManagerConfig( maxAliveInstances: 2, maxAttachedInstances: 1, )); // Register your custom plugin module WebF.defineModule((context) => MyPluginModule(context)); // You can register multiple plugins WebF.defineModule((context) => AnotherPluginModule(context)); runApp(MyApp()); } class MyApp extends StatelessWidget { @override Widget build(BuildContext context) { return MaterialApp( home: Scaffold( body: WebF( initialUrl: 'http://192.168.1.100:3000', // Your dev server ), ), ); } }

Step 3: Install npm Package

In your JavaScript/TypeScript project:

▼
bash
复制代码
# Install your custom plugin npm install @openwebf/webf-my-plugin # Or from a custom registry npm install @mycompany/webf-my-plugin --registry=https://registry.company.com # Or from a local path during development npm install ../webf-my-plugin-npm

Usage in JavaScript/TypeScript

Option 1: Using the npm Package (Recommended)

TypeScript/ES6:

▼
typescript
复制代码
import { WebFMyPlugin } from '@openwebf/webf-my-plugin'; async function useMyPlugin() { try { // Call async methods const result = await WebFMyPlugin.myAsyncMethod('input'); console.log('Result:', result); // Call sync methods const syncResult = WebFMyPlugin.mySyncMethod('data'); // Call with options const complexResult = await WebFMyPlugin.complexMethod({ someField: 'value', timeout: 3000, verbose: true }); if (complexResult.success === 'true') { console.log('Success:', complexResult.message); console.log('Data:', complexResult.data); } else { console.error('Error:', complexResult.error); } } catch (error) { console.error('Plugin error:', error); } }

React Example:

▼
tsx
复制代码
import React, { useState, useEffect } from 'react'; import { WebFMyPlugin } from '@openwebf/webf-my-plugin'; function MyComponent() { const [result, setResult] = useState<string | null>(null); const handleButtonClick = async () => { try { const data = await WebFMyPlugin.myAsyncMethod('test'); setResult(data); } catch (error) { console.error('Failed:', error); } }; return ( <div> <button onClick={handleButtonClick}> Use My Plugin </button> {result && <p>Result: {result}</p>} </div> ); }

Vue Example:

▼
vue
复制代码
<template> <div> <button @click="usePlugin">Use My Plugin</button> <p v-if="result">Result: {{ result }}</p> </div> </template> <script setup> import { ref } from 'vue'; import { WebFMyPlugin } from '@openwebf/webf-my-plugin'; const result = ref(null); const usePlugin = async () => { try { result.value = await WebFMyPlugin.myAsyncMethod('test'); } catch (error) { console.error('Failed:', error); } }; </script>

Option 2: Direct Module Invocation (Legacy)

If for some reason the npm package isn't available, you can call the module directly:

▼
javascript
复制代码
// Direct invocation (not type-safe) const result = await webf.invokeModuleAsync( 'MyPlugin', // Module name (must match what you registered) 'myAsyncMethod', // Method name 'input' // Arguments ); // With multiple arguments const complexResult = await webf.invokeModuleAsync( 'MyPlugin', 'complexMethod', { someField: 'value', timeout: 3000, verbose: true } ); // Sync method invocation const syncResult = webf.invokeModuleSync( 'MyPlugin', 'mySyncMethod', 'data' );

Feature Detection

Always check if your plugin is available:

▼
typescript
复制代码
// Check if plugin exists if (typeof WebFMyPlugin !== 'undefined') { // Plugin is available await WebFMyPlugin.myAsyncMethod('test'); } else { // Plugin not registered or npm package not installed console.warn('MyPlugin is not available'); // Provide fallback behavior }

Error Handling

▼
typescript
复制代码
async function safePluginCall() { // Check availability if (typeof WebFMyPlugin === 'undefined') { throw new Error('MyPlugin is not installed'); } try { const result = await WebFMyPlugin.complexMethod({ someField: 'value' }); // Check result status if (result.success === 'true') { return result.data; } else { throw new Error(result.error || 'Unknown error'); } } catch (error) { console.error('Plugin call failed:', error); throw error; } }

Development Workflow

During Plugin Development

▼
bash
复制代码
# Terminal 1: Flutter app cd my-flutter-app # Use local path in pubspec.yaml flutter run # Terminal 2: Web project cd my-web-project # Install local npm package npm install ../webf-my-plugin-npm npm run dev

After Publishing

▼
bash
复制代码
# Update to published versions cd my-flutter-app # Update pubspec.yaml to use pub.dev version flutter pub get flutter run cd my-web-project # Install from npm npm install @openwebf/webf-my-plugin npm run dev

Distribution Options

Public Distribution

Flutter Package:

  • Publish to pub.dev (free, public)
  • Anyone can install with webf_my_plugin: ^1.0.0

npm Package:

  • Publish to npmjs.com (free, public)
  • Anyone can install with npm install @openwebf/webf-my-plugin

Private Distribution

Flutter Package:

▼
yaml
复制代码
# Install from private registry dependencies: webf_my_plugin: hosted: name: webf_my_plugin url: https://your-company-flutter-registry.com version: ^1.0.0 # Or from Git repository dependencies: webf_my_plugin: git: url: https://github.com/yourcompany/webf_my_plugin.git ref: v1.0.0

npm Package:

▼
bash
复制代码
# Install from private registry npm install @yourcompany/webf-my-plugin --registry=https://registry.company.com # Or configure .npmrc echo "@yourcompany:registry=https://registry.company.com" >> .npmrc npm install @yourcompany/webf-my-plugin

Local Development

Flutter Package:

▼
yaml
复制代码
dependencies: webf_my_plugin: path: ../webf_my_plugin # Relative path

npm Package:

▼
bash
复制代码
npm install ../webf-my-plugin-npm # Or use npm link cd ../webf-my-plugin-npm npm link cd my-web-project npm link @openwebf/webf-my-plugin

Complete Installation Example

Scenario: You've built a camera plugin and want to use it in your app.

1. Flutter side (main.dart):

▼
dart
复制代码
import 'package:webf/webf.dart'; import 'package:webf_camera/webf_camera.dart'; // Your plugin void main() { WebFControllerManager.instance.initialize(WebFControllerManagerConfig( maxAliveInstances: 2, maxAttachedInstances: 1, )); // Register your camera plugin WebF.defineModule((context) => CameraModule(context)); runApp(MyApp()); }

2. JavaScript side (app.tsx):

▼
typescript
复制代码
import { WebFCamera } from '@openwebf/webf-camera'; function CameraApp() { const [cameras, setCameras] = useState([]); useEffect(() => { async function loadCameras() { // Check if plugin is available if (typeof WebFCamera === 'undefined') { console.error('Camera plugin not installed'); return; } try { const result = await WebFCamera.getCameras(); if (result.success === 'true') { setCameras(JSON.parse(result.cameras)); } } catch (error) { console.error('Failed to load cameras:', error); } } loadCameras(); }, []); const capturePhoto = async () => { try { const photoPath = await WebFCamera.capturePhoto(cameras[0].id); console.log('Photo saved to:', photoPath); } catch (error) { console.error('Failed to capture:', error); } }; return ( <div> <h1>Camera App</h1> <button onClick={capturePhoto}>Capture Photo</button> <ul> {cameras.map(cam => ( <li key={cam.id}>{cam.name}</li> ))} </ul> </div> ); }

Common Plugin Patterns

1. Wrapping Existing Flutter Packages

Example: Wrapping a camera package

▼
dart
复制代码
import 'package:camera/camera.dart'; class CameraPluginModule extends CameraPluginModuleBindings { CameraPluginModule(super.moduleManager); List<CameraDescription>? _cameras; @override Future<CameraListResult> getCameras() async { try { _cameras = await availableCameras(); final cameraList = _cameras!.map((cam) => { 'id': cam.name, 'name': cam.name, 'facing': cam.lensDirection.toString(), }).toList(); return CameraListResult( success: 'true', cameras: jsonEncode(cameraList), ); } catch (e) { return CameraListResult( success: 'false', error: e.toString(), ); } } @override Future<String> capturePhoto(String cameraId) async { // Implementation for capturing photos // Return file path or base64 data } }

2. Handling Binary Data

▼
dart
复制代码
@override Future<bool> processImageData(NativeByteData imageData) async { try { // Access raw bytes final bytes = imageData.bytes; // Process the data await SomeFlutterPackage.processImage(bytes); return true; } catch (e) { return false; } }

TypeScript:

▼
typescript
复制代码
interface WebFMyPlugin { processImageData(imageData: ArrayBuffer | Uint8Array): Promise<boolean>; }

3. Event Streams

For continuous data streams (sensors, location updates):

▼
dart
复制代码
class SensorPluginModule extends SensorPluginModuleBindings { StreamSubscription? _subscription; @override Future<void> startListening(String sensorType) async { _subscription = SensorPackage.stream.listen((data) { // Send events to JavaScript moduleManager.emitModuleEvent( 'SensorPlugin', 'data', {'value': data.value, 'timestamp': data.timestamp.toString()}, ); }); } @override Future<void> stopListening() async { await _subscription?.cancel(); _subscription = null; } @override void dispose() { _subscription?.cancel(); super.dispose(); } }

JavaScript:

▼
typescript
复制代码
// Listen for events webf.on('SensorPlugin:data', (event) => { console.log('Sensor data:', event.detail); }); await WebFSensorPlugin.startListening('accelerometer');

4. Permission Handling

▼
dart
复制代码
import 'package:permission_handler/permission_handler.dart'; class PermissionPluginModule extends PermissionPluginModuleBindings { @override Future<PermissionResult> requestPermission(String permissionType) async { Permission permission; switch (permissionType) { case 'camera': permission = Permission.camera; break; case 'microphone': permission = Permission.microphone; break; default: return PermissionResult( granted: 'false', message: 'Unknown permission type', ); } final status = await permission.request(); return PermissionResult( granted: status.isGranted ? 'true' : 'false', status: status.toString(), message: _getPermissionMessage(status), ); } String _getPermissionMessage(PermissionStatus status) { switch (status) { case PermissionStatus.granted: return 'Permission granted'; case PermissionStatus.denied: return 'Permission denied'; case PermissionStatus.permanentlyDenied: return 'Permission permanently denied. Please enable in settings.'; default: return 'Unknown permission status'; } } }

5. Platform-Specific Implementation

▼
dart
复制代码
import 'dart:io'; class PlatformPluginModule extends PlatformPluginModuleBindings { @override Future<PlatformInfoResult> getPlatformInfo() async { String platformName; String platformVersion; if (Platform.isAndroid) { platformName = 'Android'; // Get Android version } else if (Platform.isIOS) { platformName = 'iOS'; // Get iOS version } else if (Platform.isMacOS) { platformName = 'macOS'; } else { platformName = 'Unknown'; } return PlatformInfoResult( platform: platformName, version: platformVersion, isAndroid: Platform.isAndroid, isIOS: Platform.isIOS, ); } }

Advanced Patterns

1. Error Handling and Validation

▼
dart
复制代码
@override Future<OperationResult> performOperation(OperationOptions options) async { // Validate input if (options.value == null || options.value!.isEmpty) { return OperationResult( success: 'false', error: 'InvalidInput', message: 'Value cannot be empty', ); } if (options.timeout != null && options.timeout! < 0) { return OperationResult( success: 'false', error: 'InvalidTimeout', message: 'Timeout must be positive', ); } try { // Perform operation with timeout final result = await Future.timeout( _doOperation(options.value!), Duration(milliseconds: options.timeout ?? 5000), onTimeout: () => throw TimeoutException('Operation timed out'), ); return OperationResult( success: 'true', data: result, message: 'Operation completed', ); } on TimeoutException catch (e) { return OperationResult( success: 'false', error: 'Timeout', message: e.message ?? 'Operation timed out', ); } catch (e) { return OperationResult( success: 'false', error: 'UnknownError', message: e.toString(), ); } }

2. Resource Management

▼
dart
复制代码
class ResourcePluginModule extends ResourcePluginModuleBindings { final Map<String, Resource> _activeResources = {}; @override Future<String> createResource(ResourceOptions options) async { final id = DateTime.now().millisecondsSinceEpoch.toString(); final resource = Resource(options); await resource.initialize(); _activeResources[id] = resource; return id; } @override Future<void> releaseResource(String resourceId) async { final resource = _activeResources.remove(resourceId); await resource?.dispose(); } @override void dispose() { // Clean up all resources for (final resource in _activeResources.values) { resource.dispose(); } _activeResources.clear(); super.dispose(); } }

3. Batching Operations

▼
dart
复制代码
@override Future<BatchResult> batchProcess(String itemsJson) async { final List<dynamic> items = jsonDecode(itemsJson); final results = <String, dynamic>{}; final errors = <String, String>{}; await Future.wait( items.asMap().entries.map((entry) async { final index = entry.key; final item = entry.value; try { final result = await _processItem(item); results[index.toString()] = result; } catch (e) { errors[index.toString()] = e.toString(); } }), ); return BatchResult( success: errors.isEmpty ? 'true' : 'false', results: jsonEncode(results), errors: errors.isEmpty ? null : jsonEncode(errors), processedCount: results.length, totalCount: items.length, ); }

CLI Command Reference

Basic Generation

▼
bash
复制代码
# Generate npm package for a module webf module-codegen output-dir \ --flutter-package-src=./my_package \ --module-name=MyModule # Specify custom package name webf module-codegen output-dir \ --flutter-package-src=./my_package \ --module-name=MyModule \ --package-name=@mycompany/my-plugin

Auto-Publishing

▼
bash
复制代码
# Publish to npm after generation webf module-codegen output-dir \ --flutter-package-src=./my_package \ --module-name=MyModule \ --publish-to-npm # Publish to custom registry webf module-codegen output-dir \ --flutter-package-src=./my_package \ --module-name=MyModule \ --publish-to-npm \ --npm-registry=https://registry.company.com/

Best Practices

1. Naming Conventions

  • Flutter package: webf_{feature} (e.g., webf_share, webf_camera)
  • Module class: {Feature}Module (e.g., ShareModule, CameraModule)
  • Module name: Same as class without "Module" (e.g., "Share", "Camera")
  • npm package: @openwebf/webf-{feature} or @yourscope/webf-{feature}

2. Error Handling

▼
dart
复制代码
// Always return structured error information return ResultType( success: 'false', error: 'ErrorCode', // Machine-readable error code message: 'Human-readable error message', ); // Never throw exceptions to JavaScript // Catch and convert to result objects

3. Documentation

▼
dart
复制代码
/// Brief one-line description. /// /// Detailed explanation of what this method does. /// /// Parameters: /// - [param1]: Description of first parameter /// - [param2]: Description of second parameter /// /// Returns a [ResultType] with: /// - `success`: "true" on success, "false" on failure /// - `data`: The actual result data /// - `error`: Error message if failed /// /// Throws: /// - Never throws to JavaScript. Returns error in result object. /// /// Example: /// ```dart /// final result = await module.myMethod('input'); /// if (result.success == 'true') { /// print('Success: ${result.data}'); /// } /// ``` @override Future<ResultType> myMethod(String param1, int? param2) async { // Implementation }

4. Type Safety

▼
typescript
复制代码
// Use interfaces for complex types interface MyOptions { value: string; timeout?: number; retries?: number; } // Use specific result types interface MyResult { success: string; data?: any; error?: string; } // Avoid 'any' when possible // Use union types for enums type Platform = 'ios' | 'android' | 'macos' | 'windows' | 'linux';

5. Testing

▼
dart
复制代码
// Create tests for your module import 'package:flutter_test/flutter_test.dart'; import 'package:webf_my_plugin/webf_my_plugin.dart'; void main() { group('MyPluginModule', () { late MyPluginModule module; setUp(() { module = MyPluginModule(mockModuleManager); }); tearDown(() { module.dispose(); }); test('myAsyncMethod returns correct result', () async { final result = await module.myAsyncMethod('test'); expect(result, 'Processed: test'); }); test('handles errors gracefully', () async { final result = await module.complexMethod(MyOptionsType( someField: 'invalid', )); expect(result.success, 'false'); expect(result.error, isNotNull); }); }); }

Troubleshooting

Issue: Bindings file not found

Error: Error: Could not find 'my_plugin_module_bindings_generated.dart'

Solution:

  1. Make sure you've run the CLI code generation
  2. Check that .module.d.ts file exists in the same directory
  3. Verify the module interface is properly named (WebF{ModuleName})
  4. Run webf module-codegen again

Issue: Module not found in JavaScript

Error: Module 'MyPlugin' not found

Solution:

  1. Check that the Flutter package is in pubspec.yaml
  2. Verify the module is registered with WebF.defineModule() in main.dart
  3. Ensure module name matches exactly (case-sensitive)
  4. Run flutter pub get and rebuild the app

Issue: Method not working

Cause: Method name mismatch or incorrect parameters

Solution:

  1. Check method name matches between TypeScript and Dart
  2. Verify parameter types match
  3. Check async vs sync (Promise vs direct return)
  4. Look at console errors for details

Issue: TypeScript types not working

Cause: npm package not generated correctly

Solution:

▼
bash
复制代码
# Regenerate with CLI webf module-codegen output-dir \ --flutter-package-src=./my_package \ --module-name=MyModule # Check package.json exports cd output-dir cat package.json # Should have "types": "./dist/index.d.ts"

Real-World Example: Share Plugin

See the complete implementation in the WebF repository at native_plugins/share for:

  • Module implementation (share_module.dart)
  • TypeScript definitions (share.module.d.ts)
  • Error handling and platform-specific code
  • Binary data handling
  • Result types with detailed information

Resources

  • CLI Development Guide: cli/CLAUDE.md
  • Module System Docs: webf/lib/src/module/
  • Example Plugin: native_plugins/share
  • WebF Architecture: docs/ARCHITECTURE.md
  • Official Documentation: https://openwebf.com/en/docs/developer-guide/native-plugins

Related Skills

  • Using Plugins: See webf-native-plugins skill for how to use existing plugins
  • Native UI Development: See webf-native-ui-dev skill for creating UI components
  • CLI Usage: See CLI documentation for code generation details

Summary

Creating Plugins

  • ✅ Native plugins expose Flutter/platform capabilities as JavaScript APIs
  • ✅ Different from Native UI (functional vs visual)
  • ✅ Write Dart Module class extending generated bindings
  • ✅ Write TypeScript definitions (.d.ts) for each module
  • ✅ Use WebF CLI (webf module-codegen) to generate npm packages and Dart bindings
  • ✅ Test in both Flutter and JavaScript environments
  • ✅ Publish to pub.dev (Flutter) and npm (JavaScript)

Installing and Using Plugins

  • ✅ Custom plugins are installed exactly like official plugins
  • ✅ Requires TWO installations: Flutter package + npm package
  • ✅ Add to pubspec.yaml and run flutter pub get
  • ✅ Register with WebF.defineModule() in Flutter app's main.dart
  • ✅ Install npm package: npm install @openwebf/webf-my-plugin
  • ✅ Import and use in JavaScript: import { WebFMyPlugin } from '@openwebf/webf-my-plugin'
  • ✅ Always check availability: if (typeof WebFMyPlugin !== 'undefined')
  • ✅ Supports public (pub.dev/npm), private registries, and local paths

Best Practices

  • ✅ Follow the Share plugin example at native_plugins/share
  • ✅ Return structured results (never throw to JavaScript)
  • ✅ Use TypeScript for type safety
  • ✅ Handle errors gracefully with success/error flags
  • ✅ Document thoroughly with JSDoc comments
区块链
效率工具
软件开发

快捷安装

复制到终端去安装 Skill

npxskillsaddopenwebf/webf--skill"webf-native-plugin-dev"
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
🔥热门工具
朱雀AI检测朱雀AI检测
朱雀AI检测助手朱雀AI检测助手
LovartLovart
老鱼简历老鱼简历
WritePass官网WritePass官网
面多多面多多
CursorCursor
星月写作星月写作
朱雀AI检测助手朱雀AI检测助手
零感AI零感AI
Skills 推荐
debug
debug 是一个系统化定位软件缺陷根因的技能,适用于用户报告 'fix'、'broken'、'error' 等问题或测试意外失败时。它通过可验证的假设、最小复现、因果链分析和回归测试,确保在修复前准确定位根本原因。
retrieving-developer-knowledge
retrieving-developer-knowledge 用于搜索、获取和整合 Google 官方开发者文档,覆盖 Google Cloud、AI/Gemini、Android、Chrome、Web、Flutter、Go、Firebase 等平台,适用于查询 gcloud CLI 命令、API 语法、IAM 权限或架构对比等场景。
diff-intake
diff-intake 读取 PR 或分支差异,生成结构化 YAML 变更摘要,用于下游 analytics instrumentation 技能。适用于用户提交 PR 链接、分支对比或原始 diff 后需理解变更内容、评估分析覆盖或启动埋点流程的场景。
webapp-testing
提供本地 Web 应用的端到端测试能力,支持页面导航、元素交互、表单填写、动态等待、断言验证、截图捕获、浏览器日志收集及网络请求拦截,适用于前端功能验证与 UI 行为调试。
definition-of-done-generator
自动生成项目完成标准的规范定义与配置文件,提供符合企业级工作流要求的最佳实践指导,输出可直接投入生产环境的代码和验证结果,适用于需要标准化流程审批、合规审查及跨系统集成的复杂项目管理场景。