console 控制台

约 1994 字大约 7 分钟道无涯i

console 控制台

console 是 ScriptX 里直接注入到全局作用域的日志对象。它一方面负责把文本写进运行时日志，另一方面还能控制右上角那套悬浮日志窗口。

如果你只想简单打一行日志，用全局 log() / print() 就够了；如果你想更接近 Web / Node 的写法，或者要手动控制悬浮日志窗口，就看这一页。

先记住这 9 条

console.log()、console.info()、console.warn()、console.error() 都支持多参数。
这几组方法会先把每个参数转成字符串，再用空格拼起来。
console.clear() 清的是 ScriptX 运行时日志缓存，不只是悬浮窗里眼前显示的文本。
console.show() 依赖悬浮窗权限；没权限时会返回 false。
console.hide()、console.setSize()、console.setPosition()、console.setAlpha()、console.setTitle()、console.setScreenshotVisible() 当前实现都会返回布尔值。
console.setScreenshotVisible() 不是控制整个悬浮日志窗口显示或隐藏；窗口本身还是用 console.show() / console.hide() 控制，它管的是“悬浮日志窗在截图里要不要可见”。
即使悬浮日志窗口此时还没显示，setSize / setPosition / setAlpha / setTitle / setScreenshotVisible 也会先把设置记下来，等窗口显示后再应用。
console.setPosition(x, y) 用的是“左上角坐标”语义，不用自己去换算右边距。
console.setAlpha(alpha) 最终会被限制在 0.05 ~ 1.0 之间。

`console.log(...args)`

作用

输出普通日志。

参数

参数	类型	可填值	说明
`...args`	`any[]`	任意数量、任意类型	每一项都会先转字符串，再用空格拼接

返回值

null

示例

console.log("package", lpparam.packageName, "process", lpparam.processName);
console.log("user =", { id: 1, name: "demo" });

`console.info(...args)`

作用

输出带 INFO 级别前缀的日志。

返回值

null

示例

console.info("hook attached");

`console.warn(...args)`

作用

输出带 WARN 级别前缀的日志。

返回值

null

示例

console.warn("selector timeout, fallback to manual scan");

`console.error(...args)`

作用

输出带 ERROR 级别前缀的日志。

返回值

null

示例

try {
  throw new Error("demo");
} catch (err) {
  console.error("failed:", err);
}

`console.clear()`

作用

清空运行时日志存储。

返回值

null

说明

这不是“只把悬浮窗当前文本区域擦掉”，而是会清理底层日志缓存。
清完以后，再打开悬浮日志窗口时，之前那批缓存日志也不会继续显示。

示例

console.clear();
console.log("logs reset");

`console.show()`

作用

显示悬浮日志窗口。

返回值

boolean

返回规则

场景	返回值
已有悬浮窗权限，成功尝试启动服务	`true`
没有悬浮窗权限	`false`

说明

当前实现内部会优先取全局 context，拿不到时再尝试 activity，最后回退到应用级 Context。
如果你是在没有悬浮窗权限的环境里调用，它不会自动弹权限页，只会返回 false。

示例

if (!console.show()) {
  toast("请先授予悬浮窗权限");
}

`console.hide()`

作用

关闭悬浮日志窗口。

返回值

boolean

说明

当前实现会返回 true。
就算窗口此时没显示，调用它也不会报错。

示例

console.hide();

`console.setSize(width, height)`

作用

设置悬浮日志窗口展开状态下的尺寸。

参数

参数	类型	可填值	说明
`width`	`number`	数字像素值	非数字会直接抛错
`height`	`number`	数字像素值	非数字会直接抛错

返回值

boolean

真实行为

传入值会先被记录。
真正应用时还会再做一层限制：
- 最小宽度约 220px
- 最小高度约 140px
- 最大值不会超过当前屏幕可用范围

失败行为

如果参数不是数字，会抛：

console.setSize(width, height) requires numeric width

或

console.setSize(width, height) requires numeric height

示例

console.setSize(420, 280);
console.show();

`console.setPosition(x, y)`

作用

设置悬浮日志窗口左上角位置。

参数

参数	类型	可填值	说明
`x`	`number`	`>= 0` 更符合预期	非数字会直接抛错
`y`	`number`	`>= 0` 更符合预期	非数字会直接抛错

返回值

boolean

很重要的坐标说明

虽然日志悬浮窗内部使用的是 Gravity.TOP | END 来布局，但 console.setPosition(x, y) 暴露给脚本的是正常的左上角坐标语义：

x = 0：尽量贴近屏幕左边
y = 0：尽量贴近屏幕顶部

你不用自己换算“右边距”。

示例

console.setPosition(16, 120);
console.show();

`console.setAlpha(alpha)`

作用

设置悬浮日志窗口透明度。

参数

参数	类型	推荐值	说明
`alpha`	`number`	`0.05 ~ 1.0`	非数字会直接抛错

返回值

boolean

真实行为

最终值会被限制在 0.05 ~ 1.0。
也就是说：
- 小于 0.05 会按 0.05 处理
- 大于 1 会按 1 处理

示例

console.setAlpha(0.8);
console.show();

`console.setTitle(title)`

作用

设置悬浮日志窗口标题。

参数

参数	类型	可填值	说明
`title`	`string \| null \| undefined`	任意文本	`null`、`undefined`、空白字符串都会回退到默认标题

返回值

boolean

示例

console.setTitle("抖音调试日志");
console.show();

重置成默认标题：

console.setTitle(null);

`console.setScreenshotVisible(visible?)`

先把名字理解对

这个方法名字很容易让人误会。
它不是：

显示整个控制台窗口
隐藏整个控制台窗口

那两件事分别还是：

console.show()
console.hide()

console.setScreenshotVisible(...) 当前源码真正控制的是：

悬浮日志窗口在截图里是否可见
更具体一点说，就是切换“截图时隐藏悬浮日志窗”这一档行为

参数

参数	类型	可填值	默认值	说明
`visible`	`boolean \| number \| string \| null \| undefined`	`true`、`false`、`1`、`0`、`"true"`、`"false"`、`"on"`、`"off"`、`"yes"`、`"no"` 等	不传时按 `true`	表示“截图时是否让悬浮日志窗保持可见”

这些值会被怎么理解

当前源码不是只认布尔值，而是做了一层宽松解析：

你传的值	最终当成什么
`true`	可见
`false`	隐藏
`1`、`2`、`-1` 这类非零数字	可见
`0`	隐藏
`"true"`、`"on"`、`"yes"`	可见
`"false"`、`"0"`、`"off"`、`"no"`	隐藏
`null`、`undefined`	可见
其他普通字符串，比如 `"abc"`	可见

也就是说，如果你是为了脚本可读性，最稳的还是直接传：

console.setScreenshotVisible(true);
console.setScreenshotVisible(false);

返回值

boolean

当前实现会返回 true。

它真正改的是什么状态

从源码行为看，它内部对应的是悬浮日志窗上的“截图可见性”开关：

true：截图时让这块悬浮日志窗保持可见
false：截图时把这块悬浮日志窗临时隐藏掉

这和悬浮窗右上角那个“眼睛”图标是同一类状态。

它和 `console.show()` / `console.hide()` 的区别

API	控制的东西
`console.show()`	把悬浮日志窗口真正显示出来
`console.hide()`	把悬浮日志窗口真正关掉
`console.setScreenshotVisible(false)`	窗口仍然开着，但截图时把它当成“隐藏”

一个很实用的使用场景

你调试脚本时想一直开着悬浮日志窗看输出，但又不想它挡到布局截图或屏幕截图，这时就很适合先：

console.show();
console.setScreenshotVisible(false);

这样你平时还能看到日志窗，但在这套截图相关链路里，它会尽量不出现在截图结果里。

和 `auto.saveScreenRoots()` 的关系

auto.saveScreenRoots(...) 在导出布局包之前，会临时把悬浮日志窗切成“截图里隐藏”的状态，导出完成后再恢复。
所以如果你平时本来就不希望日志窗混进截图，主动先设一遍也很合理：

console.show();
console.setScreenshotVisible(false);

const zipPath = auto.saveScreenRoots("/sdcard/Download/home_layout");
log(zipPath);

示例：显式允许截图里看见日志窗

console.show();
console.setScreenshotVisible(true);
console.log("这次希望把日志悬浮窗也一起留进截图");

示例：调试时窗口开着，但截图里隐藏

console.show();
console.setScreenshotVisible(false);
console.log("我还在看日志，但导出布局时不想把它拍进去");

示例：用数字和字符串也能控制

console.setScreenshotVisible(0);       // 等价于 false
console.setScreenshotVisible("off");   // 等价于 false
console.setScreenshotVisible("yes");   // 等价于 true

`runtime.console`

除了全局 console 以外，当前运行时还会把同一个对象挂到 runtime.console 上。

示例

runtime.console.log("same console object");

怎么选

日常脚本里直接写 console.xxx(...) 就够了。
如果你正在围绕 runtime 对象统一组织能力，再用 runtime.console 会更顺手。