跳到主要内容

# 发送中控日志 (LCC.log)

## 声明​

    LCC.log(id, ...)
    LCC.log(log_map)

## 参数​

- id
  整数型，范围 1~6，对应中控的 6 条日志通道
- ... 可变参数，字符串、表、`ImageObject` 或 `LCC.capture_ui_state()` 返回的界面状态对象；普通表会通过 `table.deep_dump` 序列化，字符串中可使用 `[DATE]`、`[LINE]` 占位符
- log_map 表类型，键为日志别名（需通过 `set_log_aliases` 配置），值可以是字符串、表、`ImageObject`、界面状态对象，或包含这些内容的数组表

## 返回值​

- 无

## 说明​

> 发送前会校验是否已配置中控地址，未配置则抛出错误。
> 遇到网络异常会循环重试直到成功，重试期间会通过 `sys.toast` 提示。
> 使用别名表时，只发送匹配到别名的键，并按别名对应的列号写入。
> 如果别名表没有任何匹配键，本次调用不会发送请求。

## 示例​

    LCC.log(1, "[DATE] 开始同步", { count = 128 })

    LCC.log({
        ["状态"] = "同步完成",
        ["错误"] = "0"
    })

## 图像日志​

`LCC.log` 支持文本、普通表和图片混排。传入 `ImageObject` 时会默认按 PNG 写入日志；传入 `data:image/png;base64,...` 或 `data:image/jpeg;base64,...` 形式的字符串时，也会自动识别为图片。

    LCC.log(1, "开始", screen.image(100, 100, 200, 200), "结束")

如果需要减小传输体积，可以自行把图片压缩成 JPEG data URL 后传入：

    local img = screen.image(100, 100, 200, 200)
    local jpg = "data:image/jpeg;base64," .. img:jpeg_data(0.7):base64_encode()
    LCC.log(1, "压缩截图", jpg)
    img:destroy()

别名表形式也支持图像日志。普通表如果不包含图片，仍按 `table.deep_dump` 输出；数组表中包含图片时，会按数组顺序渲染图文内容。

    LCC.set_log_aliases({ "状态", "错误" })

    LCC.log({
        ["状态"] = { "你好", screen.image(243, 247, 336, 345), "世界" },
        ["错误"] = "0"
    })

图片日志更适合用于诊断问题或记录关键现场，不建议作为常规进度日志的一部分。单张图片最大 20 MiB，单条日志的图片合计最大 20 MiB，单张图片最大 1200 万像素，每条日志最多 8 张图片；超过限制或图片格式不支持时，`LCC.log` 会直接报错。图片会随日志请求一起上传；设备较多、截图区域较大或日志输出很密集时，图片内容会明显增加局域网传输、服务端解码和落盘压力，可能拖慢其它控制请求的响应。建议只在关键步骤记录截图，尽量裁剪到需要观察的区域；如果需要持续采样，优先降低频率或自行压缩成 JPEG data URL。

## 界面状态日志​

`LCC.log` 可以在日志内容参数或别名表的值中接收 `LCC.capture_ui_state()` 返回的对象。界面状态对象本身不是日志别名表，必须指定日志通道；`LCC.log(state)` 会抛出参数错误。`LCC.capture_ui_state()` 需要设备端 `ui_element` 0.6.0 或更高版本；模块不可用或版本过低时，请更新 XXTouch 后再使用 capture_ui_state。日志会上传该对象缓存的原始 `.xxtuie` 字节，文本回退内容为 `[界面状态]`；别名表和图文数组写法同样支持。

    local state = LCC.capture_ui_state()
    LCC.log(1, "提交失败", state)
    state:destroy()

一次 HTTP 请求最多包含一份界面状态；同一请求中的普通图片和界面状态解码后合计不能超过 20 MiB。对象销毁后不能再写入日志。有关抓取状态、本地保存和资源释放，请参阅 `LCC.capture_ui_state`。

日志历史会把图片和界面状态显示为附件卡片。点击图片可预览原图并从预览进入取色器；点击界面状态卡会进入文本元素工具，恢复截图和元素树。导出含附件的日志时，可以选择仅导出纯文本，或导出包含可浏览 HTML、原图及原始 `.xxtuie` 的 zip 文件；如果附件文件已经缺失，HTML 中会显示缺失占位，其它日志内容和仍存在的附件会继续导出。