@rockn/vue-formula-editor

@rockn/vue-formula-editor

可复用的 Vue 3 公式编辑器组件 + 零依赖公式引擎。IF/ELSE 块状逻辑、点选变量与函数、枚举标签-值、键值对成员访问、语法高亮、实时求值与安全校验。引擎可脱离 Vue 单独使用，一套引擎同时服务编辑器与你的业务代码。

特性

• 块状 IF / ELSE IF / ELSE：IF 条件 THEN 真值 ELSE IF 条件 THEN 真值 … ELSE 假值，贴近自然语言；也支持中文关键字 如果 / 那么 / 否则 / 否则如果
• 函数式兼容：IF(条件, 真值, 假值)、IFS(...)、a ? b : c、中缀 AND / OR 依旧可用
• 枚举变量（标签 ↔ 值）：公式里写/显示标签（{会员等级} == '金卡'），求值返回代码值（如 GOLD），比较时标签与值双向可匹配；变量面板可点选标签
• 键值对变量（成员访问）：{订单}.金额、{订单}['金额']、{订单}.商品[0]，链式访问；字段定义优先、context 键兜底校验
• 47 个内置函数：逻辑、数字、文本（含 CONTAINS/REPLACE/SPLIT 等）、类型转换、日期、聚合统计
• 悬停提示：变量（类型/必填/描述/当前值/枚举标签/键值对字段）、函数（签名/参数说明/示例）、关键字、运算符
• 函数面板：点选插入任意内置函数，占位参数自动选中
• 编辑体验：变量/函数点选插入、{变量} 整块删除（仅光标在花括号内）、Enter 自动缩进 + 行尾内联 ELSE 拆行、一键格式化、括号配对高亮、当前行高亮
• 实时求值：通过 context 传测试值，输入即算（击键防抖），结果实时显示
• 安全引擎：递归下降解析 + AST 求值，无 eval / new Function，类型严格检查，错误带原文偏移
• 零依赖引擎：engine 子路径无任何依赖，可在 Node / 其他框架直接使用
• 自定义函数：functions prop 注入业务函数，functionSpecs prop 提供签名提示
• 双主题：dark / light，全部样式用 --fe-* CSS 变量，可覆盖

安装

npm install @rockn/vue-formula-editor
# 或
pnpm add @rockn/vue-formula-editor

快速开始

1. 作为 Vue 组件使用

<script setup lang="ts">
import { ref, reactive } from 'vue'
import { FormulaEditor } from '@rockn/vue-formula-editor'
import type { VariableDef } from '@rockn/vue-formula-editor'

const variables: VariableDef[] = [
  { name: '订单金额', type: 'number', description: '订单总金额（元）', required: true },
  { name: '会员等级', type: 'enum', description: '用户会员等级',
    options: [
      { label: '金卡', value: 'GOLD' },
      { label: '黑金', value: 'BLACK' },
    ] },
  { name: '订单', type: 'object', description: '订单对象',
    fields: [{ key: '金额' }, { key: '收货人' }] },
]

const formula = ref(`IF {会员等级} == '金卡' OR {会员等级} == '黑金' THEN
  ROUND({订单金额} * 0.85, 2)
ELSE
  {订单金额}`)

// 测试值：枚举存代码值，公式写标签
const context = reactive({
  订单金额: 520,
  会员等级: 'GOLD',
  订单: { 金额: 520, 收货人: '张三' },
})
</script>

<template>
  <FormulaEditor
    v-model="formula"
    :variables="variables"
    :context="context"
    title="折扣规则"
    subtitle="RULE FORMULA"
  />
</template>

从 1.0.2 起，import { FormulaEditor } from '@rockn/vue-formula-editor' 会自动带上样式。也可显式引入：

import '@rockn/vue-formula-editor/style.css'

2. 单独使用引擎（不依赖 Vue）

import { evaluateFormula, validateFormula } from '@rockn/vue-formula-editor/engine'

// 枚举变量：传变量元数据即可做标签-值解析
const variables = [
  { name: '会员等级', type: 'enum', options: [{ label: '金卡', value: 'GOLD' }] },
]
const result = evaluateFormula(
  `IF {会员等级} == '金卡' THEN {金额} - 20 ELSE {金额}`,
  { 金额: 520, 会员等级: 'GOLD' },
  {},
  variables,
)
if (result.ok) {
  console.log(result.value) // 500
} else {
  console.error(result.error.message, result.error.start, result.error.end)
}

// 静态校验（未定义变量 / 字段存在性 / 函数参数个数）
const check = validateFormula(`{订单}.金额 > 0`, [
  { name: '订单', type: 'object', fields: [{ key: '金额' }] },
])

3. Node / CommonJS

const { evaluateFormula } = require('@rockn/vue-formula-editor/engine')

Props

Events

暴露的实例方法（ref）

const editor = ref<InstanceType<typeof FormulaEditor>>()
// editor.value.validate()  → ValidationResult
// editor.value.evaluate(ctx?) → EvalResult
// editor.value.insertText('{金额}')  → 在光标处插入
// editor.value.focus()

公式语法速览

文档

• 内置函数表
• 公式语法完整参考
• 引擎独立使用（Node / 其他框架）
• 组件 API 参考
• 主题定制
• FAQ / 常见问题

本地开发

npm install
npm run dev        # 演示页 http://localhost:5162
npm run build      # 类型检查 + 演示打包
npm run build:lib  # 组件库打包（dist/，供发布）
npm run typecheck  # 仅类型检查
npm run smoke      # 引擎冒烟测试（152 项断言）
npm pack           # 生成可发布的 tgz（会自动 build:lib）

发布

npm login                # 登录你的 npm 账号（包名为 @rockn/vue-formula-editor）
npm run build:lib        # 构建组件库
npm publish --access public

注意：Windows + Node 24 下 fs.rmSync 与 vite-plugin-dts 存在原生崩溃（STATUS_STACK_BUFFER_OVERRUN）。本项目构建脚本已改用异步 rm 规避，声明文件由 vue-tsc + 手写 types/ 生成。

许可

MIT