# 读取对象字段并通过连线使用

“变量与数据 → 读取对象字段”（`core.object.get`）可读取联系人 ID、名称或任意 JSON 对象字段。字段路径填在读取节点的属性中，输出通过数据连线传给后续节点，日志和消息正文不用填写表达式。

## 可导入模板

- [企业微信联系人 ID 与名称](../samples/workflows/wecom-contacts-fields-log.xfeworkflow)：先在插件中心连接已登录的企业微信客户端，再导入并按 F5。需要企业微信插件 3.0.0；读取当前客户端缓存，逐个输出 ID 与名称，不发送消息。[JSON 源文件](../samples/workflows/wecom-contacts-fields-log.json)。
- [无需插件的对象字段示例](../samples/workflows/object-fields-log.xfeworkflow)：直接导入并按 F5，输出两位示例联系人的 ID、中文名称与表情。工作流设置中的 `inputDefaults.contacts` 可换成自己的对象数组。[JSON 源文件](../samples/workflows/object-fields-log.json)。

导入后默认关闭自动调度，但可以手动运行。企业微信返回的是已加载的缓存，`completeRoster=false`，不保证完整通讯录；名称可能为空。

## 查看模板中的连线

选中“逐个遍历联系人”，在属性里点击“编辑子图：body”。每轮先执行“当前联系人”，然后分别读取 `id` 与 `displayName`。每个字段经过“转换为文本”节点，提供明确的文本输出，便于继续连接插件的文本参数。

```mermaid
flowchart LR
    C[当前联系人] -.->|item → value| I[读取字段 id]
    C -.->|item → value| N[读取字段 displayName]
    I -.->|value| IT[转换为文本]
    N -.->|value| NT[转换为文本]
    IT -.->|value → message| IL[输出联系人 ID]
    NT -.->|value → message| NL[输出联系人名称]
```

图中虚线是数据连接；模板的执行线按顺序运行两个字段读取、转换和日志节点。两个日志节点的固定参数均为空，消息完全取自数据连线。每位联系人只写两条日志，日志来源标明 ID 或名称；不添加内容前缀，不改写名称、空白、换行或表情。循环体的 `result` 仍返回完整原始联系人，主图返回全部迭代结果。

需要将 ID 或名称用于其他操作时，把对应“转换为文本”的 `value` 输出连到目标节点的文本输入。需要输出整个对象时，可以把“当前联系人”的 `item` 直接连接“输出日志”的 `message`。需要检查数值字段时，选择“转换为数字”；数据类型不一致的具体端口需要显式转换。

## 输入与输出

| 端口 | 方向 | 类型 | 含义 |
|---|---|---|---|
| `value` | 输入 | 通用 | 接收对象或数组；JSON 文本需先用转换节点解析 |
| `path` | 输入 | 文本 | 字段路径，默认 `id`，可直接在节点属性中填写 |
| `value` | 输出 | 通用 | 字段原始值的副本，保留类型与内容 |
| `found` | 输出 | 布尔 | 字段是否存在，可连接系统“条件分支” |

`value` 输出可以直接连接接受通用值的输入；连接文本、数字、布尔等具体类型输入前，使用对应转换节点。所有端口都有名称、类型和用途的悬停介绍，属性在参数下方显示连接来源和去向。

字段存在且值为 `null` 时，`found=true`、`value=null`；路径不存在时，`found=false`、`value=null`。可把 `found` 连到系统条件的 `left`，选择 `truthy`，只在 `true` 分支使用字段。每个分支只能读取该分支之前已执行节点的输出。

## 字段路径

字段名区分大小写，数组序号从 0 开始：

| 路径 | 示例用途 |
|---|---|
| `id` | 顶层联系人 ID，不把长字符串 ID 转成数字 |
| `displayName` | 顶层联系人名称 |
| `profile.name` | 嵌套对象字段 |
| `items.0.name` | 数组第一个对象的名称 |
| `0` | 输入本身为数组时的第一项 |
| `/a.b` | JSON Pointer，读取名字本身包含点号的 `a.b` 字段 |
| `/字段~1名` | 读取 `字段/名`；`~1` 表示 `/`，`~0` 表示 `~` |
| 空字符串 | 返回整个输入对象或数组的副本 |

缺失字段、数组越界或经过空值的路径返回 `found=false`。输入是空值、数字、布尔或未解析的 JSON 文本时明确报错。读取不修改源对象，也不会把原始字段中看起来像绑定的内容当作表达式执行。

## 中文、表情与 JSON 显示

对象和数组的日志、调试数据、运行记录与参数 JSON，以及导出的工作流和 JSON 日志，使用可读的 Unicode 字符，例如 `{"displayName":"李四 👨‍👩‍👧‍👦👍🏽🇨🇳"}`。中文、补充平面字符、组合表情、肤色和旗帜保留完整字符序列，不显示为 `\uXXXX` 或分开的代理对。

引号、反斜杠、换行等仍按 JSON 语法转义，文件保持可解析。用户原文本来包含的字面量 `\u4e2d` 不会变成“中”；文本值直接写入日志时仍保持原文。托管凭据在可读 JSON 中继续脱敏。

选中读取或使用字段的节点按 F9 设置断点，F5 运行／继续，F10 越过，F11 进入循环体。底部调试页查看当前参数及已执行节点输出，无需额外记录流程开始、结束或遍历日志。[调试说明](debugging.md)。