|
1 | 1 | # Script Engine |
2 | 2 |
|
3 | | -一个基于 React 的规则引擎框架,基于groovy语言实现。 |
| 3 | +基于 React + CodeMirror 6 的 Groovy 脚本编辑器组件库，提供语法高亮、动态类型自动补全、属性面板等功能。 |
4 | 4 |
|
| 5 | +## 功能特性 |
5 | 6 |
|
6 | | -## Script元数据结构 |
| 7 | +- **Groovy 语法高亮**：基于 CodeMirror 6，支持完整的 Groovy/Java 语法着色 |
| 8 | +- **动态类型自动补全**：基于 `ScriptMetadata` 提供变量名补全和点号链式访问补全（如 `request.test.name`） |
| 9 | +- **Groovy 语法提示**：内置 `if`/`for`/`while`/`println`/`return` 等常用 Groovy 语法片段 |
| 10 | +- **属性面板**：右侧侧边栏展示主函数签名、变量、数据类型（字段和方法），支持折叠/展开和拖拽调节宽度 |
| 11 | +- **主题切换**：暗色/亮色两套主题，编辑器、补全弹窗、属性面板同步切换 |
| 12 | +- **编译验证**：工具栏提供编译验证按钮（通过回调函数对接后端 API） |
| 13 | +- **热更新**：主题和 metadata 变化时通过 Compartment 热更新，不重建编辑器，不丢失用户输入 |
7 | 14 |
|
| 15 | +## 安装 |
| 16 | + |
| 17 | +```bash |
| 18 | +npm install @coding-script/script-engine |
| 19 | +# 或 |
| 20 | +pnpm add @coding-script/script-engine |
8 | 21 | ``` |
9 | | -{"binds":[{"dataType":"GroovyBindObject","name":"$request"}],"requests":[{"dataType":"MyScriptRequest","description":"我的测试对象","name":"request"}],"returnType":"Integer","types":{"MyScriptRequest":{"dataType":"MyScriptRequest","description":"我的测试对象","fields":[{"dataType":"int","description":"总数量","name":"count"},{"dataType":"MyTest","description":"test","name":"test"}],"functions":[{"description":"是否匹配","name":"isSupport","parameters":[{"dataType":"int","description":"描述信息","name":"count"}]}]},"Integer":{"dataType":"Integer","fields":[],"functions":[]},"boolean":{"dataType":"boolean","fields":[],"functions":[]},"Long":{"dataType":"Long","fields":[],"functions":[]},"String":{"dataType":"String","fields":[],"functions":[]},"MyTest":{"dataType":"MyTest","description":"test","fields":[{"dataType":"Long","description":"id","name":"id"},{"dataType":"String","description":"name","name":"name"}],"functions":[]},"int":{"dataType":"int","fields":[],"functions":[]}}} |
10 | | -``` |
11 | 22 |
|
12 | | -## 实例使用代码 |
| 23 | +## 基础用法 |
| 24 | + |
| 25 | +```tsx |
| 26 | +import { ScriptCodeEditor } from '@coding-script/script-engine'; |
| 27 | +import type { ScriptMetadata } from '@coding-script/script-engine'; |
| 28 | + |
| 29 | +const metadata: ScriptMetadata = { |
| 30 | + mainMethod: 'run', |
| 31 | + returnType: 'Integer', |
| 32 | + binds: [ |
| 33 | + { dataType: 'GroovyBindObject', name: '$request' }, |
| 34 | + ], |
| 35 | + requests: [ |
| 36 | + { dataType: 'MyScriptRequest', description: '请求参数', name: 'request' }, |
| 37 | + ], |
| 38 | + types: { |
| 39 | + MyScriptRequest: { |
| 40 | + dataType: 'MyScriptRequest', |
| 41 | + description: '请求参数类型', |
| 42 | + fields: [ |
| 43 | + { dataType: 'int', description: '总数量', name: 'count' }, |
| 44 | + { dataType: 'MyTest', description: '测试对象', name: 'test' }, |
| 45 | + ], |
| 46 | + functions: [ |
| 47 | + { |
| 48 | + name: 'isSupport', |
| 49 | + description: '是否匹配', |
| 50 | + parameters: [{ dataType: 'int', description: '数量', name: 'count' }], |
| 51 | + }, |
| 52 | + ], |
| 53 | + }, |
| 54 | + MyTest: { |
| 55 | + dataType: 'MyTest', |
| 56 | + description: '测试对象', |
| 57 | + fields: [ |
| 58 | + { dataType: 'Long', description: 'id', name: 'id' }, |
| 59 | + { dataType: 'String', description: '名称', name: 'name' }, |
| 60 | + ], |
| 61 | + functions: [], |
| 62 | + }, |
| 63 | + Integer: { dataType: 'Integer', fields: [], functions: [] }, |
| 64 | + String: { dataType: 'String', fields: [], functions: [] }, |
| 65 | + Long: { dataType: 'Long', fields: [], functions: [] }, |
| 66 | + int: { dataType: 'int', fields: [], functions: [] }, |
| 67 | + }, |
| 68 | +}; |
13 | 69 |
|
| 70 | +function App() { |
| 71 | + const [theme, setTheme] = useState<'dark' | 'light'>('dark'); |
| 72 | + |
| 73 | + return ( |
| 74 | + <ScriptCodeEditor |
| 75 | + value="def run(request){\n return request.count;\n}\n" |
| 76 | + title="Groovy 脚本编辑器" |
| 77 | + theme={theme} |
| 78 | + metadata={metadata} |
| 79 | + onThemeChange={(next) => setTheme(next)} |
| 80 | + onChange={(code) => console.log('代码变化:', code)} |
| 81 | + onCompile={(code) => console.log('编译验证:', code)} |
| 82 | + options={{ minHeight: 400, maxHeight: 500 }} |
| 83 | + /> |
| 84 | + ); |
| 85 | +} |
14 | 86 | ``` |
15 | | -def run(request){ |
16 | | - println($request.count); |
17 | | - return request.count; |
| 87 | + |
| 88 | +## Props |
| 89 | + |
| 90 | +| 属性 | 类型 | 默认值 | 说明 | |
| 91 | +|---|---|---|---| |
| 92 | +| `value` | `string` | `undefined` | 代码内容 | |
| 93 | +| `readonly` | `boolean` | `false` | 是否只读 | |
| 94 | +| `onChange` | `(value: string) => void` | `undefined` | 代码变化回调 | |
| 95 | +| `onCompile` | `(code: string) => void` | `undefined` | 编译验证回调 | |
| 96 | +| `onThemeChange` | `(theme: 'dark' \| 'light') => void` | `undefined` | 主题切换回调 | |
| 97 | +| `placeholder` | `string` | `'请输入 Groovy 脚本...'` | 空内容占位符 | |
| 98 | +| `theme` | `'dark' \| 'light'` | `'dark'` | 当前主题 | |
| 99 | +| `title` | `string` | `undefined` | 工具栏标题（可选） | |
| 100 | +| `metadata` | `ScriptMetadata` | `undefined` | 脚本元数据，提供后启用属性面板和自动补全 | |
| 101 | +| `defaultSidebarOpen` | `boolean` | `metadata != null` | 属性面板默认是否展开 | |
| 102 | +| `options.fontSize` | `number` | `14` | 字体大小（px） | |
| 103 | +| `options.minHeight` | `number` | `300` | 编辑器最小高度（px） | |
| 104 | +| `options.maxHeight` | `number` | `300` | 编辑器最大高度（px） | |
| 105 | + |
| 106 | +## ScriptMetadata 数据结构 |
| 107 | + |
| 108 | +```typescript |
| 109 | +interface ScriptMetadata { |
| 110 | + /** 主函数名称 */ |
| 111 | + mainMethod: string; |
| 112 | + /** 注入变量（如 $request，name 含 $ 前缀） */ |
| 113 | + binds: ScriptBindInfo[]; |
| 114 | + /** 主函数参数 */ |
| 115 | + requests: ScriptRequestInfo[]; |
| 116 | + /** 主函数返回类型（可选） */ |
| 117 | + returnType?: string; |
| 118 | + /** 所有可用类型定义（含基础类型如 Integer/String） */ |
| 119 | + types: Record<string, ScriptTypeInfo>; |
| 120 | +} |
| 121 | + |
| 122 | +interface ScriptTypeInfo { |
| 123 | + dataType: string; |
| 124 | + description?: string; |
| 125 | + fields: ScriptFieldInfo[]; |
| 126 | + functions: ScriptFunctionInfo[]; |
| 127 | +} |
| 128 | + |
| 129 | +interface ScriptFieldInfo { |
| 130 | + name: string; |
| 131 | + dataType: string; |
| 132 | + description?: string; |
| 133 | +} |
| 134 | + |
| 135 | +interface ScriptFunctionInfo { |
| 136 | + name: string; |
| 137 | + parameters: ScriptParameterInfo[]; |
| 138 | + description?: string; |
| 139 | + returnType?: string; |
18 | 140 | } |
19 | 141 |
|
| 142 | +interface ScriptParameterInfo { |
| 143 | + name: string; |
| 144 | + dataType: string; |
| 145 | + description?: string; |
| 146 | +} |
| 147 | + |
| 148 | +interface ScriptBindInfo { |
| 149 | + name: string; |
| 150 | + dataType: string; |
| 151 | + description?: string; |
| 152 | +} |
| 153 | + |
| 154 | +interface ScriptRequestInfo { |
| 155 | + name: string; |
| 156 | + dataType: string; |
| 157 | + description?: string; |
| 158 | +} |
| 159 | +``` |
| 160 | + |
| 161 | +> **注意**：`metadata` 必须是解析后的 JavaScript 对象，不能是 JSON 字符串。如果从 API 获取的是 JSON 字符串，需要先 `JSON.parse()` 再传入。 |
| 162 | +
|
| 163 | +## 自动补全 |
| 164 | + |
| 165 | +提供 metadata 后，编辑器支持以下补全能力： |
| 166 | + |
| 167 | +| 输入 | 补全内容 | |
| 168 | +|---|---| |
| 169 | +| `re` | 弹出 `request`、`$request` 等变量 | |
| 170 | +| `request.` | 弹出 `count`、`test`、`isSupport` 等字段和方法 | |
| 171 | +| `request.test.` | 弹出 `id`、`name` 等链式访问成员 | |
| 172 | +| `if` / `for` / `while` | 弹出 Groovy 语法片段（含 tab-stop 占位符） | |
| 173 | + |
| 174 | +不提供 metadata 时，仅启用 Groovy 关键字和语法片段补全。 |
| 175 | + |
| 176 | +## 本地开发 |
| 177 | + |
| 178 | +```bash |
| 179 | +# 安装依赖 |
| 180 | +pnpm install |
| 181 | + |
| 182 | +# 启动库 watch 模式（终端 1） |
| 183 | +pnpm run watch:script-engine |
| 184 | + |
| 185 | +# 启动演示应用（终端 2） |
| 186 | +pnpm run dev:app-pc |
20 | 187 | ``` |
21 | 188 |
|
| 189 | +演示应用访问 http://localhost:3000 |
| 190 | + |
| 191 | +## 技术栈 |
22 | 192 |
|
| 193 | +- **编辑器**：[CodeMirror 6](https://codemirror.net/)（`@codemirror/view`、`state`、`autocomplete`、`lang-java`、`theme-one-dark`） |
| 194 | +- **构建工具**：[Rslib](https://rslib.rs/)（库）+ [Rsbuild](https://rsbuild.dev/)（演示应用） |
| 195 | +- **包管理**：pnpm monorepo（workspaces） |
| 196 | +- **UI**：纯 CSS-in-JS（React `style` 对象），库本身不依赖 Ant Design |
23 | 197 |
|
| 198 | +## License |
24 | 199 |
|
| 200 | +MIT |
0 commit comments