企业官网建设流程全解析

• 音视频
• 图形学
• 桌面应用

本指南以 TiXL 官方文档 .help/docs/operators/lib/io/json/README.md 为核心骨架，结合仓库中 GetAttributeFromJsonString.cs 与 RequestUrl.cs 的源码实现，系统讲解在 TiXL 节点图中拉取 URL/JSON 数据、按列与行号提取字段的完整方案。读完本文，你将能独立完成"请求远程接口 → 解析 JSON → 提取目标字段 → 驱动文本/数值/列表输出"的实时数据可视化链路。

一、Lib.io.json 模块概览

TiXL（Tooll eXperimental Language，实时动态图形开源软件）的Lib.io.json命名空间位于 Operators/Lib/Symbols/io/json/ 目录，是 IO 类操作符库（.help/docs/operators/lib/io/README.md）中专门负责HTTP 请求与 JSON 解析的子模块。官方索引文档 README.md 中登记了 2 个操作符：

这两个操作符通常组合使用：RequestUrl负责把远程 JSON 文本拉进节点图，GetAttributeFromJsonString负责把它按表格语义拆解出可用字段；也可以单独使用，例如把RequestUrl的输出接给 PickStringPart 之类的字符串处理操作符做自由裁剪。两个操作符的完整输入/输出定义都登记在其.t3ui界面文件与同名.cs实现中，文档由算子库自动生成（README 末尾标注Auto-generated from the operator library）。

需要留意的是：Lib.io.json是运行时 HTTP 数据源通道。TiXL 中数据加载类操作符还有很多，例如文件类的 ReadFile、WriteToFile、FilesInFolder，以及图片类的 LoadImageFromUrl。当你的数据源是本地 JSON 文件时，更合适的路径是先经ReadFile读成字符串再交给GetAttributeFromJsonString；当数据源在网络上时，才用RequestUrl。

二、GetAttributeFromJsonString：按表结构提取 JSON 字段

这是Lib.io.json的核心解析操作符。官方文档描述为："Loads a JSON string from a URL and outputs the defined part as a string."（加载 JSON 字符串并输出其中指定的部分）。在 TiXL 内部，它把 JSON 反序列化为System.Data.DataTable，从而把 JSON 视为一张"行 × 列"的表格，用户通过列名 + 行号精确取出单元格。

2.1 输入参数详解

2.2 输出说明

RowCount与Columns是很有价值的"元数据"输出：你可以用RowCount做循环上界、随机行采样（例如MathUtils随机取行号再喂给RowIndex），用Columns动态发现接口返回了哪些字段，避免硬编码列名。

2.3 底层解析逻辑（源码级）

从 GetAttributeFromJsonString.cs 可以看出完整工作流：

1. 读取ColumnName、RowIndex、JsonString三个输入值（L27-L30）；
2. 调用JsonConvert.DeserializeObject<DataTable>(json)（L35）——这是Newtonsoft.Json（项目依赖见 Operators/Lib/Lib.csproj）的经典反序列化用法，意味着 JSON 顶层应当是一个对象数组（[{...},{...}]）或可转换为表的结构，形如：

   [ {"name": "alpha", "value": 1}, {"name": "beta", "value": 2} ]

   等价于 2 行 × 2 列的表；

3. 遍历DataTable的列，收集列名并按InvariantCultureIgnoreCase匹配ColumnName（L40-L50），同时填充Columns输出；
4. 若列不存在，状态信息置为Can't find column {columnName}（L54）；
5. 若行越界，状态信息置为Row index {rowIndex} exceeds {dt.Rows.Count}.（L60）；
6. 命中则把单元格值写入Result（L65）；
7. 任何解析异常（如非法 JSON）被catch捕获，写入Log.Warning("Couldn't parse json to data table ...")（L73），不会导致节点崩溃。

状态可视化：该类实现了IStatusProvider（L7、L87-L95）。当列名找不到或行号越界时，节点在编辑器中会显示 Warning 级别状态提示（StatusLevel.Warning），排查问题非常直观——这是 TiXL 操作符的标准诊断模式（接口定义见 IStatusProvider.cs）。

2.4 典型接线示例

[RequestUrl] 或 [ReadFile] │ Result (JSON 文本) ▼ [GetAttributeFromJsonString] JsonString ← 上一步的 Result ColumnName ← "title"（字符串常量） RowIndex ← 0 │ ├─ Result → 文本/字幕/UI 标签 ├─ RowCount → 循环取样的上界 └─ Columns → 字段列表（可接 List 类输出）

若你想遍历 JSON 的全部行，可以把RowCount接进一个整数运算链（例如%取模或用帧号驱动），再连回RowIndex，实现"每 N 帧轮换显示一条数据"的动画效果；配合 TiXL 的曲线与时间线（Timeline.md）即可做成数据驱动的滚动字幕。

三、RequestUrl：拉取 URL 源码文本

RequestUrl是Lib.io.json中的 HTTP 请求操作符，官方文档描述："Loads a URL and outputs the source text as a string."，并提示"输出内容等价于浏览器打开 URL 后『查看网页源代码』所见文本"。它不与 JSON 强绑定——只要是 HTTP(S) GET 能取到的文本，都可以用它拉取，再配合 PickStringPart 之类的文本处理操作符做任意裁剪。

3.1 输入参数详解

3.2 输出说明

3.3 触发与缓存语义（源码级）

RequestUrl.cs 的关键逻辑在Update方法（L16-L24）：

var wasTriggered = MathUtils.WasTriggered(TriggerRequest.GetValue(context), ref _triggered); var isUrlDirty = Url.DirtyFlag.IsDirty; var url = Url.GetValue(context); if (wasTriggered || isUrlDirty) Download2(url);

• Url.DirtyFlag.IsDirty：URL 值发生变化（被编辑或重新接线）时自动触发一次下载——这是 TiXL 槽位脏标记机制（DirtyFlag.cs）的典型应用，即"换地址自动重拉"；
• MathUtils.WasTriggered(...)（工具实现见 MathUtils.cs）：只在TriggerRequest从false变true的上升沿触发，避免每个渲染帧都重复请求；
• 触发后Download2(url)以async/await异步执行（L28-L51），通过HttpClient（UseDefaultCredentials = true）发出 GET 请求，拿到响应体后写入Result并调用Result.DirtyFlag.Invalidate()通知下游重新求值。异步执行意味着请求期间节点不会阻塞渲染线程，但Result的更新存在网络延迟，下游依赖它的节点在此之前拿到的是旧值或空值；
• 请求失败（网络不可达、4xx/5xx、非法 URI 等）会被catch捕获并记录Log.Warning("Download failed: ...")（L49），同样不会让 TiXL 崩溃。

无轮询限制：RequestUrl只在 URL 变化或收到TriggerRequest上升沿时请求一次，并不会自动周期刷新。若你的场景需要周期性拉取（比如每 5 秒刷新一次天气数据），可从时间线或帧计数器生成方波/脉冲信号驱动TriggerRequest。

3.4 与 JSON 解析组合的完整链路

RequestUrl+GetAttributeFromJsonString是官方文档中互为补充的经典组合（两个文档的 "Also see" 部分相互引用）：

[RequestUrl] Url = https://api.example.com/events TriggerRequest = true（或由方波脉冲驱动） │ Result：远程 JSON 原文 ▼ [GetAttributeFromJsonString] JsonString ← Result ColumnName ← "title" RowIndex ← 帧驱动 / 随机 │ ▼ 文本/字幕/数值显示

实测链路需要满足两点前提：① 目标接口返回的 JSON 能被JsonConvert.DeserializeObject<DataTable>解析（顶层为对象数组）；② 接口允许匿名 GET 访问（源码 RequestUrl.cs 使用默认凭据，未设置 Authorization 头——源码中预留了 apikey / Bearer 注释代码，说明当前版本未内置鉴权头注入能力，如需鉴权接口需自行扩展）。

四、扩展应用与相关操作符

• 文本裁剪：RequestUrl的Result未必是 JSON，也可能是 HTML 或纯文本；接上 PickStringPart 可提取任意片段；
• 本地文件 JSON：JSON 已存成本地文件时，优先用 ReadFile 读取内容再进GetAttributeFromJsonString，避免不必要的网络请求；
• 结果持久化：配合 WriteToFile 可以把拉取到的数据落盘，形成"采集 → 解析 → 存档"闭环；FilesInFolder 则可批量枚举数据文件目录；
• 图片类 URL 资源：图片资源可用LoadImageFromUrl直接加载（见 GetAttributeFromJsonString.md 的 "Also see"）；
• 更广泛的 IO 通道：Lib.io还提供 WebSocketClient、TcpClient、UdpInput、OscInput 等实时通信操作符，适合需要更低延迟或双向通道的数据源；Lib.io.json定位是"一次性 GET 请求 + 表结构解析"的轻量方案。

五、快速上手清单

1. 在操作符搜索框中输入json或直接查找Lib.io.json分类，拖入RequestUrl与GetAttributeFromJsonString；
2. RequestUrl.Url填入一个返回 JSON 数组的公开接口地址（或使用文档示例https://cataas.com/cat）；
3. 把TriggerRequest点开一次（或接方波脉冲）触发下载，观察Result是否出现 JSON 文本；
4. 将RequestUrl.Result连到GetAttributeFromJsonString.JsonString；
5. 在ColumnName填目标字段名（大小写不敏感），RowIndex填 0（首行）；
6. 把Result接到文本输出或数值显示，确认取数正确；用RowCount/Columns验证解析结构；
7. 若节点出现 Warning 状态提示，对照 2.3 节的错误语义检查列名与行号。

六、相关参考

• 模块索引：.help/docs/operators/lib/io/json/README.md
• 操作符文档：GetAttributeFromJsonString.md ｜ RequestUrl.md
• 源码实现：GetAttributeFromJsonString.cs ｜ RequestUrl.cs
• IO 模块总览：.help/docs/operators/lib/io/README.md
• 文件类操作符：ReadFile ｜ WriteToFile ｜ FilesInFolder

• 音视频
• 图形学
• 桌面应用