af —— 交互流(.af)与 action 全表

读者:做工具的用户,和替他干活的 AI。两者读同一份。

它是什么

.af 是用户动了手指之后跑的那条流:点组件、长按编辑、页面上按一个按钮、提交一张表单。它能做副作用 —— 弹 toast、震一下、开页面、写本地数据、把参数写回组件、让组件重新取数。

它和取数流 .df 是同一套 ActionFlow 引擎、同一套写法,分界只有一条:.df 是白名单子集,零 UI、零导航、零 App 注入能力;.af 是全集。取数写 .df,副作用写 .af,后缀就是能力声明,写错后缀App 里会直接回「flow not found」(check G12b)。取数流的写法见 numable docs df。

引擎按载体再切一刀,这刀比后缀更硬:

所以「取数的时候顺手弹个 toast / 顺手刷新一下自己」是做不到的,写了不会报错,只是那一步不存在。

最小可用示例

页面里按「保存」跑的那条流(page/flow/save.af)。写盘 + 让本包的组件重新取数,这是最常见的一种 .af。

{
  "version": 1,
  "actions": [
    { "action": "ui.haptic", "params": { "type": "tap" } },
    { "op": "set", "props": { "key": "lk", "value": "log_${id}" } },
    { "op": "set", "props": { "key": "sk", "value": "stat_${id}" } },
    { "action": "data.set", "params": { "key": "${lk}", "value": "${log}" } },
    { "action": "data.set", "params": { "key": "${sk}", "value": "${stat}" } },
    { "action": "data.set", "params": { "key": "agg", "value": "${agg}" } },
    { "action": "widget.refresh" }
  ]
}

逐行:ui.haptic 在 actions[0](按下到画面变化之间没有别的反馈)· op:set 先把动态键名落成变量 · 三个 data.set 写盘 · 最后 widget.refresh 让这个包的组件真取数重渲。所有写盘动作必须排在 widget.refresh 之前,否则刷新读到的是旧盘。

文件格式

{
  "version": 1,                                  // 必填,恒 1
  "inputs": ["secid", "period"],                 // 可选,声明期望入参,只做静态校验
  "i18n": { "zh-CN": { "k": "文案" },            // 可选,本文件自己的 A 表,用 ${@i18n.k} 取
            "en-US": { "k": "text" } },
  "actions": [ /* 步骤数组 */ ]
}

_note 字段可写在任何位置,是给人和 AI 的注释,引擎忽略。

步骤的三种形状

复合步写成 {"op":"concurrent"} 会被整块静默跳过 —— 流照样 success,里面一个 action 都没跑。

policy(可选,写在步骤上):wait(默认,等它完成)/ detach(不等)/ skip(跳过)。

params 递归求值:字符串走表达式引擎,对象的键也求值,数组逐元素求值;@[…] 整值引用求不出来时按字面量透传。表达式与方法见 numable docs methods。

id = 结果键

带 id 的 action 步,结果以 id 为键写进作用域,后面用 ${id.xxx} 取。两种情况结果被丢弃:没写 id;结果是 null 或 undefined。

后者是最常见的静默失效来源:data.get 取不到值又没写 default,那个键根本不出现在作用域里,下游 ${k} 恒空且不报错。data.get 一律写 default。

除 concurrent 分支外,写入后下一步立刻可见。

内联 flow 绑定的四种形态

节点的 depends、events 的值、onSubmit 的绑定,都用这四种形态之一:

"depends": [
  { "flow": "@[file://page/flow/quote.df]", "params": { "secid": "${secid}" } },  // ① 文件引用 + 入参(推荐)
  { "flow": { "version": 1, "actions": [ … ] }, "params": { "x": "${y}" } },      // ② 内联对象
  "@[file://page/flow/noop.df]",                                                   // ③ 裸引用,入参 = {}
  { "op": "set", "props": { "key": "cards", "value": [] } }                        // ④ 裸内联单步
]

flow 写成数组无效。裸引用形态传空入参 —— 需要入参却写成③,流仍 success、组件渲一片 --(check G12c)。不参与取数但要显示的键(比如城市名)也必须列进 params。

@[file://…] 的路径基准跟载体走

基准写错的表现是「点了没反应」,App 里读不到 actions 就静默结束(check G12d)。

action 全表

系统内置(.df 一列 = 渲染流 / 取数流里也能用)

data.* 没有 scope 参数,写了静默忽略;数据域按包隔离,由宿主注入身份。

页面里要 loading / toast,用下面 App 注入的 ui.showLoading / ui.toast(能拿到文案与类型),别用内置的 showLoading / toast。

⚠️ 这两个 toast 参数名和取值都不一样,写混了不报错、只是没样式:

也就是说 ui.toast 没有 warning 这一档,而内置 toast 没有 info;把 style 写到 ui.toast 上,或者把 type 写到内置 toast 上,都会被当成没写、落回默认样式。事件流里一律用 ui.toast。

App 注入(只在事件流里存在)

「空转」= 调得到但什么都不做(组件宿主上没有页面可改)。

别再写的名字

operation 节点

op:include 是这张表里唯一一个「写了也不会跑」的:流引擎不实现它的展开,那一步恒展开成零个子步骤,而整条流照报 success。想复用公共步骤,只有两条路:把那几步复制过去,或者拆成独立的 .df,在 depends 里多绑一条(见 numable docs xwidget 的多条 depends)。

两条必须记住的:

1. op:if 的条件键是 props.val。 写成 cond 的后果是条件恒假、整个分支体静默不执行、流仍报 success、分支外的动作全部正常 —— 只有分支里的写盘什么都没发生(check G30)。
2. op:if 分支里 op:set 出来的键,出了分支取不到。 分支退出会恢复外层绑定。所以:算值用表达式嵌套 if::,op:if 只用来分派动作。

events:哪里能挂 .af

.xwidget 的 onClick / onEdit

events 只有这两个键,写在 .xwidget 的外壳上(不在 canvas 里)。字段细节见 numable docs xwidget。

"events": {
  "onClick": "/detail?secid=${secid}",
  "onEdit": "/pick?ref=board&base=${base}"
}

值解析后是字符串 → 当导航串走;是结构体(@[file://x.af] 或内联对象)→ 当 ActionFlow 跑。不许写裸的 flow 文件名。

四种可用写法:

• onEdit 走导航时必须是裸路由 path(/pick),不能写 numable:// 形态 —— App 里拿这个串逐字匹配 router.json,匹配不上就开出空白页且不报错(check G12d)。onClick 两种形态都行。
• onEdit 的目标页型 html / xpage / form 都可以,但必须证明得出写回(check G12e)。
• af 形态的路径基准是 xWidget/。
• 导航串里的 ${…} 只取顶层标量;作用域从低到高:外壳 params → 实例 params → 本地数据 → depends 结果集。

整组件 onClick / onEdit 跑 af 时的入参 = 这个组件的实例 params + @i18n(只有这个 af 文件自己的表)+ @app,没有 @event。 组件整体被点,没有「哪个元素」可言。

@event.*(XPage 节点 / RCN cell / 表单)

@i18n 的取法见 numable docs i18n。

常用原语

widget.refresh —— 让组件真取数

{ "action": "widget.refresh", "params": { "scope": "bundle", "widgetId": "streak", "desktop": true } }

• 语义 = 清取数计时 + 真取数 + 重渲,不是 reload。reload 会命中渲染图缓存,等于什么都没刷。
• 返回 { refreshed: <张数> }。匹配到 0 张是成功,不是错误。
• 5000 毫秒节流窗内再调,直接返回 { refreshed: 0 }。
• 跨包无效;渲染流里硬拒;.df 里不可用。
• 错误(no_brick_context / no_bundle_context / unknown_scope / widget_not_in_bundle)会让整条流失败。
• 写盘之后必须调它,且所有 data.set 排在它前面(人审;run 层看不出来,现象是「设置改了组件不变」)。

widget.updateParams —— 把值写回组件实例

{ "action": "widget.updateParams", "params": { "city": "${r.value.value}", "sub": null } }

• 顶层对象就是要合并的 params,不套一层。逐键 merge:给值 = 覆盖,给 null = 删键、回落 .xwidget 里的默认值。
• 值必须是标量,并且会被规范成标准形:1.0 → "1"、true → "true"。传对象或数组直接报错(non_scalar_value)。
• 返回 { params };失败(no_brick_context / non_scalar_value / brick_not_found)让流失败。
• 只有 onEdit 的 af 里调得到。 整组件 onClick 的 flow 拿不到组件实例上下文,调它必失败。html 参数页用 JS 桥的 xbridge.updateParams(见 numable docs bridge),其余页型用这个 action。
• 渲染流硬拒。

典型串法:onEdit: "@[file://flow/edit.af]" → singleValue 或 startPageForResult 收一个值 → widget.updateParams 写回。整个过程不需要做一张页。

startPageForResult —— 开一张页,等它回值

{
  "id": "picked",
  "action": "startPageForResult",
  "params": { "page": "/for-result-pick", "container": "sheet", "params": { "secid": "${secid}" } }
}

输出恒为 { value, cancelled },读 ${picked.value.xxx} 与 ${picked.cancelled}。

xpage / html / form 三种页型通吃。子页回值的写法:

用户按 ✕、‹、点遮罩、系统返回手势 = 取消,不经过 onSubmit,宿主直接兑现 { value: null, cancelled: true }。取消是正常路径,一定要判 cancelled 再用 value。

ui.confirm —— 二次确认,拿一个布尔

{ "id": "ok", "action": "ui.confirm",
  "params": { "title": "清空全部记录?", "message": "这一步不可撤销", "okText": "清空", "destructive": true } }

后面直接拿 ${ok} 进 op:if:

{ "op": "if", "props": { "val": "${ok}" },
  "items": [ { "action": "data.clear" }, { "action": "widget.refresh" } ] }

• ok 是真布尔,直接写进 props.val 就行。
• ⚠️ 别把它先转成数字再判。props.val 的真值口径很窄:布尔取自身,字符串只认 1 / true / on / yes / y(不分大小写),数字只有恰好等于 1 才算真(2、-1 都是假)。算出个 2 就以为「有货」的写法会静默走进假分支,而流照报成功。
• destructive: true 把确认钮标红,用在删除这类做完回不去的操作上。
• 它等用户操作,期间不计入事件流的 15 秒超时。

ui.alert —— 单钮提示,等用户点掉

{ "action": "ui.alert", "params": { "title": "今天已经打过组件了", "message": "明天再来" } }

没有返回值。要「告诉一句就走」用 ui.toast(不打断);要用户明确点头才继续,才用 ui.alert。

ui.presentSheet —— 贴底弹一张子页

{ "id": "r", "action": "ui.presentSheet",
  "params": { "source": "/detail", "params": { "id": "${id}" } } }

返回的是子页 page.setResult 传回来的那个对象本身,子页被关掉则是 null。它是 startPageForResult 的底层原语 —— 一般写 startPageForResult:那个的返回值统一成 { value, cancelled },不用自己判 null 到底是「取消了」还是「回了个空」。

nav.openForResult —— 压栈打开一张页,等它回值

{ "id": "picked", "action": "nav.openForResult",
  "params": { "url": "/city-pick", "params": { "cur": "${city}" } } }

同样是 startPageForResult 的底层原语,只是恒压栈(相当于 container: "page"),返回值也是裸的结果 / null。新写的流一律用 startPageForResult,这两个原语留着是给已有的包。

xpage.setState 与 patchState —— 改页面数据

两个的入参都是「整个 params 就是那张表」,不套 value:

{ "action": "xpage.patchState", "params": { "tab": "week", "loading": "0" } }

最常撞的坑是拿 setState 当 patchState 用:改一个 tab 值,把页面上其它键一起清空,现象是别处的内容突然全空了。

改完 state 再决定重画多少:

{ "action": "xpage.patchState", "params": { "tab": "week" } }

{ "action": "xpage.redraw", "params": { "id": "chart" } }

还有一个 xpage.const:它写的是这条流自己的作用域顶层变量(后面的步骤用 ${名} 读),不写进页面 state,页面上的节点看不见。要页面看得见就用 patchState。

input.* —— 命令式操作输入框

input 节点的值平时是自己静默写进页面 state 的(键名 = props.bindKey,不写就是节点 id)。下面五个是「用流去动它」:

{ "action": "input.focus",     "params": { "id": "kw" } }

{ "action": "input.setValue",  "params": { "id": "kw", "value": "${@i18n.preset}" } }

{ "action": "input.clear",     "params": { "id": "kw" } }

{ "action": "input.selectAll", "params": { "id": "kw" } }

{ "action": "input.blur",      "params": { "id": "kw" } }

• id 是节点 id,不是 bindKey。
• input.setValue 同时更新 bindKey 指向的 state,效果和用户自己敲进去一样。
• 没有输入宿主的地方(组件事件流)这五个都是空转,不报错。
• 收键盘另有一个 ui.dismissKeyboard(无参),它不改值、只收键盘:{ "action": "ui.dismissKeyboard" }。

widget.pick —— 打开「加到仪表盘」面板

{ "action": "widget.pick",
  "params": { "items": [ { "id": "today", "params": { "habit": "water" } }, { "id": "streak" } ] } }

• items 省略 = 列本包全部组件;写了就只列这几个,各带各的实例参数。
• id 是 xWidget/<名>.xwidget 的文件名(不含后缀)。
• 一个 id 都对不上时这一步会失败(no_matching_widget),不会回落成「列全部」。所以改了组件文件名记得同步改这里。
• 返回 { listed: <列出几张> }。
• ⚠️ 落盘发生在面板里的按钮上,不在这一步。调用之后不要提示「已添加」—— 用户完全可能翻两下就关掉(check G24)。

installBundle —— 提议安装另一个包

{ "action": "installBundle", "params": { "id": "01M050AARQ0R08T9EHGDSGZBHJ" } }

id 必填(目标包的 ULID),version / ref 可选。它只是弹出安装面板,装不装由用户在面板里决定;流拿不到「装没装成」的结果(返回恒 null)。同 widget.pick:调用之后不要提示「已安装」。

page.close —— 关掉本页

{ "action": "page.close" }

无参。常规路由打开的页 = 真的关掉这一页;被 startPageForResult 打开的子页 = 收起浮层并兑现 { value: null, cancelled: true }。要带值关闭用 page.setResult,那个会自己关页,不用再补一个 page.close。

表单输入

单个值用 singleValue,一次收多个字段做一张 .xform 页。

{
  "id": "r",
  "action": "singleValue",
  "params": {
    "container": "page",
    "title": "列表选择",
    "desc": "副标题",
    "confirmTxt": "确定",
    "component": {
      "type": "select",
      "value": "b",
      "props": { "items": [ { "label": "选项 A", "value": "a" }, { "label": "选项 B", "value": "b" } ] }
    }
  }
}

container 必填(page / sheet / dialog)。返回 { value: { value: <字符串 | 数组 | null> }, cancelled },值在 ${r.value.value} —— 多套了一层。

.xform 是页型 form 的页,用 startPageForResult 打开,自己不写 container(三态由调用方裁决);form 的键就是结果键,声明顺序就是渲染顺序;onSubmit 绑定的 flow 只看得见 @event.value。字段类型全表、props、值形状见 numable docs params。

nav.open 与跳外部 App

{
  "id": "r",
  "action": "nav.open",
  "params": { "url": "futunn://quote/00700", "fallback": "https://www.futunn.com/stock/00700-HK" }
}

判定次序:危险 scheme 黑名单(javascript / file / data / intent / about / blob,check G16)→ 手势门(不是用户手势引发的 10 秒窗外静默拒绝,连弹窗都不给)→ 该包对该 scheme 的授权记忆 → 首跳确认弹窗。授权按(包, scheme)记,不进备份,卸载即清。

返回值五枚:opened · no-handler · denied · fallback · presented(container 为 sheet / dialog 时不等待,立即返回这个)。

• fallback 可选、只认 http(s)(check G16),只在外部 App 且 no-handler 时触发;用户拒绝(denied)恒不回落。
• nav.open 会等用户,标了 interactive;不标 interactive 的等待型 action 会撞上事件流 15 秒硬超时。
• URL 里 scheme 之后拼进去的 ${…} 要用 $[urlEncode::(…)] 包一层(check G16,警告级)。
• numable://self 在 nav.open 里不成立 —— 它走系统 scheme 回环,收端没有「当前是哪个包」的上下文,会弹「工具『self』未安装」。self 只在页内路由里有效;要从 flow 里开自己的包,写本包 ULID 字面量:{"action":"nav.open","params":{"url":"numable://01M050AARQ0R08T9EHGDSGZBHJ"}}。

规则(违反 = 返工)

出错怎么办

更多静默失效见 numable docs pitfalls。

相关

• numable docs df —— 取数流的白名单与写法
• numable docs xwidget —— events 挂在哪、实例 params 怎么来
• numable docs params —— 表单字段类型全表与 .xform