feat: 新增 toolbar 按钮列表属性 + 规范化 ToolbarButtonProps 命名

xlorne · claude · xlorne · commit 61241904bc65 · 2026-05-28T16:49:01.000+08:00
- 新增 ScriptCodeEditorProps.toolbar (ToolbarItem[]) 支持以数组形式声明自定义工具栏按钮
- 将 ToolbarButtonProps 移至 types/index.ts 统一管理并添加中文注释
- 规范化属性命名：bg→backgroundColor、hoverBg→hoverBackgroundColor、color→textColor、border→borderColor
- 提取 meta.json 为独立文件，版本号升级至 0.0.4

Co-Authored-By: Claude Opus 4.7 &lt;noreply@anthropic.com&gt;
diff --git a/apps/app-pc/package.json b/apps/app-pc/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@script-example/app-pc",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/apps/app-pc/src/pages/home.tsx b/apps/app-pc/src/pages/home.tsx
@@ -1,8 +1,7 @@
 import { ScriptCodeEditor } from '@coding-script/script-engine';
-import type { ScriptMetadata } from '@coding-script/script-engine';
+import sampleMetadata from './meta.json';
 import { message } from 'antd';
 
-const sampleMetadata: ScriptMetadata = JSON.parse(`{"binds":[{"dataType":"GroovyBindObject","name":"$request"}],"description":"run 函数是脚本的主入口，由引擎在每次任务触发时自动调用。\\n\\n参数说明：\\n  - request: MyScriptRequest 类型，包含本次请求携带的所有业务字段。\\n\\n返回值：Integer 类型，表示本次执行的结果状态码。\\n  - 0 表示成功\\n  - 1 表示参数校验失败\\n  - 2 表示业务逻辑异常\\n\\n注意事项：\\n  1. 函数内部可以通过 $request 访问全局注入对象，获取上下文环境信息（如租户 ID、用户身份等）。\\n  2. 请勿在函数内执行耗时超过 5 秒的同步操作，否则引擎会触发超时中断并记录告警日志。\\n  3. 所有对 request 字段的访问应提前做非空判断，避免 NullPointerException 导致整个任务失败。\\n  4. 若需要调用外部 HTTP 接口，请使用内置的 httpUtil 工具类，而非直接 new URL 连接，以确保连接池复用与超时管控生效。","mainMethod":"run","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":[]}}}`);
 
 const sampleCode = `def run(request){
     println($request.count);
diff --git a/apps/app-pc/src/pages/meta.json b/apps/app-pc/src/pages/meta.json
@@ -0,0 +1,91 @@
+{
+    "binds": [
+        {
+            "dataType": "GroovyBindObject",
+            "name": "$request"
+        }
+    ],
+    "description": "run 函数是脚本的主入口，由引擎在每次任务触发时自动调用。\\n\\n参数说明：\\n  - request: MyScriptRequest 类型，包含本次请求携带的所有业务字段。\\n\\n返回值：Integer 类型，表示本次执行的结果状态码。\\n  - 0 表示成功\\n  - 1 表示参数校验失败\\n  - 2 表示业务逻辑异常\\n\\n注意事项：\\n  1. 函数内部可以通过 $request 访问全局注入对象，获取上下文环境信息（如租户 ID、用户身份等）。\\n  2. 请勿在函数内执行耗时超过 5 秒的同步操作，否则引擎会触发超时中断并记录告警日志。\\n  3. 所有对 request 字段的访问应提前做非空判断，避免 NullPointerException 导致整个任务失败。\\n  4. 若需要调用外部 HTTP 接口，请使用内置的 httpUtil 工具类，而非直接 new URL 连接，以确保连接池复用与超时管控生效。",
+    "mainMethod": "run",
+    "requests": [
+        {
+            "dataType": "MyScriptRequest",
+            "description": "我的测试对象",
+            "name": "request"
+        }
+    ],
+    "returnType": "Integer",
+    "types": {
+        "MyScriptRequest": {
+            "dataType": "MyScriptRequest",
+            "description": "我的测试对象",
+            "fields": [
+                {
+                    "dataType": "int",
+                    "description": "总数量",
+                    "name": "get('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": []
+        }
+    }
+}
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@coding-script/root",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "script-engine",
   "main": "index.js",
   "scripts": {
diff --git a/packages/script-engine/package.json b/packages/script-engine/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@coding-script/script-engine",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "script-engine components",
   "keywords": [
     "coding-script",
diff --git a/packages/script-engine/src/components/index.ts b/packages/script-engine/src/components/index.ts
@@ -1,7 +1,7 @@
 export { themes, SCROLL_CLASS, ensureScrollbarStyle } from './theme-colors';
 export type { ThemeColors } from './theme-colors';
 export { ToolbarButton } from './toolbar-button';
-export type { ToolbarButtonProps } from './toolbar-button';
+export type { ToolbarButtonProps } from '../types';
 export { Toolbar } from './toolbar';
 export type { ToolbarProps } from './toolbar';
 export { ExpandSidebarButton } from './expand-sidebar-button';
diff --git a/packages/script-engine/src/components/toolbar-button.tsx b/packages/script-engine/src/components/toolbar-button.tsx
@@ -1,16 +1,15 @@
 import React, { useState } from 'react';
+import type { ToolbarButtonProps } from '../types';
 
-export interface ToolbarButtonProps {
-  label: React.ReactNode;
-  title: string;
-  bg: string;
-  hoverBg: string;
-  color: string;
-  border: string;
-  onClick: () => void;
-}
-
-export const ToolbarButton: React.FC<ToolbarButtonProps> = ({ label, title, bg, hoverBg, color, border, onClick }) => {
+export const ToolbarButton: React.FC<ToolbarButtonProps> = ({
+  label,
+  title,
+  backgroundColor,
+  hoverBackgroundColor,
+  textColor,
+  borderColor,
+  onClick,
+}) => {
   const [hovered, setHovered] = useState(false);
   return (
     <button
@@ -21,9 +20,9 @@ export const ToolbarButton: React.FC<ToolbarButtonProps> = ({ label, title, bg,
         display: 'inline-flex',
         alignItems: 'center',
         gap: 4,
-        background: hovered ? hoverBg : bg,
-        border: `1px solid ${border}`,
-        color,
+        background: hovered ? hoverBackgroundColor : backgroundColor,
+        border: `1px solid ${borderColor}`,
+        color: textColor,
         cursor: 'pointer',
         fontSize: 12,
         padding: '4px 10px',
diff --git a/packages/script-engine/src/components/toolbar.tsx b/packages/script-engine/src/components/toolbar.tsx
@@ -2,6 +2,7 @@ import React from 'react';
 import { ToolbarButton } from './toolbar-button';
 import { FormatIcon } from './format-icon';
 import { MaximizeIcon, MinimizeIcon } from './fullscreen-icon';
+import type { ToolbarItem } from '../types';
 
 // 锤子图标（编译/构建）
 const HammerIcon: React.FC<{ color: string }> = ({ color }) => (
@@ -42,6 +43,7 @@ export interface ToolbarProps {
   enableFullscreen?: boolean;
   isFullscreen?: boolean;
   onToggleFullscreen?: () => void;
+  toolbar?: ToolbarItem[];
   toolbarExtra?: React.ReactNode;
 }
 
@@ -57,6 +59,7 @@ export const Toolbar: React.FC<ToolbarProps> = ({
   enableFullscreen,
   isFullscreen,
   onToggleFullscreen,
+  toolbar,
   toolbarExtra,
 }) => {
   const isDark = theme === 'dark';
@@ -105,10 +108,10 @@ export const Toolbar: React.FC<ToolbarProps> = ({
         <ToolbarButton
           label={isDark ? '🌞 浅色模式' : '🌙 深色模式'}
           title={isDark ? '切换到浅色主题' : '切换到深色主题'}
-          bg={btnBg}
-          hoverBg={btnHoverBg}
-          color={toolbarText}
-          border={borderColor}
+          backgroundColor={btnBg}
+          hoverBackgroundColor={btnHoverBg}
+          textColor={toolbarText}
+          borderColor={borderColor}
           onClick={handleThemeToggle}
         />
       )}
@@ -122,10 +125,10 @@ export const Toolbar: React.FC<ToolbarProps> = ({
             </>
           }
           title="格式化代码"
-          bg={isDark ? '#1e3a5f' : '#e6f4ff'}
-          hoverBg={isDark ? '#264a73' : '#bae0ff'}
-          color={isDark ? '#61afef' : '#1677ff'}
-          border={isDark ? '#1e3a5f' : '#91caff'}
+          backgroundColor={isDark ? '#1e3a5f' : '#e6f4ff'}
+          hoverBackgroundColor={isDark ? '#264a73' : '#bae0ff'}
+          textColor={isDark ? '#61afef' : '#1677ff'}
+          borderColor={isDark ? '#1e3a5f' : '#91caff'}
           onClick={onFormat}
         />
       )}
@@ -139,10 +142,10 @@ export const Toolbar: React.FC<ToolbarProps> = ({
             </>
           }
           title="编译并验证脚本"
-          bg={isDark ? '#2d5a27' : '#e6f4e5'}
-          hoverBg={isDark ? '#3a7033' : '#d4ecd3'}
-          color={isDark ? '#98c379' : '#389e0d'}
-          border={isDark ? '#2d5a27' : '#b7eb8f'}
+          backgroundColor={isDark ? '#2d5a27' : '#e6f4e5'}
+          hoverBackgroundColor={isDark ? '#3a7033' : '#d4ecd3'}
+          textColor={isDark ? '#98c379' : '#389e0d'}
+          borderColor={isDark ? '#2d5a27' : '#b7eb8f'}
           onClick={onCompile}
         />
       )}
@@ -160,14 +163,28 @@ export const Toolbar: React.FC<ToolbarProps> = ({
             </>
           }
           title={isFullscreen ? '退出全屏（ESC）' : '全屏显示'}
-          bg={isDark ? '#3a2d5a' : '#f3e8ff'}
-          hoverBg={isDark ? '#4a3d6a' : '#e9d5ff'}
-          color={isDark ? '#c678dd' : '#722ed1'}
-          border={isDark ? '#3a2d5a' : '#d3adf7'}
+          backgroundColor={isDark ? '#3a2d5a' : '#f3e8ff'}
+          hoverBackgroundColor={isDark ? '#4a3d6a' : '#e9d5ff'}
+          textColor={isDark ? '#c678dd' : '#722ed1'}
+          borderColor={isDark ? '#3a2d5a' : '#d3adf7'}
           onClick={() => onToggleFullscreen?.()}
         />
       )}
 
+      {/* 自定义工具栏按钮列表 */}
+      {toolbar?.map((item) => (
+        <ToolbarButton
+          key={item.key}
+          label={item.label}
+          title={item.title}
+          backgroundColor={item.backgroundColor}
+          hoverBackgroundColor={item.hoverBackgroundColor}
+          textColor={item.textColor}
+          borderColor={item.borderColor}
+          onClick={item.onClick}
+        />
+      ))}
+
       {/* 自定义工具栏内容 */}
       {toolbarExtra}
     </div>
diff --git a/packages/script-engine/src/script-code.tsx b/packages/script-engine/src/script-code.tsx
@@ -171,6 +171,7 @@ export const ScriptCodeEditor: React.FC<ScriptCodeEditorProps> = (props) => {
     enableFormat,
     enableCompile,
     enableFullscreen,
+    toolbar,
     toolbarExtra,
     options = {},
   } = props;
@@ -387,6 +388,7 @@ export const ScriptCodeEditor: React.FC<ScriptCodeEditorProps> = (props) => {
         enableFullscreen={enableFullscreen}
         isFullscreen={isFullscreen}
         onToggleFullscreen={() => setIsFullscreen((prev) => !prev)}
+        toolbar={toolbar}
         toolbarExtra={toolbarExtra}
       />
 
diff --git a/packages/script-engine/src/types/index.ts b/packages/script-engine/src/types/index.ts
@@ -1,5 +1,31 @@
 import type React from 'react';
 
+// ── 工具栏按钮 ────────────────────────────────────────────────
+
+/** 工具栏按钮属性 */
+export interface ToolbarButtonProps {
+  /** 按钮内容（支持 ReactNode，可包含图标 + 文字） */
+  label: React.ReactNode;
+  /** 鼠标悬停提示文字（原生 title 属性） */
+  title: string;
+  /** 按钮背景色 */
+  backgroundColor: string;
+  /** 鼠标悬停时的背景色 */
+  hoverBackgroundColor: string;
+  /** 文字颜色 */
+  textColor: string;
+  /** 边框颜色 */
+  borderColor: string;
+  /** 点击回调 */
+  onClick: () => void;
+}
+
+/** 工具栏自定义按钮项（用于 toolbar 数组） */
+export interface ToolbarItem extends ToolbarButtonProps {
+  /** 唯一标识（React key） */
+  key: string;
+}
+
 // ── 脚本元数据 Schema ──────────────────────────────────────────
 
 /** 函数参数信息 */
@@ -121,6 +147,8 @@ export interface ScriptCodeEditorProps {
   onCompile?: (code: string) => void;
 
   // ── 自定义工具栏内容 ──────────────────────────────────────
+  /** 工具栏自定义按钮列表（渲染在内置按钮之后） */
+  toolbar?: ToolbarItem[];
   /** 工具栏额外内容（渲染在内置按钮之后，任意 React 节点） */
   toolbarExtra?: React.ReactNode;
 

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@script-example/app-pc",`
`3`		`- "version": "0.0.3",`
	`3`	`+ "version": "0.0.4",`
`4`	`4`	`"private": true,`
`5`	`5`	`"type": "module",`
`6`	`6`	`"scripts": {`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@coding-script/root",`
`3`		`- "version": "0.0.3",`
	`3`	`+ "version": "0.0.4",`
`4`	`4`	`"description": "script-engine",`
`5`	`5`	`"main": "index.js",`
`6`	`6`	`"scripts": {`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@coding-script/script-engine",`
`3`		`- "version": "0.0.3",`
	`3`	`+ "version": "0.0.4",`
`4`	`4`	`"description": "script-engine components",`
`5`	`5`	`"keywords": [`
`6`	`6`	`"coding-script",`