ayou
296f0ae9f6
refactor(backend): 重构 script_js 执行器实现 JavaScript 文件/内联脚本执行 feat(backend): 变量节点支持表达式/引用快捷语法输入 docs: 添加变量节点使用文档说明快捷语法功能 style(frontend): 调整测试面板样式和布局 fix(frontend): 修复测试面板打开时自动关闭节点编辑侧栏 build(backend): 添加 rquickjs 依赖用于 JavaScript 执行
96 lines
5.2 KiB
Markdown
96 lines
5.2 KiB
Markdown
# 变量赋值节点：表达式/引用直输 使用文档
|
||
|
||
## 一、功能概述
|
||
- 变量节点的右值支持三种取值方式：
|
||
- 常量（constant）：数字、字符串、对象、数组等，原样作为值。
|
||
- 引用（ref）：通过路径引用上下文或其他节点的输出。
|
||
- 表达式（expression）：使用 Rhai 表达式，运行时计算出值。
|
||
- 新增“快捷语法”直输能力：即便右值选择为“常量”，也可直接在输入框里写：
|
||
- 表达式直输：以 `ctx.` 或 `ctx[` 开头的字符串按 Rhai 表达式求值。
|
||
- 引用直输：以 `${...}` 包裹的字符串按“引用路径”解析。
|
||
|
||
## 二、使用入口
|
||
- 打开画布，选择“变量”节点，在右侧侧边栏的“赋值行”进行编辑。
|
||
- 侧边栏顶部会有一段提示文字，说明三种取值方式与两种快捷语法。
|
||
- 相关代码位置：
|
||
- 前端：frontend/src/flows/nodes/variable/form-meta.tsx
|
||
- 后端：backend/src/flow/executors/variable.rs
|
||
|
||
## 三、如何输入右值
|
||
- 方式一：常量（默认）
|
||
- 直接输入数字、字符串、对象、数组，例如：`0`、`"hello"`、`{"a":1}`、`[1,2,3]`。
|
||
- 支持“快捷语法”，见下文。
|
||
- 方式二：引用（ref）
|
||
- 切换右值类型为“引用”，通过路径选择器选择 ctx 中已有字段或其他节点输出。
|
||
- 推荐用于团队协作时提升可读性。
|
||
- 方式三：表达式（expression）
|
||
- 切换右值类型为“表达式”，输入 Rhai 表达式，运行时计算。
|
||
- 适合需要计算或条件逻辑的场景。
|
||
|
||
## 四、快捷语法（在“常量”输入框中也可直输）
|
||
- 表达式直输（运行时按 Rhai 表达式执行）
|
||
- 触发规则：字符串以 `ctx.` 或 `ctx[` 开头。
|
||
- 示例：
|
||
- `ctx["user_n"]`
|
||
- `ctx.user.profile.name`
|
||
- `(ctx["score"] ?? 0) + 1`
|
||
- 引用直输（运行时按引用路径取值）
|
||
- 触发规则：字符串以 `${` 开始且以 `}` 结束。
|
||
- 示例：
|
||
- `${user_n}`（引用顶层 `ctx.user_n`）
|
||
- `${nodes.order_node.result.id}`（引用某节点的输出字段）
|
||
- `${orders[0].id}`（支持数组下标）
|
||
|
||
## 五、路径与表达式说明
|
||
- ctx 注入
|
||
- 表达式求值时，会自动注入 `ctx`（流程上下文），可通过点号或中括号访问。
|
||
- 支持典型的运算与空值处理（如 `??`）、算术、比较等。
|
||
- 引用路径（`${...}`）
|
||
- 推荐使用规范路径：顶层字段如 `${a.b}`，节点输出如 `${nodes.node_id.some_field}`。
|
||
- 支持数组访问：`${arr[0].name}`。
|
||
- 仅在完整匹配以 `${` 开始并以 `}` 结束时触发引用直输。
|
||
- 节点输出引用建议
|
||
- 使用 `${nodes.<nodeId>.<字段>}` 的规范形式。
|
||
- 避免模糊/非规范路径，便于协作和排障。
|
||
|
||
## 六、歧义与转义
|
||
- 如需输入“字面量字符串”而非触发快捷语法：
|
||
- 对于以 `ctx.` 或 `ctx[` 开头的文本：在前面加引号或任意非 `c` 字符，例如 `'ctx[1]'` 或前面加一个空格。
|
||
- 对于包含 `${...}` 的文本：只要整串文本不同时满足“以 `${` 开头且以 `}` 结束”，就不会触发引用直输；或者在外层再包一层引号，如 `"abc ${x} def"`。
|
||
- 简单记忆：只有“整串文本”完全匹配触发条件，才会被识别为快捷语法；否则按原样作为字符串。
|
||
|
||
## 七、常见示例
|
||
- 从上下文读取用户名：
|
||
- 左值：`user_name`；右值（常量输入框直输）：`ctx["user_n"]`。
|
||
- 从节点输出读取订单 ID：
|
||
- 左值：`first_order_id`；右值（常量输入框直输）：`${nodes.order_node.result.orders[0].id}`。
|
||
- 进行加一计算：
|
||
- 左值：`score_plus_one`；右值（常量输入框直输）：`(ctx["score"] ?? 0) + 1`。
|
||
- 传统方式（非快捷语法）：
|
||
- 切换到“引用”类型，选择路径 `a.b`。
|
||
- 切换到“表达式”类型，输入 `(ctx["a"] ?? 0) + 1`。
|
||
|
||
## 八、最佳实践
|
||
- 简单取值：优先用“引用”类型或 `${...}` 快捷语法。
|
||
- 复杂逻辑：使用“表达式”类型，便于维护与问题定位。
|
||
- 协作/导出可读性：更倾向使用“引用/表达式”类型（而非快捷语法），或在保存时做规范化（如后续启用）。
|
||
|
||
## 九、导出/保存行为
|
||
- 本次为“运行时增强”：
|
||
- 在“常量”输入框中写的 `ctx[...]` 或 `${...}`，保存/导出时仍表现为普通字符串。
|
||
- 运行时自动识别并解析执行。
|
||
- 如需“保存即规范化”（将快捷语法转换为标准的 ref/expression 类型），可作为后续可选功能启用。
|
||
|
||
## 十、常见问题排查
|
||
- 变量值为空或错误：
|
||
- 检查 `ctx` 中是否存在对应字段（例如 `ctx.user_n` 是否在上游节点或初始上下文中设定）。
|
||
- 检查节点 ID 与输出字段拼写（如 `nodes.<nodeId>`）。
|
||
- 表达式报错多为语法或空值访问，建议在“表达式”类型中尝试以便定位。
|
||
- 表达式返回类型：
|
||
- 应返回可序列化 JSON 值（字符串、数值、布尔、对象、数组或 `null`）。
|
||
- 查看结果：
|
||
- 在变量节点右侧“输出”面板或下游节点输入位置查看结果。
|
||
|
||
## 十一、版本信息
|
||
- 新增：在“常量”输入框中支持表达式/引用快捷直输。
|
||
- 兼容：不影响既有流程配置与执行。 |