跳到主要内容

qk.Sys:系统

2.3.32 起,qk.Sys.PlaySound 可单独调整本次播放的音量,例如 qk.Sys.PlaySound("dim", volumeGain: 0.5)。volumeGain 支持 0~4,默认 1,0 为静音;不改变系统音量,也不控制 TTS 朗读。使用新参数的脚本需要 2.3.32 或更高版本,过度放大可能失真。

Windows 与本机(系统信息、CPU 与内存占用、环境变量与注册表读取、提示音、朗读、音量与音频设备、媒体键、磁盘、网络与 Wi-Fi、Windows 设置页(SearchSettings/OpenSettings)、显示器亮度、深色模式、锁屏/关屏/睡眠/关机等电源操作);Quicker 自身的信息见 qk.Quicker。

Sys.Info​

SysInfo Info()

读取计算机名、用户名、系统版本、锁屏/全屏/深色模式/联网状态、局域网 IP 与开机时长。

返回类型:SysInfo。空值、用户取消和异常行为以成员及域说明为准。

Sys.PlaySound​

void PlaySound(string sound, bool wait = false)

播放声音;每次运行 PlaySound 与 Speak 合计最多 100 次;无法解码或没有音频设备报 SOUND_FAILED(不等待时只记警告)。

参数声明说明
string sound内置音名 info|snip|succeed|warning|wrong|dim(总是按内置音处理),或音频文件路径(mp3/wav/wma/m4a 等;不存在 FILE_NOT_FOUND),或 http(s) 网址;其他协议 INVALID_ARGUMENT。 取值:info、snip、succeed、warning、wrong、dim。也接受其他值,详见成员说明。
bool wait = falsetrue:播完才返回,停止脚本即停止播放并立即返回;false:立即返回并在后台播完(运行结束后继续;在 Quicker 中停止本动作时随之停止;最长 30 分钟)。整个 Quicker 同时最多 4 个后台播放/朗读,超出报 LIMIT_EXCEEDED(不排队;连续播放请用 wait: true)。文件/网址 15 秒内打不开报 SOUND_FAILED。

返回类型:void。空值、用户取消和异常行为以成员及域说明为准。

void PlaySound(string sound, bool wait = false, double volumeGain = 1)

播放声音;每次运行 PlaySound 与 Speak 合计最多 100 次;无法解码或没有音频设备报 SOUND_FAILED(不等待时只记警告)。

参数声明说明
string sound内置音名 info|snip|succeed|warning|wrong|dim(总是按内置音处理),或音频文件路径(mp3/wav/wma/m4a 等;不存在 FILE_NOT_FOUND),或 http(s) 网址;其他协议 INVALID_ARGUMENT。 取值:info、snip、succeed、warning、wrong、dim。也接受其他值,详见成员说明。
bool wait = falsetrue:播完才返回,停止脚本即停止播放并立即返回;false:立即返回并在后台播完(运行结束后继续;在 Quicker 中停止本动作时随之停止;最长 30 分钟)。整个 Quicker 同时最多 4 个后台播放/朗读,超出报 LIMIT_EXCEEDED(不排队;连续播放请用 wait: true)。文件/网址 15 秒内打不开报 SOUND_FAILED。
double volumeGain = 1本次播放的音量倍率,范围 0–4,支持小数;默认 1 为原始音量,0 为静音,大于 1 放大。仅影响本次播放,不改变系统或应用会话音量;过度放大可能削波失真。非有限数字或超出范围报 INVALID_ARGUMENT(后台模式也会在播放开始前报错)。

返回类型:void。空值、用户取消和异常行为以成员及域说明为准。

Sys.Speak​

void Speak(string text, bool wait = false)

用 Windows 默认语音朗读文本(1–20000 字符);语音引擎不可用报 SOUND_FAILED。

参数声明说明
string text见本成员和所在域的说明。
bool wait = falsetrue:读完才返回,停止脚本即停止朗读并立即返回;false:立即返回并在后台读完(与 PlaySound 共用同时 4 个的后台名额,超出 LIMIT_EXCEEDED)。

返回类型:void。空值、用户取消和异常行为以成员及域说明为准。

Sys.GetVolume​

VolumeInfo GetVolume(string device = "output")

读取当前默认输出设备(或默认录音设备)的音量与静音(每次调用都重新取默认设备);没有音频设备报 SOUND_FAILED。停止后的 finally 中也可调用。

参数声明说明
string device = "output"output(默认输出/播放设备,默认)| input(默认录音设备,如麦克风)。 取值:output、input。

返回类型:VolumeInfo。空值、用户取消和异常行为以成员及域说明为准。

Sys.SetVolume​

VolumeInfo SetVolume(int? level = null, bool? muted = null, string device = "output")

设置当前默认输出设备(或默认录音设备,如麦克风静音)的音量与静音,返回调用后的状态;运行后保留(宿主不自动恢复:先 GetVolume 保存,在 finally 中 SetVolume 恢复,停止后的 finally 中也可调用);没有音频设备报 SOUND_FAILED。

参数声明说明
int? level = null音量 0–100;null 不改。
bool? muted = null是否静音;null 不改。
string device = "output"output(默认输出/播放设备,默认)| input(默认录音设备,如麦克风)。 取值:output、input。

返回类型:VolumeInfo。空值、用户取消和异常行为以成员及域说明为准。

Sys.Power​

void Power(string action)

电源与会话操作。lock、screenOff 锁定或关闭屏幕;sleep/hibernate/signOut/shutdown/restart 可使电脑睡眠、休眠、注销、关机或重启,未保存的工作可能丢失。失败报 POWER_FAILED。screenOff 由鼠标或按键触发时,随后的鼠标移动或松键可能立即点亮屏幕。睡眠期间停止与超时不生效;唤醒后若已超过动作超时,后续代码不再执行。

参数声明说明
string actionlock(锁定计算机)| screenOff(关闭显示器)| sleep(睡眠,唤醒后返回)| hibernate(休眠,未启用休眠报 POWER_FAILED)| signOut(注销)| shutdown(立即关机)| restart(立即重启);不区分大小写。 取值:lock、sleep、hibernate、screenOff、signOut、shutdown、restart。

返回类型:void。空值、用户取消和异常行为以成员及域说明为准。

Sys.GetBrightness​

int GetBrightness(string screen = "mouse")

读取显示器亮度 0–100(同“显示器亮度”步骤:笔记本内置屏走 WMI,外接显示器走 DDC/CI)。不支持调节亮度报 BRIGHTNESS_UNSUPPORTED,其他失败(屏幕未连接等)报 BRIGHTNESS_FAILED。

参数声明说明
string screen = "mouse"mouse(鼠标所在屏,默认)| primary(主屏)| all(与 primary 相同)| qk.Screen.List() 返回的 ScreenInfo.Id。 取值:mouse、primary、all。也接受其他值,详见成员说明。

返回类型:int。空值、用户取消和异常行为以成员及域说明为准。

Sys.SetBrightness​

int SetBrightness(int? level = null, int delta = 0, string screen = "mouse", bool osd = false)

设置显示器亮度,返回设置后的亮度;设备只支持部分档位时取最接近的档位;运行后保留。screen 为 all 时设置全部显示器,至少一块成功即返回(鼠标所在屏,否则第一块成功屏的亮度),全部失败才报错。错误码同 GetBrightness。

参数声明说明
int? level = null目标亮度 0–100;与 delta 只能给出一个。
int delta = 0相对调整 -100–100(非 0;越界取 0/100);与 level 只能给出一个。
string screen = "mouse"mouse(默认)| primary | all | qk.Screen.List() 返回的 ScreenInfo.Id。 取值:mouse、primary、all。也接受其他值,详见成员说明。
bool osd = false是否显示亮度提示(同步骤的 OSD)。

返回类型:int。空值、用户取消和异常行为以成员及域说明为准。

Sys.ListAudioDevices​

AudioDevice[] ListAudioDevices(string device = "output")

列出已启用的音频输出(或录音)设备,IsDefault 标出当前默认设备;读取失败报 SOUND_FAILED。

参数声明说明
string device = "output"output(播放设备,默认)| input(录音设备)。 取值:output、input。

返回类型:AudioDevice[]。空值、用户取消和异常行为以成员及域说明为准。

Sys.SetDefaultAudioDevice​

void SetDefaultAudioDevice(string idOrName, string device = "output")

设为默认音频设备(多媒体、控制台与通信,同“音频控制”步骤);运行后保留。找不到 AUDIO_DEVICE_NOT_FOUND;名称匹配到多个 INVALID_ARGUMENT(请改用 Id);设置失败 SOUND_FAILED。

参数声明说明
string idOrName设备 Id,或设备名称(依次按完整名称、名称包含匹配,不区分大小写)。
string device = "output"output(播放设备,默认)| input(录音设备)。 取值:output、input。

返回类型:void。空值、用户取消和异常行为以成员及域说明为准。

Sys.GetEnv​

string? GetEnv(string name)

读取环境变量(Quicker 进程中的当前值;Quicker 启动后在系统设置中修改的变量需重启 Quicker 才可见);不存在返回 null。

参数声明说明
string name变量名,如 "PATH"、"USERPROFILE"(不区分大小写)。

返回类型:string?。空值、用户取消和异常行为以成员及域说明为准。

Sys.GetRegistry​

object? GetRegistry(string path, string? name = null)

读取注册表值(只读);键或值不存在返回 null。REG_SZ/REG_EXPAND_SZ → string(已展开)、REG_DWORD → long(无符号)、REG_QWORD → long、REG_MULTI_SZ → string[]、REG_BINARY → byte[];无权限报 ACCESS_DENIED。

参数声明说明
string path键路径,如 @"HKCU\Software\Microsoft";根键可写 HKCU/HKLM/HKCR/HKU/HKCC 或全名,可带注册表编辑器复制出的“计算机\”前缀。
string? name = null值名;null 或 "" 为默认值。

返回类型:object?。空值、用户取消和异常行为以成员及域说明为准。

Sys.SetDarkMode​

void SetDarkMode(bool dark, string scope = "all")

切换当前用户的 Windows 深色(true)/浅色(false)模式,并通知已打开的程序(个别程序重启后才生效);运行后保留,当前状态见 qk.Sys.Info().DarkMode。

参数声明说明
bool dark见本成员和所在域的说明。
string scope = "all"apps(应用)| system(任务栏、开始菜单等系统界面)| all(默认)。 取值:apps、system、all。

返回类型:void。空值、用户取消和异常行为以成员及域说明为准。

Sys.MediaKey​

void MediaKey(string key)

发送系统媒体播放键。全局生效,不需要目标窗口或键盘焦点(qk_run 的 target:'none' 可用);响应的播放器由系统决定;只能发送这四个键(音量与静音请用 Sys.SetVolume)。失败报 HOST_FAILED。

参数声明说明
string keyplayPause(播放/暂停)| next(下一首)| previous(上一首)| stop;不区分大小写,不接受别名(play_pause 等报 INVALID_ARGUMENT)。 取值:playPause、next、previous、stop。

返回类型:void。空值、用户取消和异常行为以成员及域说明为准。

Sys.ListDisks​

DiskInfo[] ListDisks()

列出本机各驱动器的盘符、卷标、类型、文件系统、总容量与剩余空间(字节)。未就绪的驱动器(光驱无盘、断开的网络盘)IsReady 为 false,其余字段为 null,不报错;所有非固定盘(可移动盘、光驱、网络盘、内存盘、未知类型)并行探测,合计最多约 0.5 秒,无响应的按“未就绪、容量未知”报告(类型照实给出),不会被断开的网络盘或休眠的 USB 盘卡住。

返回类型:DiskInfo[]。空值、用户取消和异常行为以成员及域说明为准。

Sys.SearchSettings​

SettingsPage[] SearchSettings(string query, int limit = 10)

按关键词查 Windows 设置页(数据同搜索插件“Windows 设置”):空白分隔的每个词都须出现在标题、分类或地址中(不区分大小写),标题更贴近的排前面;只收 ms-settings: 与 control.exe 目标;没有命中返回空数组。

参数声明说明
string query关键词,如 "蓝牙"、"wifi"、"默认应用";多个词用空格分隔。
int limit = 10最多返回条数,1–100。

返回类型:SettingsPage[]。空值、用户取消和异常行为以成员及域说明为准。

Sys.OpenSettings​

void OpenSettings(string uri)

以普通权限打开 Windows 设置页,不等待窗口出现。uri 只接受 ms-settings: 开头的地址(按原样打开,不检查该页在当前 Windows 版本是否存在),或 SearchSettings 返回的 control.exe 目标;其他地址、命令(含 rundll32)报 INVALID_ARGUMENT;启动失败 PROCESS_FAILED。

参数声明说明
string uri如 "ms-settings:bluetooth",或 SearchSettings 返回的 Uri(control.exe 目标须与目录中的命令逐字相同)。

返回类型:void。空值、用户取消和异常行为以成员及域说明为准。

Sys.GetNetwork​

NetworkInfo GetNetwork()

本机网络状态:是否联网,以及已连接的适配器(不含回环与隧道)的名称、类型、Wi-Fi 名称与信号、IPv4/IPv6、网关、DNS。绝不读取或返回 Wi-Fi 密码。Wi-Fi 名称与 IP 可识别用户。

返回类型:NetworkInfo。空值、用户取消和异常行为以成员及域说明为准。

Sys.GetPerf​

PerfInfo GetPerf()

整机性能(只读):CPU 占用(约 0.5 秒采样,调用阻塞约半秒)与物理内存已用/总量(字节);开机时长请用 Sys.Info().UptimeMs。

返回类型:PerfInfo。空值、用户取消和异常行为以成员及域说明为准。