Flipper Zero JavaScript 应用脚手架使用 create-fz-app 快速创建与运行 JS App【免费下载链接】flipperzero-firmwareFlipper Zero firmware source code项目地址: https://gitcode.com/GitHub_Trending/fl/flipperzero-firmware导读本指南围绕 Flipper Zero 官方 JavaScript SDK 的脚手架工具flipperdevices/create-fz-app展开介绍如何在本地用一条命令交互式生成一个完整的 JS 应用工程、通过npm start一键完成编译、上传与在真机上运行。读完本文你将掌握 Flipper Zero JS App 从空目录到屏幕弹出 Hello 对话框的完整开发闭环并理解脚手架背后的模板结构、fz-sdk.config.json5配置语义以及 SDK 的构建与串口上传原理。一、脚手架工具是什么create-fz-app是 Flipper Zero 官方发布在 npm 上的交互式脚手架包包名flipperdevices/create-fz-app用于在本地生成一个可运行的 JavaScript 应用工程目标运行环境是 Flipper Zero 设备内置的 JS 解释器mjs。该包与flipperdevices/fz-sdk官方类型声明与构建/上传工具链配套使用两者的源码均位于本仓库的 applications/system/js_app/packages/ 目录下。从源码看脚手架的核心逻辑非常轻量create-fz-app/index.js通过prompts交互式收集用户输入然后把内置的template/模板目录复制到目标文件夹用项目名替换模板中的app_name占位符最后调用所选包管理器执行依赖安装。包本身依赖极少仅prompts与replace-in-file见 package.json这意味着它只负责生成工程真正的编译与上传由模板中引入的fz-sdk完成。二、快速开始三分钟创建并运行第一个应用2.1 创建工程在任意空目录下执行官方推荐命令npx flipperdevices/create-fz-applatestnpx会自动从 npm 拉取最新版脚手架并启动交互式向导期间会依次询问三个问题项目名称默认my-flip-app生成后即作为目录名包管理器选择npm/pnpm/yarn三选一确认创建默认确认。确认后工具会复制模板文件、将模板内所有app_name占位符替换为你的项目名对应源码中的replaceInFileSync({ files:${name}/**/*, from: /app_name/g, to: name })然后自动执行pnpm install/npm install/yarn install安装依赖。若目标目录已存在同名文件或目录向导会额外询问是否继续覆盖源码中通过fs.rmSync(name, { recursive: true, force: true })实现删除重建因此请谨慎操作。2.2 运行到 Flipper Zero进入生成的项目目录并启动cd my-flip-app npm start如果你在创建时选择了pnpm或yarn完全可以使用pnpm start/yarn start代替npm start三个包管理器对工具链完全等价。npm start实际执行的是模板 package.json 中定义的两步流水线build: tsc node node_modules/flipperdevices/fz-sdk/sdk.js build, start: npm run build node node_modules/flipperdevices/fz-sdk/sdk.js upload即先用 TypeScript 编译器检查并产出 JS再调用fz-sdk的build命令打包最后用upload命令把产物通过串口写入 Flipper Zero 并立即运行。2.3 运行前提需要 Node.js 环境脚手架与 SDK 均为 Node 工具链Flipper Zero 需通过 USB 连接到电脑并处于命令行模式CLI 会话以便upload通过串口交互首次使用时会通过串口在设备上创建/ext/apps/Scripts/目录存放脚本详见下文配置与上传原理。三、生成的工程模板剖析脚手架内置的模板文件位于仓库的 applications/system/js_app/packages/create-fz-app/template/ 目录生成后的工程包含四个关键文件。理解它们就等于掌握了 Flipper Zero JS App 的最小工程结构。3.1fz-sdk.config.json5构建与上传配置这是整个工程的枢纽配置使用 JSON5 语法支持注释包含build与upload两大段{ build: { // 编译产物的输出路径 output: dist/app_name.js, // 是否压缩以减小文件体积以牺牲可读性和错误信息清晰度为代价 minify: false, // 若已通读文档、确认可自行处理版本检查可设为 false enforceSdkVersion: true, }, upload: { // 上传来源文件若构建后无额外处理应与 build.output 一致 input: dist/app_name.js, // 上传到设备上的目标路径 output: /ext/apps/Scripts/app_name.js, }, }各配置项说明对应 fz-sdk.config.json5 模板源码配置项含义默认行为build.output打包产物路径同时是upload.input的默认来源dist/app_name.jsbuild.minify是否启用 esbuild 压缩输出false保留可读性与错误信息build.enforceSdkVersion是否在产物头部注入 SDK 版本兼容性检查true强烈建议保持开启upload.output脚本在设备上的存放位置/ext/apps/Scripts/app_name.js其中enforceSdkVersion对应 fz-sdk/sdk.js 中的实现构建时会读取 SDK 自身版本号并在产物最前面注入一行checkSdkCompatibility(major, minor);由设备端 JS 运行时在执行脚本时校验 SDK 兼容性避免因 API 变更导致运行期崩溃。3.2index.ts开箱即用的示例应用模板自带一个可直接运行的对话框示例template/index.ts演示了 Flipper Zero JS App 的标准骨架// import modules // caution: eventLoop HAS to be imported before gui, and gui HAS to be // imported before any gui submodules. import * as eventLoop from flipperdevices/fz-sdk/event_loop; import * as gui from flipperdevices/fz-sdk/gui; import * as dialog from flipperdevices/fz-sdk/gui/dialog; // a common pattern is to declare all the views that your app uses on one object const views { dialog: dialog.makeWith({ header: Hello from app_name, text: Check out index.ts and\nchange something :), center: Gonna do that!, }), }; // stop app on center button press eventLoop.subscribe(views.dialog.input, (_sub, button, eventLoop) { if (button center) eventLoop.stop(); }, eventLoop); // stop app on back button press eventLoop.subscribe(gui.viewDispatcher.navigation, (_sub, _item, eventLoop) { eventLoop.stop(); }, eventLoop); // run app gui.viewDispatcher.switchTo(views.dialog); eventLoop.run();这个示例刻意展示了三条重要约定导入顺序有强约束eventLoop必须先于gui导入gui必须先于任何gui子模块导入——这是 fz-sdk 类型声明中的硬性要求破坏顺序会导致运行时错误事件循环驱动所有交互都通过eventLoop.subscribe订阅视图输入事件完成中心键与返回键都会停止事件循环从而退出应用视图管理器gui.viewDispatcher.switchTo()负责切换当前显示的视图。flipperdevices/fz-sdk的完整类型声明位于仓库 applications/system/js_app/packages/fz-sdk/覆盖guidialog、submenu、text_input、widget、byte_input 等十余种视图、event_loop、flipper、gpio、storage、serial、badusb、math、notification等模块是开发时最重要的类型参考。3.3package.json与tsconfig.jsonpackage.json声明flipperdevices/fz-sdk^1.0与typescript^5.6.3两个开发依赖以及上文提到的build/start脚本tsconfig.json面向 Flipper Zero JS 运行时的编译配置target: ES2015、noLib: true不使用 Node 类型库、types: []并把 SDK 的global.d.ts显式纳入编译保证设备端全局 API 的类型可用。设备端的 JS 解释器仅支持受限的 ECMAScript 子集因此工具链在打包时会主动禁用大量现代语法特性见下文开发者应尽量编写 ES5/ES2015 风格的代码。四、SDK 构建与上传的底层原理npm start调用的sdk.js位于 applications/system/js_app/packages/fz-sdk/sdk.js这是理解整个工具链的关键文件。4.1build面向嵌入式运行时的 esbuild 打包build命令基于 esbuild 完成三件事以./dist/index.js即 tsc 的编译产物为入口按tsconfig.json配置打包成单个 CommonJS 文件输出到config.output通过external: [flipperdevices/fz-sdk/*]把 SDK 模块声明为外部依赖——SDK 不打包进产物而是由设备端运行时按需解析这也是为什么 import 顺序如此重要最关键的是supported配置显式将arrow、async-await、class、template-literal、optional-chain、nullish-coalescing、destructuring、for-of等数十项现代语法特性全部设为false仅保留const-and-let。这意味着任何依赖现代 JS 语法的代码都会在构建阶段被拒绝从源头保证产物与 Flipper Zero 内置解释器的语法能力兼容。打包完成后脚本会在产物头部拼接let exports {};并根据enforceSdkVersion注入版本检查调用最终写回输出文件。4.2upload串口发现、写入与启动upload命令实现了一条完整的写盘-运行链路发现设备通过SerialPort.list()枚举串口优先按serialNumber以flip_前缀识别 Flipper Zero针对部分 Windows 驱动不报告序列号的情况回退到按 STM32 VCP 的VID 0483 : PID 5740匹配。若同时连接多台设备会弹出选择框建立连接以230400波特率打开串口等待 CLI 提示符:出现写入脚本依次执行storage remove清除旧文件、storage write_chunk path size声明写入块大小、随后发送文件内容等待写入完成启动应用执行js path命令启动脚本实时转发设备输出到终端并在脚本退出出现Script done!后自动结束进程。这条链路意味着你甚至可以把生成的dist/*.js手动复制到设备/ext/apps/Scripts/目录后自行运行upload只是把这个过程自动化了。五、版本兼容性约定脚手架配套的fz-sdk包遵循一套明确的版本语义见 fz-sdk/README.md包版本号的 major.minor 与其所面向的 Flipper Zero JS SDK 版本一致并遵循 semver。例如用 SDK 版本0.1.0编译的应用兼容0.1至1.0不含1.0之间的 SDK 版本。每个 API 的版本历史记录在其 JSDoc 注释中。SDK 强烈建议开发者根据场景组合使用sdkCompatibilityStatus、isSdkCompatible、assertSdkCompatibility等运行时 API 做兼容性检查——这也是模板默认开启enforceSdkVersion的原因把版本检查内联进产物确保设备端与工具链版本匹配时应用才允许运行将兼容性问题提前暴露在启动阶段。六、下一步深入 JS 开发脚手架生成的工程是探索 Flipper Zero JS API 的最佳起点。本仓库的 documentation/js/ 目录提供了完整的模块级参考包括js_developing_apps_using_js_sdk.md基于 JS SDK 开发应用的总体流程js_event_loop.md 与 js_gui.md事件循环与 GUI 视图体系js_gui__dialog.md、js_gui__submenu.md、js_gui__widget.md 等各视图组件的独立用法说明js_storage.md、js_gpio.md、js_serial.md文件系统、GPIO、串口等硬件能力访问。结合 fz-sdk 的类型声明IDE 中可直接获得智能提示你可以从模板的对话框示例出发逐步替换为菜单、文本输入、文件浏览器等更复杂的界面构建真正可用的设备端工具应用。【免费下载链接】flipperzero-firmwareFlipper Zero firmware source code项目地址: https://gitcode.com/GitHub_Trending/fl/flipperzero-firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Flipper Zero JavaScript 应用脚手架：使用 create-fz-app 快速创建与运行 JS App
Flipper Zero JavaScript 应用脚手架使用 create-fz-app 快速创建与运行 JS App【免费下载链接】flipperzero-firmwareFlipper Zero firmware source code项目地址: https://gitcode.com/GitHub_Trending/fl/flipperzero-firmware导读本指南围绕 Flipper Zero 官方 JavaScript SDK 的脚手架工具flipperdevices/create-fz-app展开介绍如何在本地用一条命令交互式生成一个完整的 JS 应用工程、通过npm start一键完成编译、上传与在真机上运行。读完本文你将掌握 Flipper Zero JS App 从空目录到屏幕弹出 Hello 对话框的完整开发闭环并理解脚手架背后的模板结构、fz-sdk.config.json5配置语义以及 SDK 的构建与串口上传原理。一、脚手架工具是什么create-fz-app是 Flipper Zero 官方发布在 npm 上的交互式脚手架包包名flipperdevices/create-fz-app用于在本地生成一个可运行的 JavaScript 应用工程目标运行环境是 Flipper Zero 设备内置的 JS 解释器mjs。该包与flipperdevices/fz-sdk官方类型声明与构建/上传工具链配套使用两者的源码均位于本仓库的 applications/system/js_app/packages/ 目录下。从源码看脚手架的核心逻辑非常轻量create-fz-app/index.js通过prompts交互式收集用户输入然后把内置的template/模板目录复制到目标文件夹用项目名替换模板中的app_name占位符最后调用所选包管理器执行依赖安装。包本身依赖极少仅prompts与replace-in-file见 package.json这意味着它只负责生成工程真正的编译与上传由模板中引入的fz-sdk完成。二、快速开始三分钟创建并运行第一个应用2.1 创建工程在任意空目录下执行官方推荐命令npx flipperdevices/create-fz-applatestnpx会自动从 npm 拉取最新版脚手架并启动交互式向导期间会依次询问三个问题项目名称默认my-flip-app生成后即作为目录名包管理器选择npm/pnpm/yarn三选一确认创建默认确认。确认后工具会复制模板文件、将模板内所有app_name占位符替换为你的项目名对应源码中的replaceInFileSync({ files:${name}/**/*, from: /app_name/g, to: name })然后自动执行pnpm install/npm install/yarn install安装依赖。若目标目录已存在同名文件或目录向导会额外询问是否继续覆盖源码中通过fs.rmSync(name, { recursive: true, force: true })实现删除重建因此请谨慎操作。2.2 运行到 Flipper Zero进入生成的项目目录并启动cd my-flip-app npm start如果你在创建时选择了pnpm或yarn完全可以使用pnpm start/yarn start代替npm start三个包管理器对工具链完全等价。npm start实际执行的是模板 package.json 中定义的两步流水线build: tsc node node_modules/flipperdevices/fz-sdk/sdk.js build, start: npm run build node node_modules/flipperdevices/fz-sdk/sdk.js upload即先用 TypeScript 编译器检查并产出 JS再调用fz-sdk的build命令打包最后用upload命令把产物通过串口写入 Flipper Zero 并立即运行。2.3 运行前提需要 Node.js 环境脚手架与 SDK 均为 Node 工具链Flipper Zero 需通过 USB 连接到电脑并处于命令行模式CLI 会话以便upload通过串口交互首次使用时会通过串口在设备上创建/ext/apps/Scripts/目录存放脚本详见下文配置与上传原理。三、生成的工程模板剖析脚手架内置的模板文件位于仓库的 applications/system/js_app/packages/create-fz-app/template/ 目录生成后的工程包含四个关键文件。理解它们就等于掌握了 Flipper Zero JS App 的最小工程结构。3.1fz-sdk.config.json5构建与上传配置这是整个工程的枢纽配置使用 JSON5 语法支持注释包含build与upload两大段{ build: { // 编译产物的输出路径 output: dist/app_name.js, // 是否压缩以减小文件体积以牺牲可读性和错误信息清晰度为代价 minify: false, // 若已通读文档、确认可自行处理版本检查可设为 false enforceSdkVersion: true, }, upload: { // 上传来源文件若构建后无额外处理应与 build.output 一致 input: dist/app_name.js, // 上传到设备上的目标路径 output: /ext/apps/Scripts/app_name.js, }, }各配置项说明对应 fz-sdk.config.json5 模板源码配置项含义默认行为build.output打包产物路径同时是upload.input的默认来源dist/app_name.jsbuild.minify是否启用 esbuild 压缩输出false保留可读性与错误信息build.enforceSdkVersion是否在产物头部注入 SDK 版本兼容性检查true强烈建议保持开启upload.output脚本在设备上的存放位置/ext/apps/Scripts/app_name.js其中enforceSdkVersion对应 fz-sdk/sdk.js 中的实现构建时会读取 SDK 自身版本号并在产物最前面注入一行checkSdkCompatibility(major, minor);由设备端 JS 运行时在执行脚本时校验 SDK 兼容性避免因 API 变更导致运行期崩溃。3.2index.ts开箱即用的示例应用模板自带一个可直接运行的对话框示例template/index.ts演示了 Flipper Zero JS App 的标准骨架// import modules // caution: eventLoop HAS to be imported before gui, and gui HAS to be // imported before any gui submodules. import * as eventLoop from flipperdevices/fz-sdk/event_loop; import * as gui from flipperdevices/fz-sdk/gui; import * as dialog from flipperdevices/fz-sdk/gui/dialog; // a common pattern is to declare all the views that your app uses on one object const views { dialog: dialog.makeWith({ header: Hello from app_name, text: Check out index.ts and\nchange something :), center: Gonna do that!, }), }; // stop app on center button press eventLoop.subscribe(views.dialog.input, (_sub, button, eventLoop) { if (button center) eventLoop.stop(); }, eventLoop); // stop app on back button press eventLoop.subscribe(gui.viewDispatcher.navigation, (_sub, _item, eventLoop) { eventLoop.stop(); }, eventLoop); // run app gui.viewDispatcher.switchTo(views.dialog); eventLoop.run();这个示例刻意展示了三条重要约定导入顺序有强约束eventLoop必须先于gui导入gui必须先于任何gui子模块导入——这是 fz-sdk 类型声明中的硬性要求破坏顺序会导致运行时错误事件循环驱动所有交互都通过eventLoop.subscribe订阅视图输入事件完成中心键与返回键都会停止事件循环从而退出应用视图管理器gui.viewDispatcher.switchTo()负责切换当前显示的视图。flipperdevices/fz-sdk的完整类型声明位于仓库 applications/system/js_app/packages/fz-sdk/覆盖guidialog、submenu、text_input、widget、byte_input 等十余种视图、event_loop、flipper、gpio、storage、serial、badusb、math、notification等模块是开发时最重要的类型参考。3.3package.json与tsconfig.jsonpackage.json声明flipperdevices/fz-sdk^1.0与typescript^5.6.3两个开发依赖以及上文提到的build/start脚本tsconfig.json面向 Flipper Zero JS 运行时的编译配置target: ES2015、noLib: true不使用 Node 类型库、types: []并把 SDK 的global.d.ts显式纳入编译保证设备端全局 API 的类型可用。设备端的 JS 解释器仅支持受限的 ECMAScript 子集因此工具链在打包时会主动禁用大量现代语法特性见下文开发者应尽量编写 ES5/ES2015 风格的代码。四、SDK 构建与上传的底层原理npm start调用的sdk.js位于 applications/system/js_app/packages/fz-sdk/sdk.js这是理解整个工具链的关键文件。4.1build面向嵌入式运行时的 esbuild 打包build命令基于 esbuild 完成三件事以./dist/index.js即 tsc 的编译产物为入口按tsconfig.json配置打包成单个 CommonJS 文件输出到config.output通过external: [flipperdevices/fz-sdk/*]把 SDK 模块声明为外部依赖——SDK 不打包进产物而是由设备端运行时按需解析这也是为什么 import 顺序如此重要最关键的是supported配置显式将arrow、async-await、class、template-literal、optional-chain、nullish-coalescing、destructuring、for-of等数十项现代语法特性全部设为false仅保留const-and-let。这意味着任何依赖现代 JS 语法的代码都会在构建阶段被拒绝从源头保证产物与 Flipper Zero 内置解释器的语法能力兼容。打包完成后脚本会在产物头部拼接let exports {};并根据enforceSdkVersion注入版本检查调用最终写回输出文件。4.2upload串口发现、写入与启动upload命令实现了一条完整的写盘-运行链路发现设备通过SerialPort.list()枚举串口优先按serialNumber以flip_前缀识别 Flipper Zero针对部分 Windows 驱动不报告序列号的情况回退到按 STM32 VCP 的VID 0483 : PID 5740匹配。若同时连接多台设备会弹出选择框建立连接以230400波特率打开串口等待 CLI 提示符:出现写入脚本依次执行storage remove清除旧文件、storage write_chunk path size声明写入块大小、随后发送文件内容等待写入完成启动应用执行js path命令启动脚本实时转发设备输出到终端并在脚本退出出现Script done!后自动结束进程。这条链路意味着你甚至可以把生成的dist/*.js手动复制到设备/ext/apps/Scripts/目录后自行运行upload只是把这个过程自动化了。五、版本兼容性约定脚手架配套的fz-sdk包遵循一套明确的版本语义见 fz-sdk/README.md包版本号的 major.minor 与其所面向的 Flipper Zero JS SDK 版本一致并遵循 semver。例如用 SDK 版本0.1.0编译的应用兼容0.1至1.0不含1.0之间的 SDK 版本。每个 API 的版本历史记录在其 JSDoc 注释中。SDK 强烈建议开发者根据场景组合使用sdkCompatibilityStatus、isSdkCompatible、assertSdkCompatibility等运行时 API 做兼容性检查——这也是模板默认开启enforceSdkVersion的原因把版本检查内联进产物确保设备端与工具链版本匹配时应用才允许运行将兼容性问题提前暴露在启动阶段。六、下一步深入 JS 开发脚手架生成的工程是探索 Flipper Zero JS API 的最佳起点。本仓库的 documentation/js/ 目录提供了完整的模块级参考包括js_developing_apps_using_js_sdk.md基于 JS SDK 开发应用的总体流程js_event_loop.md 与 js_gui.md事件循环与 GUI 视图体系js_gui__dialog.md、js_gui__submenu.md、js_gui__widget.md 等各视图组件的独立用法说明js_storage.md、js_gpio.md、js_serial.md文件系统、GPIO、串口等硬件能力访问。结合 fz-sdk 的类型声明IDE 中可直接获得智能提示你可以从模板的对话框示例出发逐步替换为菜单、文本输入、文件浏览器等更复杂的界面构建真正可用的设备端工具应用。【免费下载链接】flipperzero-firmwareFlipper Zero firmware source code项目地址: https://gitcode.com/GitHub_Trending/fl/flipperzero-firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考