20px为什么不是64px的缩小版thinking-orbs双尺寸独立设计与暗色/亮色主题自动适配深度解析【免费下载链接】thinking-orbsDotted thought-orb loading indicators for AI agent UIs, 9 tuned types, two sizes, auto dark/light项目地址: https://gitcode.com/gh_mirrors/th/thinking-orbsthinking-orbs是一款面向 AI 与 Agent 界面的点阵思维球加载指示器 React 组件9 种手工调校的动画状态working、searching、solving……、两个独立调校的尺寸64px 与 20px、暗色/亮色主题全自动适配全部基于最朴素的 2D Canvas 绘制——无 WebGL、无滤镜Chrome、Safari、Firefox 下像素级一致。很多开发者第一反应是两种尺寸把大的缩小不就完了吗这篇文章带你深入 preset 调校表和三层主题解析机制看看为什么缩小版恰恰是它刻意避开的方案。为什么等比缩小会毁掉一个加载指示器直观上64px 缩到 20px缩小 3.2 倍似乎只是transform: scale()的事。但点阵动画的可读性由三个独立变量决定变量64px 下粗暴缩小后在 20px 下点的数量几百个点的细腻网格点挤成一团糊斑点的大小有呼吸感的近深远小细到肉眼不可见动画速度从容舒展视觉上显得更快更碎thinking-orbs在类型层面就拒绝了这种做法——OrbSize是一个精确的联合类型64 \| 20传别的数字会直接报类型错误见 src/types.tsexport type OrbSize 64 | 20;这两个值不是渲染边长而是两套独立调校的预设名称64对应聊天头像场景20对应行内文字场景各自拥有独立的点数量、点半径和速度参数官方说明见 README.md。双尺寸预设表9 状态 × 2 尺寸的独立调校真正的调校数据集中在 src/presets.ts 的PRESETS表里9 个动画模式 × 2 个尺寸每个组合都有自己烘焙好的speed速度倍率、count点数量倍率、size点半径倍率和模式专属附加参数。对比working状态轨道粒子的两行orbits: { 64: { speed: 1.885, count: 1, size: 1 }, 20: { speed: 3.9, count: 0.238, size: 2.4 } }三个倍率两两不同、且与缩放比例 3.2 毫无关系20px 版的点数量砍到约 1/4、单点放大约 2.4 倍、速度提到 2 倍。再看connecting星座连线64px 速度 3.31520px 速度 6.63——每个状态都有自己听感正确的节奏这是逐帧人眼调校baked tuning session的结果不可能从一个统一缩放系数推导出来。解析逻辑很轻resolvePreset按(state, size)组合查表、缩放后缓存渲染循环拿到的全是现成数字src/presets.ts。背后的数学点数按面积缩放所以开平方数量缩放并非拍脑袋基础数学在 src/engine/profiles.tsscaleCounts环形/网格类点阵如latRings × lonDensity两个维度各乘 √scale这样总点数才与面积成正比球面密度不变形scaleRadii统一缩放 9 个半径类参数rBase、rDepth、nodeR……保证近大远小的深度衰减曲线在小尺寸下依然成立。所以 20px 预设可以理解为以正确的几何规则缩放为骨架 逐状态人工再调校为血肉。暗色/亮色自动适配themeauto 的三层解析机制配色策略是严格的单色墨迹哲学深色背景用浅色墨点浅色背景用深色墨点画布保持透明src/engine/core.ts 的Dot.white字段注释即写明Dark themes 下镜像。而主题由谁决定看 src/theme.ts 的useResolvedDarkauto模式按三层顺序解析且全程实时监听祖先节点约定优先——向上遍历 DOM找到data-themedark|light属性或dark/lightclassTailwind / shadcn 的通行约定即采用并用MutationObserver监听全树 class 与data-theme变化回落到系统偏好——订阅prefers-color-scheme: dark操作系统切主题时即时跟随无需刷新SSR 安全——所有监听都跑在useEffect里画布只在客户端主题解析完成后才落笔服务端渲染零报错。显式传入themedark或themelight可跳过检测直接锁定见 README.md。实际收益切一次系统主题0 行代码改动把上面串起来就是完整链路OS 切换深色模式 →matchMedia触发 → 重新解析dark→ 依赖项变化 → 组件重绘为浅色墨点。整条链路在 src/ThinkingOrb.tsx 中由dark作为 effect 依赖项驱动同时它还顺手处理了两个体验细节prefers-reduced-motion用户得到一帧静态定格但依然跟随主题、实例滚出视口或标签页隐藏时自动暂停、恢复时保持同相位全站共享一个performance.now()时钟。上手只需一行代码import { ThinkingOrb } from thinking-orbs; ThinkingOrb statesearching size{20} / {/* 行内文字旁 */} ThinkingOrb statesolving size{64} / {/* 头像/卡片位 */}theme默认就是auto什么都不写也能正确变色speed、paused、aria-label按需覆盖其余canvas属性原样透传。想可视化调参可以看看演示工程里的交互面板 demo/components/Playground.tsx。关键文件速查 内容路径双尺寸独立预设表src/presets.ts√ 缩放与半径缩放算法src/engine/profiles.ts三层主题自动解析src/theme.ts组件主循环与自动暂停src/ThinkingOrb.tsx尺寸/状态/主题类型定义src/types.ts跨端移植与调校说明PORT_PLAN.md总结thinking-orbs用预设名而非边长的 API 设计、逐状态独立调校的双尺寸参数表、以及三层实时主题解析把加载指示器从能转推进到了在任何尺寸、任何主题下都恰到好处。对于做 AI 聊天界面、Agent 状态流的开发者这是几乎零成本获得专业级动效细节的选择。【免费下载链接】thinking-orbsDotted thought-orb loading indicators for AI agent UIs, 9 tuned types, two sizes, auto dark/light项目地址: https://gitcode.com/gh_mirrors/th/thinking-orbs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考