ScriptEditor

Ace 脚本编辑器：语法高亮与自定义函数/变量联想。中文惯用名：脚本编辑器。

稳定本期新增已接入

元信息

字段	值
规范 ID	`component.script-editor`
名称	ScriptEditor
二级分类	业务组件（`business`）
用途	Ace 脚本编辑器：语法高亮与自定义函数/变量联想
描述	中文惯用名：脚本编辑器。

预览

静态结构：外层容器内嵌 Ace 编辑器（挂载时动态 import ace-builds，规避 SSR；加载失败静默保留空容器）——theme textmate、showPrintMargin=false、highlightActiveLine、tabSize=4 软 Tab、enableLiveAutocompletion + enableSnippets，自定义 completer 由 buildScriptCompletions(functions, variables) 构建（函数以 snippet 补全、变量直接补全名称），worker 关闭（避免 URL 404）；语言模式按需加载，本期仅 python（mode + snippets 一并注册），未知值回退纯文本；受控模式：外部 value 变化仅当与编辑器内容不同才 setValue（避免光标跳动），编辑器 change 经 ref 调用最新 onChange；functions / variables 变化以 setOptions 热更新联想；readonly 时只读 + 外层 bg-muted；空内容时渲染绝对定位占位覆盖层（pointer-events-none）；卸载时 destroy 编辑器。

DSL 结构

DslNode

{
  "type": "ScriptEditor",
  "props": {
    "value": "${state.script}",
    "language": "python",
    "height": 200,
    "placeholder": "输入脚本，函数 / 变量自动联想",
    "functions": [
      {
        "name": "SUM",
        "description": "求和",
        "parameters": [
          {
            "name": "field",
            "type": "string"
          }
        ]
      }
    ],
    "variables": [
      {
        "name": "order_amount",
        "type": "number",
        "description": "订单金额"
      }
    ]
  },
  "events": {
    "onChange": {
      "action": "setState",
      "params": {
        "script": "${event}"
      }
    }
  }
}

何时用

何时使用

表单内脚本 / 代码输入：Python 语法高亮、行号、自动补全。
需要自定义函数（snippet 补全，如 SUM(${1:field})）与变量名联想。

何时不用

简短表达式（单行、无语法高亮需求）：使用 Input / Textarea 或 ExpressionEditor。
只读代码展示（无编辑需求）：使用 CodeBlock。

变体

变体	视觉形态	适用场景
python 模式	语法高亮 + python snippets	脚本 / 表达式输入（默认）
纯文本回退	无高亮纯文本	未注册的语言值
readonly 只读	只读编辑器 + 灰底	脚本回显
自定义联想	函数 snippet / 变量名补全	平台函数（SUM / COUNT…）与变量提示

API 属性

属性	类型	默认值	说明
`id`	`string`	—	编辑器容器 DOM 的 id
`value`	`string`	—	受控值（代码内容）
`onChange`	`(value: string) => void`	—	内容变化回调（Ace change 事件）
`placeholder`	`string`	—	内容为空时的占位覆盖层
`language`	`string`	'python'	语法模式；未知值回退纯文本
`functions`	`ScriptFunctionDef[]`	—	自定义函数联想：{ name, description?, parameters? }，以 snippet 补全
`variables`	`ScriptVariableDef[]`	—	自定义变量联想：{ name, type?, description? }
`readonly`	`boolean`	false	只读模式（外层加灰底）
`height`	`number`	160	编辑器高度（px）
`className`	`string`	—	外层容器类名

使用规范

平台自定义函数经 functions 以 snippet 形式联想（含参数占位符），避免用户记函数签名。
语言模式按需注册（MODE_LOADERS），新增语言需同时注册 mode 与 snippets 模块（避免按 URL 404）。
受控值变更尽量小步提交：组件已做内容差异比对，外层无需节流。

正例

✓ 指标计算脚本：language=python + functions=[{ name: "SUM", parameters: [{ name: "field" }] }]，输入 SUM( 即得 snippet 补全。
✓ 回显只读：readonly + value 展示已保存脚本。

反例

✕ 把 ScriptEditor 用于单行表达式输入（应使用 ExpressionEditor / Input）。
✕ 期望未注册的语言自动高亮（本期仅 python，其余回退纯文本）。

Design Token 映射

不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。