Ink 终端渲染器用于 json-render,属于 @json-render/ink 包,目标是把 JSON 规格转换为可交互的终端组件树。规格采用带 root 键的扁平元素映射,每个元素包含 type、props、children,并可用 on 字段绑定事件动作。
主要能力
标准组件分为几类。布局类:Box(弹性布局容器,默认 flexDirection 为 row,可用于分组、间距、边框、对齐)、Text(带颜色、加粗、斜体等样式)、Newline(插入空行,须置于 flexDirection 为 column 的 Box 内)、Spacer(沿主轴伸展的弹性空白)。内容类:Heading(h1 加粗并带下划线,h2 加粗,h3 加粗并变暗,h4 变暗)、Divider(可选居中标题的分隔线)、Badge(default、info、success、warning、error 变体)、Spinner(带动画的加载指示器,可附带标签)、ProgressBar(0 到 1 的进度条)、Sparkline(用 Unicode 块字符绘制的行内图表)、BarChart(带标签和数值的横向条形图)、Table(带表头和行的表格)、List 与 ListItem(列表及含标题、副标题、前后文本的结构化行)、Card(可带标题的带边框容器)、KeyValue(键值对展示)、Link(可点击 URL,可带标签)、StatusLine(带彩色图标的 estado 信息)、Markdown(以终端样式渲染 Markdown)。交互类:TextInput(触发 submit、change 事件)、Select(方向键导航,触发 change)、MultiSelect(空格切换多选,触发 change、submit)、ConfirmInput(是/否确认,触发 confirm、deny)、Tabs(左右方向键切换,触发 change)。
状态与动态属性
元素可用 visible 字段基于状态控制显示或隐藏,支持 { "$state": "/path" }、带 eq 的比较、带 not 的取反,以及 $and、$or 组合条件。任意 prop 值可以是渲染时解析的动态表达式:$state 单向读取状态;$bindState 用于表单组件的自然 value prop 实现双向绑定(组件不使用 statePath prop);$bindItem 双向绑定重复项字段;$cond 配合 $then、$else 实现条件取值;$template 将状态值插值进字符串。
事件与动作
组件通过 emit 触发命名事件,元素 on 字段把事件映射到动作绑定。内置动作 setState、pushState、removeState 由框架自动处理,参数分别使用 statePath、value、index。容器元素可用 repeat 字段按状态数组渲染子项,重复子项内用 { "$item": "field" } 读取当前项、{ "$index": true } 读取索引。
渲染与集成
使用 defineCatalog 基于 schema 与标准组件定义创建目录,defineRegistry 注册自定义组件(标准组件已内置),Renderer 渲染规格。createRenderer 是更高层 API,生成自带状态、可见性、动作、焦点等 Provider 的组件。Provider 包括 StateProvider(用 JSON Pointer 路径共享状态,可传 store 进入受控模式)、ActionProvider、VisibilityProvider、ValidationProvider、FocusProvider 和合并全部上下文的 JSONUIProvider。传入外部 StateStore 时 initialState 与 onStateChange 被忽略,store.set 会触发 React 重渲染;createStateStore 可创建与框架无关的内存状态存储。useUIStream 可从 API 端点按 JSONL 补丁流渐进渲染规格;./server 导出可用目录生成 AI 系统提示。
适用场景与限制
适合以 JSON 描述并生成终端仪表盘、表单、多标签视图等交互界面,也适合结合流式接口渐进构建终端 UI。终端宽度约 80 到 120 列,主结构建议使用垂直布局,可用 Box 的 borderStyle(single、double、round、bold)分组,并使用 red、green、yellow、blue、magenta、cyan、white、gray 等命名颜色。具体收费、支持平台与完整安装步骤暂未提供。