多平台计算器 SDK

一个模块化的 TypeScript SDK，提供跨平台的计算器能力：独立的核心计算引擎、响应式状态管理层与可插拔的 UI 适配层，支持 Web、React、Vue 与微信小程序。内置主题、历史记录、模式切换与无障碍增强能力，并暴露丰富的 SDK 接口供业务扩展。

功能亮点

• 核心引擎：基于逆波兰式（Shunting Yard）解析的表达式求值，支持幂、开方、阶乘、对数、三角函数等科学运算，内置 π、e 常量，可配置精度与角度模式（度/弧度）。
• 状态管理：观察者模式的状态容器，维护表达式、显示屏、预览、历史、模式、主题等数据，提供结果、错误、模式切换、历史变更等事件。
• UI 适配层：
  • DOM 渲染器：具备可访问的按钮布局、历史面板、实时预览、键盘操作及主题融合。
  • React 适配：提供 DomCalculator 组件、上下文 Provider 及 Hook，方便在组件树中集成。
  • Vue 适配：基于 DOM 渲染器实现的 Calculator 组件。
  • 微信小程序：封装组件构造器，复用核心能力快速生成小程序计算器。
• UMD 构建：dist/calculator.umd.global.js 便于通过 <script> 标签直接引入。
• 主题系统：内置浅色/深色主题，基于 CSS 变量，可跟随 prefers-color-scheme 自动切换。
• 可扩展接口：支持自定义按键布局、主题变量、历史记录管理、表达式 API 等功能。在默认布局中新增快捷操作行：顶行的 ⟳ 一键模式切换、双列宽的 ⌫ 退格键以及 Copy 复制按钮，便于在简易模式下快速处理表达式。

项目结构

src/
  core/          # 表达式分词、RPN 计算、核心引擎
  state/         # 状态管理、事件定义与快照类型
  adapters/      # SDK 工厂、按键布局与公共类型
  ui/
    dom/         # DOM 渲染器与主题工具
    react/       # React Provider、Hook、DOM 包装
    vue/         # Vue 组件封装
  platform/
    wechat/      # 微信小程序组件工厂
  themes/        # 默认主题变量
  index.ts       # SDK 对外导出入口

脚本命令

npm run build   # 打包 ESM + CJS 输出，同时产出 UMD 与类型声明
npm run lint    # 执行 TypeScript 类型检查
npm run dev     # tsup watch 模式开发

构建产物位于 dist/：

• dist/index.js / dist/index.cjs：主 SDK 的 ESM/CJS 版本。
• dist/index.d.ts：自动生成的类型声明。
• dist/calculator.umd.global.js：浏览器场景可直接挂载 window.CalculatorSDK。
• CoreEngines/calculator-core.core.js / .core.cjs / .core.global.js：核心引擎独立构建，便于在小程序或其它自定义 UI 中复用。

安装方式

npm install multiplatform-calculator-sdk

提示：为避免 npm 10 与旧版构建管线（如 @stencil/[email protected]）产生的解析问题，建议使用 npm 9.x（项目在 package.json 的 engines 与 packageManager 中已固定版本范围）。如需在 npm 10 环境安装，请先执行 npm install -g npm@9 或在安装命令后附加 --legacy-peer-deps。

按需安装的对等依赖：

• React 适配：react + react-dom
• Vue 适配：vue

快速上手

原生 DOM

import { createDomCalculator } from 'multiplatform-calculator-sdk/ui/dom';

const mountPoint = document.getElementById('calculator');
const instance = createDomCalculator(mountPoint!, {
  autofocus: true,
  showHistory: true,
  sdkOptions: {
    defaultMode: 'scientific',
    angleMode: 'deg'
  }
});

// 直接调用核心 API
instance.sdk.calculate('2+3*4'); // => { value: 14, ... }

UMD 直接引入：

<script src="dist/calculator.umd.global.js"></script>
<script>
  const container = document.querySelector('#calculator');
  const instance = CalculatorSDK.createDomCalculator(container, {
    autofocus: true,
    draggable: true
  });
</script>

draggable 默认为 true，允许从外框边缘拖拽计算器；如需固定在页面上可设置为 false。

核心引擎（CoreEngines）

构建后会在根目录生成 CoreEngines/，包含三种格式：

| 文件 | 说明 | 使用方式 | | --- | --- | --- | | CoreEngines/calculator-core.core.js | ES Module | import { createCalculatorSDK } from './CoreEngines/calculator-core.core.js'; | | CoreEngines/calculator-core.core.cjs | CommonJS | const { createCalculatorSDK } = require('./CoreEngines/calculator-core.core.cjs'); | | CoreEngines/calculator-core.core.global.js | IIFE | <script> 引入后使用 window.CalculatorCore |

示例：在任意运行时快速构建自定义 UI。

import { createCalculatorSDK } from './CoreEngines/calculator-core.core.js';

const sdk = createCalculatorSDK({
  defaultMode: 'simple',
  angleMode: 'deg'
});

console.log(sdk.evaluate('69/9%8').displayValue); // => '7.666667e+0'

React

import { DomCalculator } from 'multiplatform-calculator-sdk/ui/react';

export function Calculator() {
  return <DomCalculator showHistory mountStyles />;
}

如需更灵活的控制，可使用 CalculatorProvider 包裹应用，并通过 useCalculatorSnapshot 获取状态。

Vue 3

import { Calculator } from 'multiplatform-calculator-sdk/ui/vue';

export default {
  components: { Calculator }
};

模板示例：

<Calculator :show-history="true" @result="handleResult" />

微信小程序

import { buildWechatCalculatorComponent } from 'multiplatform-calculator-sdk/platform/wechat';

Component(
  buildWechatCalculatorComponent({
    defaultMode: 'scientific'
  })
);

在 WXML 中绑定组件暴露的方法（onDigitTap、onOperatorTap 等）。

自定义能力

• 按键布局：通过 createCalculatorSDK 或 DOM 适配器的 layout 选项注入自定义布局，可按模式拆分并定义自定义事件。
• 主题扩展：传入 theme（包含 mode: 'auto' | 'light' | 'dark' 与自定义 CSS 变量），或运行时调用 sdk.setTheme 动态更新。
• 事件监听：使用 sdk.state.on('result' | 'error' | 'modeChange' | 'historyChange', handler) 注册回调，React/Vue 版本也提供相应的事件透出。
• 表达式 API：sdk.calculate(expression) 提供无副作用的计算，sdk.state.evaluate() 会同步更新 UI 状态与历史记录。
• 核心引擎复用：从 CoreEngines/ 目录引入独立构建的核心包，快速在任意运行时搭建自定义 UI。

未来拓展方向

• 集成单位换算，与表达式联动（如长度、重量、温度等）。
• 公式库管理，支持预设与自定义公式存储。
• 借助 Web Worker 进行重计算离线化，结合 PWA 提供离线使用体验。
• 提供更多主题包与多语言支持。

开发说明

• 使用 tsup 输出双构建（ESM/CJS）并额外产出 DOM UMD 包。
• 全部源码采用 TypeScript；Vue 适配基于渲染函数封装，避免引入 SFC 解析链路。
• 主题系统基于 CSS 变量，可在 mode: 'auto' 下自动响应系统主题。
• 目标运行环境覆盖现代浏览器（ES2019）、Vue 3 与 React 18。
• https://gitee.com/bai_jia_wei/calculator-sdk // 代码仓库地址

许可证

MIT © 2025