API: wingman.clipboard

剪贴板模块，提供系统剪贴板的读写能力，支持文本、HTML、图像和文件列表。

平台支持

能力	Windows	macOS	Linux (X11)
文本	完整	完整	完整
HTML	完整	完整	纯文本降级（setHTML/getHTML 直接透传纯文本）
图像	完整	完整	未实现（setImage 恒返回 false，hasImage 恒 false，getImage 恒空）
文件列表	完整	完整	完整

模块概述

clipboard 模块提供以下能力：

• 文本剪贴板 - 设置/读取/检测纯文本内容
• HTML 剪贴板 - 设置/读取/检测富文本 HTML 内容（Linux 上为纯文本降级）
• 图像剪贴板 - 设置/读取/检测位图图像（仅 Windows/macOS）
• 文件剪贴板 - 设置/读取/检测文件列表（拖拽场景）
• 通用操作 - 清空剪贴板、判断是否为空

---

文本操作

setText(text) / setText(text)

说明：设置剪贴板的纯文本内容。

函数签名：

setText(text: str) -> bool

setText(text: string) -> boolean

参数：

• text - 要写入剪贴板的文本

返回：

• bool/boolean - 是否成功

from wingman import clipboard

clipboard.setText("hello world")

---

getText() / getText()

说明：读取剪贴板的纯文本内容。

函数签名：

getText() -> str

getText() -> string

参数：

• 无

返回：

• str/string - 剪贴板中的文本内容

from wingman import clipboard

text = clipboard.getText()
print(text)

---

hasText() / hasText()

说明：检测剪贴板中是否包含文本内容。

函数签名：

hasText() -> bool

hasText() -> boolean

参数：

• 无

返回：

• bool/boolean - 是否包含文本

from wingman import clipboard

if clipboard.hasText():
    print(clipboard.getText())

---

HTML 操作

setHTML(html) / setHTML(html)

说明：设置剪贴板的 HTML 富文本内容。

函数签名：

setHTML(html: str) -> bool

setHTML(html: string) -> boolean

参数：

• html - 要写入剪贴板的 HTML 内容

返回：

• bool/boolean - 是否成功

from wingman import clipboard

clipboard.setHTML("<b>bold text</b>")

---

getHTML() / getHTML()

说明：读取剪贴板的 HTML 富文本内容。

函数签名：

getHTML() -> str

getHTML() -> string

参数：

• 无

返回：

• str/string - 剪贴板中的 HTML 内容

from wingman import clipboard

html = clipboard.getHTML()

---

hasHTML() / hasHTML()

说明：检测剪贴板中是否包含 HTML 内容。

函数签名：

hasHTML() -> bool

hasHTML() -> boolean

参数：

• 无

返回：

• bool/boolean - 是否包含 HTML

from wingman import clipboard

if clipboard.hasHTML():
    print(clipboard.getHTML())

---

图像操作

setImage(imageData, width, height) / setImage(imageData, width, height)

说明：设置剪贴板中的位图图像。要求原始像素数据（字节流）以及图像的宽高，模块内部按 RGB/BGR 像素缓冲写入系统剪贴板。

函数签名：

setImage(imageData: str, width: int, height: int) -> bool

setImage(imageData: string, width: number, height: number) -> boolean

参数：

• imageData - 图像数据（字节字符串）
• width - 图像宽度（像素）
• height - 图像高度（像素）

返回：

• bool/boolean - 是否成功；当任一参数类型不匹配（非字符串/非整数）时直接返回 false

from wingman import clipboard

# 写入 2x2 像素图像数据
data = b"\xff\x00\x00" * 4  # 像素字节流
clipboard.setImage(data, 2, 2)

---

getImage() / getImage()

说明：读取剪贴板中的位图图像。

函数签名：

getImage() -> dict | None

getImage() -> table | nil

参数：

• 无

返回：

• 成功时返回对象 { data: str, width: int, height: int }：
  • data - 图像像素字节流
  • width - 图像宽度（像素）
  • height - 图像高度（像素）
• 当剪贴板无图像时返回 None/nil

from wingman import clipboard

img = clipboard.getImage()
if img is not None:
    print(img["width"], img["height"], len(img["data"]))

---

hasImage() / hasImage()

说明：检测剪贴板中是否包含图像。

函数签名：

hasImage() -> bool

hasImage() -> boolean

参数：

• 无

返回：

• bool/boolean - 是否包含图像

from wingman import clipboard

if clipboard.hasImage():
    img = clipboard.getImage()

---

文件列表操作

setFiles(files) / setFiles(files)

说明：设置剪贴板中的文件列表（用于模拟文件拖拽/复制）。参数既支持单个字符串数组，也支持多个字符串参数。

函数签名：

setFiles(files: list[str]) -> bool

setFiles(files: string[]) -> boolean

参数：

• files - 文件路径数组；也可传入多个字符串参数（每个字符串会被收集为路径，数组参数中的字符串元素也会被展开）

返回：

• bool/boolean - 是否成功

from wingman import clipboard

# 传入数组
clipboard.setFiles(["C:/a.txt", "C:/b.txt"])

---

getFiles() / getFiles()

说明：读取剪贴板中的文件列表。

函数签名：

getFiles() -> list[str]

getFiles() -> string[]

参数：

• 无

返回：

• list[str]/string[] - 文件路径数组

from wingman import clipboard

files = clipboard.getFiles()
for f in files:
    print(f)

---

hasFiles() / hasFiles()

说明：检测剪贴板中是否包含文件列表。

函数签名：

hasFiles() -> bool

hasFiles() -> boolean

参数：

• 无

返回：

• bool/boolean - 是否包含文件

from wingman import clipboard

if clipboard.hasFiles():
    print(clipboard.getFiles())

---

通用操作

clear() / clear()

说明：清空剪贴板中的所有内容。

函数签名：

clear() -> None

clear() -> nil

参数：

• 无

返回：

• 无

from wingman import clipboard

clipboard.clear()

---

isEmpty() / isEmpty()

说明：检测剪贴板是否为空。

函数签名：

isEmpty() -> bool

isEmpty() -> boolean

参数：

• 无

返回：

• bool/boolean - 是否为空

from wingman import clipboard

if clipboard.isEmpty():
    print("clipboard is empty")

---

完整示例

Python

from wingman import clipboard

# 文本读写
clipboard.setText("hello")
assert clipboard.hasText()
print(clipboard.getText())

# HTML 读写
clipboard.setHTML("<i>styled</i>")
assert clipboard.hasHTML()

# 文件列表
clipboard.setFiles(["C:/report.csv", "C:/data.json"])
if clipboard.hasFiles():
    print(clipboard.getFiles())

# 判空与清空
if not clipboard.isEmpty():
    clipboard.clear()

Lua

local wingman = require("wingman")

-- 文本读写
wingman.clipboard.setText("hello")
assert(wingman.clipboard.hasText())
print(wingman.clipboard.getText())

-- HTML 读写
wingman.clipboard.setHTML("<i>styled</i>")
assert(wingman.clipboard.hasHTML())

-- 文件列表
wingman.clipboard.setFiles({ "C:/report.csv", "C:/data.json" })
if wingman.clipboard.hasFiles() then
    print(wingman.clipboard.getFiles())
end

-- 判空与清空
if not wingman.clipboard.isEmpty() then
    wingman.clipboard.clear()
end

---

可用接口

Python 函数	Lua 函数	说明	参数
setText(text)	setText(text)	设置文本	text: 文本内容
getText()	getText()	读取文本	无
hasText()	hasText()	是否含文本	无
setHTML(html)	setHTML(html)	设置 HTML	html: HTML 内容
getHTML()	getHTML()	读取 HTML	无
hasHTML()	hasHTML()	是否含 HTML	无
setImage(imageData, width, height)	setImage(imageData, width, height)	设置图像	imageData: 像素字节流 width: 宽度 height: 高度
getImage()	getImage()	读取图像	无
hasImage()	hasImage()	是否含图像	无
setFiles(files)	setFiles(files)	设置文件列表	files: 路径数组（也支持多字符串参数）
getFiles()	getFiles()	读取文件列表	无
hasFiles()	hasFiles()	是否含文件列表	无
clear()	clear()	清空剪贴板	无
isEmpty()	isEmpty()	是否为空	无