RuleExpression

自由文本与特征字段 chip 混排的规则表达式输入。中文惯用名：规则表达式。

稳定本期新增已接入

元信息

字段	值
规范 ID	`component.rule-expression`
名称	RuleExpression
二级分类	业务组件（`business`）
用途	自由文本与特征字段 chip 混排的规则表达式输入
描述	中文惯用名：规则表达式。

预览

静态结构：根节点为相对定位容器，内层 contentEditable 富文本输入框（role="textbox"、aria-multiline、min-h-9 高度随内容增长，placeholder 经 data-placeholder + empty:before 伪元素实现）；选中的特征字段渲染为不可编辑 chip（span 带 dataset.value / dataset.label，内含删除按钮 aria-label="remove-<value>"）；输入时取光标前尾部词（正则 [\w一-龥]+$）对 options 的 label 做不区分大小写 includes 匹配，候选列表（onMouseDown preventDefault 防失焦）支持上下键循环、Enter 选中（无候选时换行）；Backspace / Delete 紧贴 chip 时整体删除。序列化：字段 token 与文本 token（操作符）间以空格分隔，expression 用字段 value、expressionLabel 用 label、sourceField 收集全部字段 value；外部值变化经 lastEmittedRef 跳过自身回环后按 sourceField 顺序在 expression 中定位各字段重建 DOM（候选变更时未匹配字段追加为 chip）。

DSL 结构

DslNode

{
  "type": "RuleExpression",
  "props": {
    "value": "${state.ruleExpr}",
    "placeholder": "输入字段名匹配候选，Enter 选中为 chip",
    "options": [
      {
        "label": "年龄",
        "value": "age"
      },
      {
        "label": "注册时间",
        "value": "registerTime"
      },
      {
        "label": "订单金额",
        "value": "orderAmount"
      }
    ]
  },
  "events": {
    "onChange": {
      "action": "setState",
      "params": {
        "ruleExpr": "${event}"
      }
    }
  }
}

何时用

何时使用

自由文本操作符与特征字段混排的规则表达式输入（如「age > 18 && status == 已激活」中字段以 chip 呈现）。
需要同时拿到表达式串、可读串与选中字段数组（RuleExpressionValue 三元组）。

何时不用

结构化「字段 + 操作符 + 值」行编辑：使用 FieldCondition。
按模板占位符拆分的表达式：使用 ExpressionEditor。

变体

变体	视觉形态	适用场景
text token	自由文本（操作符 / 字面量）	表达式骨架与操作符输入
field chip	不可编辑芯片（label 展示 + 删除按钮）	特征字段插槽，整体删除
候选列表	尾部词匹配的下拉候选，键盘循环 + Enter 选中	按 label 模糊匹配特征字段

API 属性

属性	类型	默认值	说明
`options`	`RuleExpressionOption[]`	[]	特征字段候选：{ label, value }；label 用于匹配与展示，value 写入 sourceField
`value`	`RuleExpressionValue	string	null`
`onChange`	`(value: RuleExpressionValue) => void`	—	值变化回调，回传完整三元组
`placeholder`	`string`	—	占位符（空态伪元素展示）
`disabled`	`boolean`	false	禁用：contentEditable 关闭，chip 不渲染删除按钮
`id`	`string`	—	编辑器 DOM 的 id
`className`	`string`	—	外层容器类名

使用规范

候选字段的 label 用于用户匹配、value 写入 sourceField：label 要可读且尽量唯一，避免同名前缀误匹配。
外部赋值（AI 填充 / 表单重置）按 sourceField 在 expression 中定位回填；两者不一致时以 sourceField 为准。
组件仅做输入与序列化，表达式合法性由上层规则引擎校验。

正例

✓ 规则条件输入：options 传特征字段表，用户输入「age > 18 && status == [chip:已激活]」。
✓ AI 回填：外部赋完整 RuleExpressionValue，编辑器按 sourceField 重建 chip 结构。

反例

✕ 期望 RuleExpression 校验表达式语义（只负责输入与三元组输出）。
✕ 把 field chip 当普通文本逐字删除（紧贴 chip 时 Backspace 整体删除，符合插槽语义）。

Design Token 映射

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