# WebF 原生 UI 开发想要通过包装 Flutter 小部件来为 WebF 创建自己的本机 UI 库吗？这项技能将指导您完成构建自定义原生 UI 库的完整过程，这些库使 Flutter 小部件可以通过 JavaScript/TypeScript 访问，并支持 React 和 Vue。 ## 什么是原生 UI 开发？ WebF 中的本机 UI 开发意味着： * **将 Flutter 小部件**包装为 WebF 自定义元素 * **将原生 Flutter UI** 与 Web 技术 (HTML/JavaScript) 连接起来 * **创建可与 React、Vue 和 vanilla JavaScript 配合使用的可重用组件库** * **使用类型安全的 TypeScript 定义发布 npm 包** ## 何时创建原生 UI 库 ### 用例： * ✅ 您想要向 Web 开发人员公开 Flutter 小部件 * ✅ 需要封装一个Flutter包以供WebF使用 * ✅ 您正在构建具有本机性能的设计系统 * ✅ 您想要创建特定于平台的组件（iOS、Android 等） * ✅ 您需要超出 HTML/CSS 功能的自定义小部件 ### 在以下情况下不要创建本机 UI 库： * ❌ HTML/CSS 可以达到相同的结果（使用标准网页） * ❌ 只需使用现有的 UI 库即可（参见 `webf-native-ui` 技巧） * ❌ 您正在构建一个一次性组件（直接使用 WebF 小部件元素） ## 架构概述本机 UI 库由三层组成： ┌──────────────────────────────────────────┐ │ JavaScript/TypeScript (React/Vue) │ ← 由 CLI 生成 │ @openwebf/my-component-lib │ ├──────────────────────────────────────────┤ │ TypeScript 定义 (.d.ts) │ ← 你写这个 │ 组件接口和事件 │ ├──────────────────────────────────────────┤ │ Dart (Flutter) │ ← 你写这个 │ Flutter 小部件包装器 │ │ my_component_lib 包 │ └──────────────────────────────────────────┘ ## 开发工作流程 ### 概述 # 1. 使用 Dart 包装器创建 Flutter 包 # 2. 编写 TypeScript 定义文件 # 3. 使用 WebF CLI 生成 React/Vue 组件 # 4. 测试并发布 webf codegen my-ui-lib --flutter-package-src=./flutter_package ## 分步指南 ### 第 1 步：创建 Flutter 包结构创建标准Flutter包： # 创建 Flutter 包 flutter create --template=package my_component_lib cd my_component_lib **目录结构：** 我的组件库/ ├── 库/ │ ├── my_component_lib.dart # 主导出文件 │ └── src/ │ ├── button.dart # Dart 小部件包装器 │ ├── button.d.ts # TypeScript 定义 │ ├── 输入.dart │ └── 输入.d.ts ├── pubspec.yaml └── 自述文件.md **pubspec.yaml 依赖项：** 依赖项：颤振： sdk：颤动 webf: ^0.24.0 # 最新的 WebF 版本 ### 步骤 2：编写 Dart Widget 包装器创建一个包装 Flutter 小部件的 Dart 类： **示例：lib/src/button.dart** 导入'包：flutter/widgets.dart'; 导入'包：webf/webf.dart'；导入“button_bindings_ generated.dart”； // 将由 CLI 生成 /// 自定义按钮组件包装Flutter widget 类 MyCustomButton 扩展 MyCustomButtonBindings { MyCustomButton(super.context); // 内部状态字符串_variant = '填充'; 布尔_disabled = false； // 属性 getters/setters（通过绑定实现接口） @覆盖字符串获取变体 => _variant; @覆盖设置变体（字符串值）{ _variant = 值； // 当属性改变时触发重建设置状态（（）{}）； } @覆盖 bool 被禁用 => _disabled; @覆盖设置禁用（布尔值）{ _禁用=值；设置状态（（）{}）； } @覆盖 WebFWidgetElementState createState() { 返回 MyCustomButtonState(this); } } 类 MyCustomButtonState 扩展 WebFWidgetElementState { MyCustomButtonState(super.widgetElement); @覆盖 MyCustomButton get widgetElement => super.widgetElement as MyCustomButton; @覆盖小部件构建（BuildContext上下文）{ 返回手势检测器（ onTap: widgetElement.disabled ？空：() { // 将点击事件发送给 JavaScript widgetElement.dispatchEvent(Event('click')); }, 子项：容器（填充：EdgeInsets.all(12), 装饰：BoxDecoration( 颜色：_getBackgroundColor(), borderRadius: BorderRadius.circular(8), ), 孩子：文本（ // 从子节点获取文本 widgetElement.getTextContent() ?? '按钮', 样式：文本样式（颜色：widgetElement.disabled？颜色.灰色：颜色.白色， ), ), ), ）； } 颜色_getBackgroundColor() { if (widgetElement.disabled) 返回 Colors.grey[400]!; 开关 (widgetElement.variant) { 案例“已满”：返回 Colors.blue；案例“概述”：返回 Colors.transparent; 默认：返回 Colors.blue； } } } ### 步骤 3：编写 TypeScript 定义在 Dart 文件旁边创建一个 `.d.ts` 文件： **示例：lib/src/button.d.ts** /** * 具有多种变体的自定义按钮组件。 */ /** * <我的自定义按钮> 的属性。 */ 接口 MyCustomButtonProperties { /** * 按钮变体样式。 * 支持的值：“已填充”| '概述' | '文本' * @default '已填充' */ 变体？：字符串； /** * 按钮是否禁用。 * @默认假 */ 禁用？：布尔值； } /** * <我的自定义按钮> 的事件。 */ 接口 MyCustomButtonEvents { /** * 单击按钮时触发。 */ 点击：活动； } **TypeScript 指南：** * 接口名称必须以“Properties”或“Events”结尾 * 使用 `?` 作为可选属性（布尔值除外，在 Dart 中布尔值始终不可为空） * 对带有数据的事件使用 `CustomEvent` * 为文档添加 JSDoc 注释 * 更多详情请参见【TypeScript定义指南】() ### 步骤 4：创建主导出文件 **lib/my_component_lib.dart：** 库 my_component_lib；导入'包：webf/webf.dart'；导入'src/button.dart'; 导出'src/button.dart'; /// 安装该库中的所有组件无效 installMyComponentLib() { // 注册自定义元素 WebFController.defineCustomElement( '我的自定义按钮', （上下文）=> MyCustomButton（上下文），）； // 在这里添加更多组件 // WebFController.defineCustomElement('my-custom-input', ...); } ### 步骤 5：生成 React/Vue 组件使用 WebF CLI 生成 JavaScript/TypeScript 组件： # 全局安装 WebF CLI（如果尚未安装） npm install -g @openwebf/webf-cli # 生成 TypeScript 绑定和 React/Vue 组件 webf codegen my-ui-lib-react \ --flutter-package-src=./my_component_lib \ --框架=反应 webf codegen my-ui-lib-vue \ --flutter-package-src=./my_component_lib \ --框架=vue **CLI 的作用：** 1. ✅ 解析你的`.d.ts`文件 2. ✅ 生成 Dart 绑定类（`*_bindings_ generated.dart`） 3. ✅ 使用正确的 TypeScript 类型创建 React 组件 4. ✅ 创建支持 TypeScript 的 Vue 组件 5. ✅ 将 `.d.ts` 文件复制到输出目录 6. ✅ 使用正确的元数据创建 `package.json` 7. ✅ 如果构建脚本存在则运行 `npm run build` **生成的输出结构：** 我的-ui-lib-react/ ├── src/ │ ├── MyCustomButton.tsx # React 组件 │ └── index.ts # 主要导出 ├── dist/ # 构建文件（npm run build 之后） ├── package.json ├── tsconfig.json └── 自述文件.md ### 第 6 步：测试您的组件 #### 在 Flutter 应用程序中测试 **在 Flutter 应用程序的 main.dart 中：** 导入'包：my_component_lib / my_component_lib.dart'；无效主（）{ WebFControllerManager.instance.initialize(WebFControllerManagerConfig( 最大活动实例数：2，最大附加实例数：1，））； // 安装你的组件库安装MyComponentLib(); runApp(MyApp()); } #### 在 JavaScript/TypeScript 中测试 **反应示例：** 从'@openwebf/my-ui-lib-react'导入{MyCustomButton}；函数应用程序（）{ 返回（

<我的自定义按钮变体=“填充” onClick={() => console.log('点击了！')} > 点我

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

<我的自定义按钮变体=“填充” @click="handleClick" > 点我

<脚本设置> 从 '@openwebf/my-ui-lib-vue' 导入 { MyCustomButton }； const handleClick = () => { console.log('点击了！'); }; ### 第 7 步：发布您的库 #### 发布 Flutter 包 # 在Flutter包目录下颤动酒吧发布 # 或者对于私人包 flutter pub 发布 --server=https://your-private-registry.com #### 发布 npm 包 # 使用 CLI 自动发布 webf codegen my-ui-lib-react \ --flutter-package-src=./my_component_lib \ --framework=反应 \ --发布到 npm # 或者手动发布 cd my-ui-lib-react npm 发布 **对于自定义 npm 注册表：** webf codegen my-ui-lib-react \ --flutter-package-src=./my_component_lib \ --framework=反应 \ --发布到 npm \ --npm-registry=https://registry.your-company.com/ ## 高级模式 ### 1\.处理复杂的属性 **打字稿：** 接口 MyComplexWidgetProperties { // 复杂数据的 JSON 字符串属性项目？：字符串； // 在 Dart 中将是 JSON.parse() // 类似枚举的值对齐方式？： '左' | '中心' | '正确的'; // 数字属性最大长度？：数字；不透明度？：数字； } **飞镖：** @覆盖设置项目（字符串？值）{ 如果（值！= null）{ 尝试{ 最终列表已解析 = jsonDecode(value); _items = parsed.cast>(); 设置状态（（）{}）； } 捕获 (e) { print('解析项目时出错：$e'); } } } ### 2\.使用数据调度自定义事件 **飞镖：** void _handleValueChange(String newValue) { // 使用数据调度 CustomEvent widgetElement.dispatchEvent(自定义事件( ‘改变’，详细信息：{'value'：newValue}，））； } **打字稿：** 接口 MyInputEvents { 更改：CustomEvent<{值：字符串}>； } ### 3\.从 JavaScript 调用方法 **打字稿：** 接口我的输入属性{ // 常规属性值？：字符串； // 方法焦点（）：无效；清除（）：无效； } **飞镖：** 类 MyInput 扩展 MyInputBindings { 最终 FocusNode _focusNode = FocusNode(); @覆盖无效焦点（）{ _focusNode.requestFocus(); } @覆盖无效清除（）{ // 清除输入值=''； // 调度事件调度事件(事件('输入')); } } ### 4\.读取 CSS 样式 **飞镖：** @覆盖小部件构建（BuildContext上下文）{ // 读取 CSS 属性最终 renderStyle = widgetElement.renderStyle; 最终背景颜色 = renderStyle.backgroundColor?.value; 最终 borderRadius = renderStyle.borderRadius; 返回容器（装饰：BoxDecoration( 颜色：背景颜色？？颜色.蓝色, borderRadius: BorderRadius.circular( borderRadius?.topLeft?.x ?? 8.0 ), ), 孩子：buildChild(), ）； } ### 5\.处理子元素 **飞镖：** @覆盖小部件构建（BuildContext上下文）{ // 获取子节点的文本内容最终文本 = widgetElement.getTextContent() ?? ''; // 构建子部件最终的孩子 = widgetElement.children.map((child) { 返回child.renderObject？.widget ??大小框(); }).toList(); 返回列（儿童：儿童，）； } ## 常见模式和最佳实践 ### 1\.属性验证 @覆盖设置变体（字符串值）{ const validVariants = ['填充', '轮廓', '文本']; if (validVariants.contains(value)) { _variant = 值； } 否则{ print('警告：无效变体“$value”'); _variant = '填充'; } 设置状态（（）{}）； } ### 2\.消除频繁更新计时器？ _debounceTimer； @覆盖设置 searchQuery(字符串值) { _searchQuery = 值； // 去抖动搜索 _debounceTimer?.cancel(); _debounceTimer = 计时器(持续时间(毫秒: 300), () { _performSearch(); }); } ### 3\.生命周期管理 @覆盖无效didMount（）{ super.didMount(); // 当元素插入 DOM 时调用 _initializeWidget(); } @覆盖无效处置（）{ // 清理资源 _debounceTimer?.cancel(); _focusNode.dispose(); 超级.dispose(); } ### 4\.错误处理 @覆盖设置 jsonData(字符串？值) { if (value == null || value.isEmpty) { _数据=空；返回; } 尝试{ _data = jsonDecode(值); 设置状态（（）{}）； } 捕获 (e) { print('解析 JSON 时出错：$e'); // 发送错误事件 dispatchEvent(CustomEvent('error', 详细信息: {'message': e.toString()})); } } ## CLI 命令参考 ### 基本生成 # 生成React组件 webf codegen 输出目录 --flutter-package-src=./my_package --framework=react # 生成Vue组件 webf codegen 输出目录 --flutter-package-src=./my_package --framework=vue # 指定包名 webf codegen 输出目录 \ --flutter-package-src=./my_package \ --framework=反应 \ --package-name=@mycompany/my-ui-lib ### 自动发布 # 生成后发布到npm webf codegen 输出目录 \ --flutter-package-src=./my_package \ --framework=反应 \ --发布到 npm # 发布到自定义注册表 webf codegen 输出目录 \ --flutter-package-src=./my_package \ --framework=反应 \ --发布到 npm \ --npm-registry=https://registry.company.com/ ### 项目自动创建如果文件丢失，CLI 会自动创建项目： * 如果缺少 `package.json`、`tsconfig.json` 或 `global.d.ts`，则会创建一个新项目 * 如果不指定framework，则交互提示 * 如果项目已存在，则使用现有配置 ## 故障排除 ### 问题：找不到绑定文件 **错误：** `错误：找不到'button_bindings_ generated.dart'` **解决方案：** 1. 确保您已运行 CLI 代码生成 2. 检查`.d.ts`文件是否与`.dart`文件位于同一目录中 3. 验证接口命名（必须以“Properties”或“Events”结尾） ### 问题：UI 中的属性未更新 **原因：** 属性更改后未调用 `setState()` **解决方案：** @覆盖设置 myProperty(字符串值) { _myProperty = 值；设置状态（（）{}）； // ← 别忘了这一点！ } ### 问题：JavaScript 中未触发事件 **原因：** 事件名称不匹配或未调度事件 **解决方案：** // 确保事件名称与您的 TypeScript 定义匹配 widgetElement.dispatchEvent(Event('click')); // 匹配 TypeScript 中的“click” ### 问题：TypeScript 类型不起作用 **原因：** 生成的类型未正确导出 **解决方案：** 检查生成的 `package.json` 导出类型： { “类型”：“./dist/index.d.ts”， “出口”：{ “。”：{ “类型”：“./dist/index.d.ts”， “导入”：“./dist/index.js” } } } ## 完整示例：文本输入组件有关文本输入组件的完整实现，请参阅[完整示例]()： * Flutter TextFormField 包装器 * TypeScript 定义 * 事件处理 * 验证 * 方法（聚焦、模糊、清晰） * CSS 集成 ## 资源 * **CLI 开发指南** : [cli/CLAUDE.md]() * **TypeScript 指南** ：[CLI TYPING_GUIDE.md]() * **示例包**：[native_uis/webf_cupertino_ui]() * **WebF 架构** : [docs/ARCHITECTURE.md]() * **官方文档**： ## 后续步骤创建本机 UI 库后： 1. **在所有目标平台（iOS、Android、桌面）上进行彻底测试** 2. **为每个组件编写文档**（请参阅 webf_cupertino_ui 中现有的 `.md` 文件） 3. **创建示例应用程序** 演示用法 4. **发布到 pub.dev** (Flutter) 和 npm (JavaScript) 5. **保持与WebF版本更新的兼容性** ## 总结 * ✅ 原生 UI 库将 Flutter 小部件包装为可通过 Web 访问的自定义元素 * ✅ 编写扩展 WebFWidgetElement 的 Dart 包装器 * ✅ 为每个组件编写 TypeScript 定义 (.d.ts) * ✅ 使用WebF CLI生成React/Vue组件 * ✅ 在 Flutter 和 JavaScript 环境中进行测试 * ✅ 发布到 pub.dev (Flutter) 和 npm (JavaScript) * ✅ 遵循 webf_cupertino_ui 中的现有模式以供参考

Webf 原生 Ui 开发

包含技能