Flipper Zero Unleashed 固件 JS Math 模块完全指南常量、全部数学方法与源码级实现解析【免费下载链接】unleashed-firmwareFlipper Zero Unleashed Firmware项目地址: https://gitcode.com/GitHub_Trending/un/unleashed-firmware本指南围绕 Unleashed 固件Flipper ZeroJS 插件系统中的math模块展开系统讲解其 3 个内置常量与 24 个数学方法的参数、返回值、边界行为及典型示例并深入对应原生实现 modules/js_math.c 与插件注册信息 application.fam帮助你理解该模块与 mjs 引擎、硬件随机数等底层机制的衔接方式。读完本文你将能在自己的 Flipper JS 脚本中熟练完成数值计算、角度换算、随机数生成与浮点容差比较等任务。模块加载与运行前提math模块属于 Unleashed 固件 JS 运行时js_app的内置模块使用前必须先通过require函数加载let math require(math);从源码结构看该模块以 Flipper 应用插件PLUGIN形式存在其声明位于 application.famappidjs_math、entry_pointjs_math_ep类型为FlipperAppType.PLUGINrequires[js_app]即依赖 JS 应用宿主运行时源码仅一个文件sources[modules/js_math.c]fap_exclude_libs[gcc]说明该插件在构建时排除 gcc 运行库依赖浮点运算由固件侧的 libm 提供。模块实际注册名称是字符串math定义于 js_math.c 的JsModuleDescriptor并通过FlipperAppPluginDescriptorappid PLUGIN_APP_ID即js导出给 JS 宿主。这意味着math是随固件 JS 插件系统一起分发、无需额外安装即可使用的标准模块。常量math模块提供三个常量均为 IEEE 754 双精度浮点数取自 C 标准库PI圆周率 π精确值为3.14159265358979323846264338327950288源码中定义为((double)M_PI)js_math.c。math.PI; // 3.141592653589793E自然常数 e欧拉数精确值为2.71828182845904523536028747135266250源码中定义为((double)M_E)js_math.c。math.E; // 2.718281828459045EPSILON满足1.0 EPSILON ! 1.0的最小数值即 C 标准头float.h中的DBL_EPSILON值为2.2204460492503131e-16js_math.c。它代表双精度浮点数在 1.0 附近的机器精度常用来判断两个浮点数是否足够接近。math.EPSILON; // 2.220446049250313e-16基本算术与舍入方法abs(x)返回一个数的绝对值。若x为负数包括-0返回-x否则返回x。结果恒为非负数或 0。源码通过fabs(x)实现js_math.c。math.abs(-5); // 5 math.abs(5); // 5ceil(x)向上取整返回大于或等于x的最小整数。数学上等价于-math.floor(-x)。源码直接调用ceil(x)js_math.c。math.ceil(-7.004); // -7 math.ceil(7.004); // 8floor(x)向下取整返回小于或等于x的最大整数。等价于-math.ceil(-x)。源码直接调用floor(x)js_math.c。math.floor(-45.95); // -46 math.floor(-45.05); // -46 math.floor(-0); // -0 math.floor(0); // 0 math.floor(45.05); // 45 math.floor(45.95); // 45trunc(x)截断取整直接移除小数部分返回x的整数部分。与ceil/floor不同它不区分正负方向而是向零舍入。源码实现为x 0 ? ceil(x) : floor(x)js_math.c。math.trunc(-1.123); // -1 math.trunc(0.123); // 0 math.trunc(13.37); // 13 math.trunc(42.84); // 42cbrt(x)返回x的立方根。源码直接调用cbrt(x)js_math.c。与平方根不同立方根对负数同样有效。math.cbrt(2); // 1.2599210498948732 math.cbrt(27); // 3sqrt(x)返回x的平方根非负数。参数必须大于或等于 0若x 0脚本会因参数错误而失败。源码在调用sqrt(x)前显式校验x 0并抛出错误js_math.c。math.sqrt(25); // 5 math.sqrt(0); // 0pow(base, exponent)返回base的exponent次幂。两个参数均为数值源码直接调用pow(base, exponent)js_math.c。math.pow(7, 2); // 49 math.pow(7, 3); // 343 math.pow(2, 10); // 1024exp(x)返回 e 的x次幂e^x结果为非负数。源码直接调用exp(x)js_math.c。math.exp(0); // 1 math.exp(1); // 2.718281828459045log(x)返回x的自然对数以 e 为底即ln(x)。参数必须大于 0源码在校验x 0时抛出参数错误js_math.c。math.log(1); // 0 math.log(3); // 1.0986122886681098sign(x)返回表示数值符号的结果。需要注意原文档描述为返回 1 或 -1但当前仓库源码 js_math.c 的实际行为更精细——当|x| EPSILON即约等于 0时返回0否则x 0返回-1、x 0返回1。以源码为准该函数实际是三元符号函数math.sign(3); // 1 math.sign(0); // 1文档示例注意0 在源码中因 |0| EPSILON 实际返回 0 math.sign(-3); // -1提示使用sign时若涉及0的判定应以当前固件源码行为返回 0为准避免文档旧描述导致的预期偏差。clz32(x)返回x的 32 位二进制表示中前导 0 的个数。源码将参数截断为unsigned int后通过右移计数实现js_math.c例如1的 32 位表示仅末位为 1前导 0 为 31 个。math.clz32(1); // 31 math.clz32(1000); // 22三角函数sin(x)返回弧度角x的正弦值结果在[-1, 1]区间内。源码调用sin(x)js_math.c。math.sin(math.PI / 2); // 1cos(x)返回弧度角x的余弦值结果在[-1, 1]区间内。源码调用cos(x)js_math.c。math.cos(math.PI); // -1asin(x)返回x的反正弦值弧度角度范围[-π/2, π/2]。参数表示正弦值理论上应在[-1, 1]内。源码直接调用asin(x)js_math.c。math.asin(0.5); // 0.5235987755982989acos(x)返回x的反余弦值弧度角度范围[0, π]。文档描述若x小于 -1 或大于 1 返回NaN但当前源码 js_math.c 在越界时会直接抛出参数错误Invalid input value for math.acos而非返回 NaN使用时请以源码行为为准。math.acos(-1); // 3.141592653589793 math.acos(0); // 1.5707963267948966atan(x)返回x的反正切值弧度角度范围(-π/2, π/2)。源码调用atan(x)js_math.c。math.atan(1); // 0.7853981633974483atan2(y, x)返回平面中正 x 轴与原点 (0,0) 到点 (x, y) 射线之间的夹角弧度范围[-π, π]。与atan不同它同时考虑 x、y 的符号能确定角的象限。注意参数顺序为atan2(y, x)js_math.c。math.atan2(90, 15); // 1.4056476493802699双曲函数sinh / cosh 相关说明math模块并未提供sinh/cosh直接函数但提供了三个反双曲函数均由对数与平方根组合实现acosh(x)返回x的反双曲余弦。参数必须大于或等于 1源码校验x 1时报错并实现为log(x sqrt(x*x - 1))js_math.c。math.acosh(1); // 0 math.acosh(2); // 1.3169578969248166asinh(x)返回x的反双曲正弦。源码实现为log(x sqrt(x*x 1))js_math.c对任意实数有效。math.asinh(1); // 0.881373587019543atanh(x)返回x的反双曲正切。参数应在开区间(-1, 1)内源码校验越界报错并实现为0.5 * log((1 x) / (1 - x))js_math.c。math.atanh(0.5); // 0.5493061443340548比较、极值与随机数max(a, b)返回两个参数中的较大值。源码用三元比较x y ? x : y实现js_math.c。math.max(10, 20); // 20 math.max(-10, -20); // -10min(a, b)返回两个参数中的较小值。源码用三元比较x y ? x : y实现js_math.c。math.min(10, 20); // 10 math.min(-10, -20); // -20isEqual(a, b, tolerance)若a与b之差的绝对值小于等于指定容差tolerance返回true否则false。源码实现为fabs(a - b) ejs_math.c。这是浮点比较的推荐方式可规避二进制浮点表示导致的精度误差。math.isEqual(1.4, 1.6, 0.2); // false差 0.2 0.2实际 0.2 0.2源码用 判定为 true见下方说明 math.isEqual(3.556, 3.555, 0.01); // true精度说明文档示例第一行结果为false而源码判定条件为fabs(a - b) tolerance由于浮点运算中fabs(1.4 - 1.6)实际为0.20000000000000018恰好大于0.2故结果为false与文档示例一致。这说明浮点比较务必显式给出容差且容差要留有余量。random()返回一个伪随机浮点数范围[0, 1)含 0不含 1在区间内近似均匀分布。这是本模块最特殊的方法源码不依赖软件伪随机数生成器而是调用固件硬件随机数接口furi_hal_random_get()将 32 位随机值除以FURI_HAL_RANDOM_MAX归一化到[0, 1)js_math.c。从实现注释看当前仅使用 32 位熵作者亦标注了未来可扩展的余地。硬件随机源意味着每次调用结果难以预测可用于随机数种子、抽奖、抖动补偿等场景。let num math.random(); // 0 num 1 let dice math.floor(math.random() * 6) 1; // 模拟掷骰子 1..6参数校验与错误处理机制所有方法共用一套参数检查逻辑js_math.c参数个数必须与期望完全一致否则抛出Wrong argument count参数类型每个参数必须是数值类型mjs_is_number否则抛出Wrong argument type数值域校验部分函数如acos、acosh、atanh、log、sqrt在输入超出定义域时抛出Invalid input value for math.name。错误通过mjs_prepend_errorf(mjs, MJS_BAD_ARGS_ERROR, ...)注入方法返回MJS_UNDEFINED。因此在编写脚本时应对用户输入做范围预检避免依赖报错做业务逻辑涉及log、sqrt、acos等定义域受限函数时先判断输入再调用。综合实战示例以下示例综合运用常量、三角函数、随机数与容差比较演示在 Flipper JS 中常见的计算场景let math require(math); // 1. 角度转弧度并计算三角函数 let deg 45; let rad deg * math.PI / 180; print(math.sin(rad)); // ≈ 0.7071067811865475 print(math.cos(rad)); // ≈ 0.7071067811865476 // 2. 由平面坐标计算极坐标角度 let angle math.atan2(1, 1); // π/4 ≈ 0.7853981633974483 // 3. 浮点精度容差比较 print(math.isEqual(0.1 0.2, 0.3, 0.000001)); // true // 4. 硬件随机数生成指定范围整数 let rnd math.floor(math.random() * 100); // 0..99 // 5. 指数与对数互逆验证 print(math.log(math.E)); // 1 print(math.exp(math.log(8))); // 8 // 6. 数值归一化到 [-1, 1] function normalize(v, min, max) { return (v - min) / (max - min) * 2 - 1; }与标准 JavaScript Math 的差异提示虽然 API 命名与标准 JavaScriptMath高度相似但存在若干差异值得注意部分函数如max/min仅接受两个参数而标准Math.max/Math.min支持任意多个参数random()基于固件硬件随机数furi_hal_random_get并非标准引擎的伪随机算法安全性/随机性来源不同未提供sinh、cosh、tanh等正双曲函数及round、fround、imul、log2、log10等标准方法可结合pow/log/exp自行组合实现越界输入如acos(2)、log(0)多数情况下以参数错误形式中断脚本而非返回NaN或Infinity。相关文档与源码导航官方模块文档documentation/js/js_math.md模块原生实现applications/system/js_app/modules/js_math.c插件注册信息applications/system/js_app/application.famJS 模块公共头文件错误处理与对象构造宏applications/system/js_app/js_modules.hJS 运行时总览documentation/js/js_builtin.mdJS 数据类型与数值表示documentation/js/js_data_types.md【免费下载链接】unleashed-firmwareFlipper Zero Unleashed Firmware项目地址: https://gitcode.com/GitHub_Trending/un/unleashed-firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
