SuperAPI AI 工具集

flint-interaction-author

数据与分析

查看项目

更新于 10-28 18:37

技能介绍

该技能用于为 Flint 图表添加或更新交互行为。Flint 图表被视为共享状态:读者的手势变成事件,处理器把事件转成 { id, ops } 形式的更新,更新按层组合后渲染,宿主和智能体都能读回状态。应用与智能体也可以直接写入同类更新。完整的交互模型见官方文档的交互介绍页面,图表本身(chart_spec、semantic_types)则属于 flint-chart-author 技能。这里的所有能力都运行在 Vega-Lite 后端;静态渲染和其他后端不会处理 interaction_spec 与更新。

用途与产出区分:当请求要求在图表上添加手势或行为(如点击高亮、缩放、刷选一个时间段、让图表可交互)时,产出一个 interaction_spec,即 { "interactions": [ ... ] },并且只使用预置交互。当请求要求对已在屏幕上的图表做外部变更(如指出日本、框选 2010 至 2020、标注某个值、按值重排、智能体借助图表回答用户)时,产出一个 ChartUpdate,即 { "id", "ops": [ ... ] }。当围绕图表编写代码(如在我的应用中、点击后打开记录、跟随悬停的面板)时,使用 flint-chart/interactive 的 TypeScript API:mount、预置交互工厂、onChange、dispatch。当需要跨图表或随时间联动(如关联两个图表、跟随选择的表格、按年份播放)时,使用 linkCharts 或 useLinkedCharts,或者用定时器 dispatch;在 MCP 画板上则使用 link_spec。当请求的手势没有对应预置(如沿路径拖拽、画出猜测、为框选加规则、应用绘制的透镜)时,需要定义 CanvasInteractionDef,包含触发器、可供性和处理器。

主要能力:预置交互按用途分组。单选类包括 click-highlight(点击标记、图例项或轴标签后保持强调、其余变淡,Shift 点击可追加)、click-group-focus(点击后同组标记强调,用 groupBy 指定分组字段)、hover-group-focus(悬停分组强调)、axis-highlight(点击或悬停离散轴标签高亮对应类别)。读取值类包括 inspect(指针移动时引导线读取最近标记,mode 可选轴与比较)、inspect-index(沿索引轴读取每个系列的值)。区域聚焦类包括 select(矩形选区)、lasso-select(自由手绘区域)、brush-x 与 brush-y(沿轴刷选区间,极坐标下 x 刷选为扇区)、brush-angle(在饼图、环图、玫瑰图或雷达图上刷选角度扇区)、linked-brush(在挂载同一预置的多张图表间联动分组)。视图移动类包括 navigate(拖拽平移、滚轮或捏合缩放,地图上移动投影,地球仪上旋转球体)和 brush-zoom(框选后飞入该区域)。删减重排类包括 legend-toggle(点击图例隐藏或恢复系列,隐藏状态在重置后保留)、drag-reorder(拖拽离散轴标签重排类别)、filter-controls(图表旁控件按字段过滤行,或以高亮模式弱化)。标记类包括 click-annotate(点击标记固定数值注释)。交给应用类包括 double-activate(双击激活)、long-press(触摸长按 500 毫秒激活)、context-activate(右键或长按打开应用菜单)、context-menu(选定标记后弹出应用动作菜单并获得 menu-select 事件)。无障碍类包括 accessible-navigation(用 Tab 与方向键遍历标题、轴、图例、分面头、系列和标记,Enter 进入层级,空格执行点击预置)。

使用方式:通过 MCP 工具时,把交互对象作为 interaction_spec 与 chart_spec 并列放入图表输入;validate_chart 会在不绘制的情况下报告警告,show 绘制时运行同一检查。list_interaction_presets 配合 chartType 可列出该图表类型支持的预置、作用与选项。发送更新时,把更新层作为 updates 参数与输入并列传给 validate_chart 和 show。仅当用户明确要求代码时,才使用 mountChart 或 React 的 <FlintChart> 挂载,用工厂调用创建预置,用 applyUpdate 提交更新,用 getState 与 onChange 读写状态。自定义交互需要能运行代码的宿主;在 MCP 视图中,只能给出最接近的预置及其未覆盖的部分。

编写要点:每个条目格式为 { "type": <预设>, "id"?: <字符串>, "options"?: { ... } }。选项只放预置自身支持的项;reset 可省略以使用默认重置手势,也可设置以释放触发器。不保留状态的预置(hover-group-focus、inspect、context-activate)不接受 reset。同一预置出现两次时才需要 id。在代码中,同一条目是对应的工厂调用,选项相同。挂载时每个触发器只有一个归属:先请求的条目获得触发器,后来的条目在能保留其余部分时让出并给出 info 警告,不能保留时被丢弃并警告;图表仍会渲染。绘图区拖拽、双击、图例点击、保留的标记焦点这四类触发器可能被多个预置争用。数据层面的确认包括:legend-toggle 需要绑定到离散图例的颜色字段;navigate 与 brush-zoom 需要连续且未分面的轴;drag-reorder 需要绑定编码中的离散轴;inspect-index 需要索引轴;分组类预置需要 groupBy 绑定的字段。格式错误的条目会报错,例如未知类型、选项与 type 并列、options 内出现 id、字符串条目、缺少必需选项、不支持的重置手势、重复 id。被丢弃或让出的条目会给出警告,指明条目、所需条件与图表类型。修复或移除被警告的条目后,返回严格 JSON 的对象,除非用户要求解释。

适用场景与限制:适合为 Flint 图表添加读者可触发的交互、向已显示图表推送更新、在应用中嵌入交互图表、联动多张图表或在无预置匹配时定义自定义交互。限制包括:交互仅在 Vega-Lite 后端生效;自定义交互必须由能运行代码的宿主挂载;在 MCP 视图中无法实现自定义交互;不应在未请求时添加交互或 interaction_spec;选项、操作、状态、触发器、光标与事件动作只能使用本技能列出的库内置名称;当请求涉及没有预置的行为时,应先说明最接近的预置及其缺失,再在条件允许时提供自定义定义,不得编造库外能力。