原生能力
native/ 下的各个包提供 Gio 没有的系统能力。它们不依赖界面模块,可以单独使用。
| 包 | 能力 | 需要的权限 |
|---|---|---|
native/permission |
检查、申请权限 | 无 |
native/screen |
列出显示器;截图 | 截图需要屏幕录制 |
native/input |
移动鼠标、点击、按键 | 读取鼠标位置以外的操作都需要辅助功能 |
native/hotkey |
全局快捷键 | 无 |
native/tray |
托盘图标、提示文字和原生菜单 | 无 |
native/clipboard |
异步读取文本、编码图片、文件路径(macOS / Windows / Linux Wayland、X11) | 无 |
支持三个平台,其他平台(以及 iOS)上,所有函数返回 native.ErrUnsupported,程序照常编译。
| 平台 | 实现 | 说明 |
|---|---|---|
| macOS 14+ | 通过 purego 调用系统框架,不需要 cgo | 需要用户授权,见下文 |
| Windows 10+ | 直接调用 user32、gdi32,不需要 cgo | 不需要授权;坐标按主显示器的 DPI 换算成逻辑点 |
| Linux | 纯 Go 实现 X11 协议,不需要 cgo | 需要 X11 会话;合成输入需要 X 服务器的 XTEST 扩展;逻辑点按 Xft.dpi 换算 |
Linux 的 Wayland 会话不允许普通程序截取整个屏幕或向其他程序注入输入。有 XWayland(DISPLAY 已设置)时可以调用,但只能看到、操作 X11 程序的窗口;没有 DISPLAY 时返回 ErrUnsupported。
错误
所有错误都包装自 native 包里的哨兵值,用 errors.Is 判断:
| 错误 | 含义 |
|---|---|
ErrUnsupported |
当前平台没有实现 |
ErrPermissionDenied |
缺少所需权限 |
ErrInvalidArgument |
参数不合法,比如未知按键名、显示器 ID 为 0 |
ErrTimeout |
系统调用超时(截图超过 10 秒) |
ErrConflict |
全局快捷键已被本进程或其他程序占用 |
ErrFailed |
其他系统错误,错误信息里带状态码 |
if _, err := screen.Capture(id); errors.Is(err, native.ErrPermissionDenied) {
permission.Request(permission.ScreenRecording)
}
permission:权限
ok, err := permission.Granted(permission.Accessibility) // 只查,不弹窗
ok, err := permission.Request(permission.Accessibility) // 可能弹出系统授权框
| 常量 | 系统设置里的名字 | 谁需要 |
|---|---|---|
Accessibility |
辅助功能 | input 包 |
ScreenRecording |
屏幕录制(macOS 15 起叫"屏幕与系统录音") | screen.Capture |
InputMonitoring |
输入监控 | 目前没有功能用到,预留 |
Windows 和 Linux 没有这几种授权,Granted 和 Request 总是返回 true。
在 macOS 上使用时要注意三点:
Request不等用户回答。 它弹框后立刻返回当时的授权状态,通常是false。用户在系统设置里打开开关后,你需要再调Granted确认。false不区分"拒绝过"和"还没问过"。 macOS 不提供这个信息。- 授权记在哪个程序名下。 打包成
.app运行时,授权记在这个 app 名下;在终端里go run,macOS 通常把授权记在终端程序(终端、iTerm、VS Code)名下。屏幕录制权限授予后,一般要重启程序才生效。
screen:显示器与截图
displays, err := screen.Displays()
for _, d := range displays {
fmt.Println(d.ID, d.X, d.Y, d.Width, d.Height, d.PixelWidth, d.PixelHeight, d.Primary)
}
X、Y、Width、Height 是逻辑点坐标,原点在主显示器左上角,副屏可能是负坐标。input 包用同一套坐标。
png, err := screen.Capture(d.ID)
- 返回 PNG 字节,尺寸为
PixelWidth × PixelHeight,不含鼠标指针。 - macOS 上需要屏幕录制权限,自己不会弹框,没有权限直接返回
ErrPermissionDenied。 - 最多阻塞 10 秒。不要在回调里调用,它会让所有窗口卡住。放进 goroutine,结果用
core.Update送回界面。 - macOS 上不能在主线程调用,否则返回
ErrFailed。main函数在window.Main()之前运行在主线程上,也不能在那里调用。
input:合成键鼠
x, y, err := input.MousePosition() // 不需要权限
input.MouseMove(100, 200) // 以下都需要辅助功能权限
input.Click(input.Left) // 在当前鼠标位置点击;Left / Right / Middle
input.Tap("enter") // 按下并松开
input.KeyDown("cmd"); input.Tap("c"); input.KeyUp("cmd") // ⌘C
按键名按美式键盘的物理位置,与当前输入法和键盘布局无关(Linux 例外:X11 按当前布局查找能打出这个字符的键):
- 字母、数字、符号:
a–z、0–9、-=[]\;',./` - 功能键:
entertabspacebackspacedeleteescapehomeendpageuppagedownupdownleftrightf1–f12 - 修饰键:
cmdshiftaltctrl。Windows 和 Linux 上cmd是 Windows 键(Super)。
KeyDown 和 KeyUp 必须成对调用,否则系统会认为这个键一直按着。
hotkey:全局快捷键
其他应用在前台时也能触发。窗口有焦点时才生效的快捷键用 window.Options.Shortcuts。
unregister, err := hotkey.Register("cmd+shift+k", func() {
core.Update(func() { status.SetText("触发了") })
})
defer unregister()
- 写法是
修饰键+按键,至少要一个修饰键。修饰键:cmdctrlalt(或option)shift;按键名同input包。 - 回调在独立的 goroutine 里执行,不持有界面锁,改界面必须包进
core.Update。 - 回调还在执行时又按了几次,只会再触发一次,不会排队。
- 组合键已被占用时返回
ErrConflict。 unregister可以重复调用,只有第一次生效。
cmd 在 Windows 和 Linux 上是 Windows 键(Super)。跨平台的快捷键通常写成 macOS 用 cmd、其他平台用 ctrl。
macOS 上需要 window.Main() 在运行:快捷键事件由主线程的事件循环派发。Windows 和 Linux 有自己的消息线程,不受这个限制。macOS 上不开窗口的纯后台程序暂时用不了,见常见问题。
notification:系统通知
native/notification 提供 Available、RequestPermission、Post 和 Remove,完成回调在独立 goroutine 执行。当前实现 macOS .app 的授权、按 ID 投递/替换和撤回,Linux 桌面 D-Bus 后端,以及 Windows 托盘气泡后端(同一时间显示一条,支持点击回调);其他未支持平台明确返回不支持。kit.Notifier 通过应用适配器接入,macOS 已实现原生前台展示与 Message.OnClick,kit 可通过交互后端接收系统点击并请求 Window.Raise,Linux 已支持声明 actions 的服务的默认点击,系统点击带来的激活令牌可交给 window.Window.Activate(Wayland xdg-activation / X11 启动 ID),完整用法与验收步骤见 模块文档。
clipboard:富剪贴板快照
clipboard.Read(func(data clipboard.Data, err error)) 异步读取;完成回调在后台 goroutine 执行,界面更新需转回 UI 帧。Text 为文本,Images 为 MIME 和编码字节,Files 为路径引用,不打开文件。
macOS 使用 AppKit,图片优先 PNG、其次 TIFF。Windows 使用 Win32,读取 Unicode 文本、PNG、CF_DIB 和 CF_HDROP;DIB 添加 BMP 文件头后以 image/bmp 返回,不解码像素。文件引用优先于资源管理器附带的图片预览。文本、路径 UTF-8 字节与编码图片合计最多 16MiB,文件最多 128 个;错误不返回部分结果。Windows 读取期间保持剪贴板打开,并在关闭前复制所有数据;剪贴板占用时最多尝试 8 次,间隔 15ms。
DIB 支持 40/108/124 字节头的 RGB、调色板和位域布局;压缩位图及带独立颜色配置文件的 V5 布局暂不支持。HTML/RTF 尚未作为独立格式返回。iOS 返回 ErrUnsupported。
组件库的 Input/Textarea 和 CodeEditor 示例已共用这个读取适配;失败时沿原有 Gio 文本通路粘贴。Windows 已通过格式解析、像素解码、错误/上限测试和交叉编译,系统剪贴板及真实窗口粘贴尚未在 Windows 真机验收。
Linux X11 使用独立连接读取 CLIPBOARD,支持 UTF-8/Latin-1 文本、PNG/JPEG/TIFF/BMP/WebP 编码图片、URI 列表及 GNOME 文件引用。只返回本机绝对路径,忽略远程文件主机和非文件 URL,不执行复制或剪切。遵守相同的 16MiB/128 文件限制;处理 INCR 分块传输,整个连接与读取限时 5 秒。读取前后检查所有者及其提供的 TIMESTAMP;不提供时间戳的旧应用若在同一所有者内部更改内容,无法保证跨格式原子快照。
连接使用 DISPLAY 和 XAUTHORITY(默认 ~/.Xauthority),支持 MIT-MAGIC-COOKIE-1。
Wayland 只把剪贴板交给有键盘焦点的客户端,所以不能另开连接:应用把聚焦窗口的连接交给它,clipboard.UseWaylandDisplay(w.WaylandDisplay()),之后 Read 在这个连接上开一个私有事件队列,绑定 seat 的数据设备,读取当前选区提供的类型(与 X11 相同的文本、URI 列表和图片格式及限制,5 秒期限),不干扰 Gio 自己的事件处理。没有传入连接、或合成器没有数据设备时退回 X11/XWayland。这一路径在运行时通过 purego 加载 libwayland-client 1.20+,不用 cgo,用 -tags nowayland 构建可去掉。它只用核心协议,用 wl_proxy_marshal_array_flags 按操作码编组,所有代理共用一个事件分发函数;尚未在 Wayland 桌面上运行。格式、分块协议替身、错误上限测试与交叉编译通过,Linux 桌面真实剪贴板和 XWayland 桥接仍待验收。
托盘:tray
native/tray 提供 macOS 菜单栏图标、Windows 通知区域图标和 Linux SNI 图标,支持勾选、禁用、分隔线与子菜单。不需要权限或 cgo,Linux 需要会话 D-Bus 和运行中的 StatusNotifierHost;没有 Host 时 New 返回 native.ErrUnsupported。iOS、Android 和 Web 不支持。
回调在 Go goroutine 中按托盘串行执行,写 UI 状态使用 core.Update。macOS 的 New 同步等待主线程,放在 window.Main 前,或在不持有 frame lock 的后台 goroutine 中调用。更新和关闭在 macOS 主队列异步应用。详见 tray 模块,运行 go run ./examples/tray -lang zh-CN。