~/progetti/aplomb/README.md

COOKIES_ADVICE PRIVACY_POLICY.

~/progetti/aplomb/README.md

Aplomb

{ 日期: “2026-05-01”, 状态: “live”, 技术栈模块: 7 }

基于 React Native 与 Expo 打造的跨平台数字水平仪,精准而细致

Aplomb 是一款功能完整的数字水平仪应用,可在 iOS、Android 和 Web 上使用。它以物理精确、视觉简洁的界面取代了传统的气泡水平仪,能够实时响应设备的方向。无论是挂一幅画、调平一个架子,还是在工地上检查一个表面,Aplomb 都能提供精确的倾角读数,并伴随即时的视觉、音频与触觉反馈。

aplomb 一词源自法语,意为"铅垂线",既体现了应用的用途,也反映了其构建过程中的精细:稳定、精准、平衡。

## 两种交互视图模式

应用提供两种互补的可视化,根据你持握设备的方式进行切换:

·Disc Level — 适用于水平/平面的经典圆形气泡水平仪;平滑的指示器同时跟踪 X/Y 两轴的倾斜
·Horizon Mode — 全屏地平线在实时旋转以显示翻滚角,适用于设备垂直持握的场景(例如靠墙)
·自动切换 — 应用通过加速度计数据的 atan2 判断设备的俯仰,并在两种模式之间平滑交叉渐变,也可手动锁定其中之一

## 实时传感器处理

加速度计数据以 20 Hz 的频率采样,并在专用数学层(level-math.ts)中进行处理,计算:

·俯仰角 — 区分设备处于水平还是垂直
·翻滚角 — 驱动地平线的旋转
·X/Y 倾斜角度(度) — 在屏幕上数值呈现
·水平检测 — 针对水平与垂直表面可配置的容差阈值

## 多感官反馈

当表面完全水平时,应用会以三种方式进行确认:通过 expo-audio 播放干净的音频提示音、通过 expo-haptics 产生令人满意的震动模式,并高亮显示指示器和读数。用户可以通过单次点击,在声音、震动或静音模式之间切换。

## 校准与已保存的测量

内置的校准模块允许用户设置自定义的零角度偏移,并通过 AsyncStorage 在会话之间持久化。这对于校正旧设备的细微误差或相对某个参考面测量角度至关重要。测量结果可通过自定义标签进行快照保存,并随后在历史卡片界面中查看,附带时间戳与删除操作。

## 自适应设计与主题

响应式布局适配手机与平板(iPhone 与 iPad),在所有设备上均支持横屏方向。基于屏幕对角线的动态尺寸计算,确保在任何设备形态下 UI 都能正确填满屏幕。浅色、深色与跟随系统的自动主题均可在运行时切换,无需重启应用。

## 国际化

应用开箱即带 15 种语言,并会自动检测设备区域:英语、意大利语、德语、法语、西班牙语、葡萄牙语、俄语、中文、日语、阿拉伯语、印地语、乌尔都语、孟加拉语、印尼语和土耳其语。通过自定义的 Expo 配置插件,应用名本身在操作系统主屏幕上也会按语言进行本地化。

## 技术栈

技术选型反映了对流畅、灵敏体验的需求:

·React Native 0.83 搭配 React 19 与实验性 React Compiler
·Expo ~55 managed workflow,提供工具链与原生模块生态
·TypeScript 5.9,覆盖整个代码库的静态类型
·Expo Router,基于文件的类型化路由导航
·expo-sensors、expo-haptics 与 expo-audio,用于硬件访问
·React Native Reanimated 4 与 shared values,在 UI 线程实现弹簧物理动画
·react-native-worklets 与 react-native-gesture-handler,用于手势互操作与帧同步计算
·TailwindCSS + Uniwind、tailwind-variants、heroui-native 与 react-native-svg,构建 UI
·expo-glass-effect 与 expo-symbols,在 iOS 上实现玻璃态与 SF Symbols
·i18next 搭配 expo-localization,实现运行时切换语言
·AsyncStorage,用于本地持久化校准与测量记录
·EAS Build,面向 iOS 与 Android 的云端构建,配合 expo-dev-client 与 expo-build-properties

## 架构亮点

塑造代码库特征的五项原则:

·关注点分离 — 传感器数学完全存在于 lib/level-math.ts,与 UI 隔离;渲染逻辑通过 useAccelerometer 自定义 hook 使用干净、类型化的值
·性能 — 动画值(discX、discY、horizonRoll、mode)通过 Reanimated shared values 运行在原生 UI 线程,每帧无需跨 JS 桥
·响应式几何 — getDynamicSizes() 基于实时屏幕尺寸重新计算布局常量,从 4" iPhone SE 到 13" iPad Pro 都能正确缩放
·平台拆分 — .web.tsx 与 .android.tsx 文件后缀提供特定于平台的 tab bar 实现,共享代码无需运行时分支
·多感官无障碍 — 视觉、听觉与触觉反馈互为冗余,确保在嘈杂或光线多变的环境下依然可用

Aplomb 作为应用可在 iOS、Android 与 Web 上使用,bundle id 为 com.mariustrica.aplomb。

// 技术栈
[react-native”, expo”, typescript”, ios”, android”, mobile”, sensors”, ]