剪贴板

auto.set_clip('要复制的文字')
text = auto.get_clip()
auto.copy(ctrl)                          # Ctrl+A → Ctrl+C，返回剪贴板文字
auto.paste('粘贴内容', ctrl)              # 可选先 set_clip，再 Ctrl+V 到 ctrl

综合方法（推荐）

面向小白的一站式 API：一次调用完成多步操作，返回统一结构（含 report 可读报告）。
items 严格按内容在原文中的出现顺序排列（文字、图片、文件混排时不重排）。

# 1. 内容复制 — 选中区域全选→复制→解析（笔记 / 图文混排）
result = auto.copy_content(ctrl, mode='uia')
print(result['report'])

# 2. 读剪贴板 — 不复制，只解析当前剪贴板（返回含 items 数组，结构同 copy_content）
clip = auto.inspect_clipboard()
print(clip['report'])                       # 调试：可读报告
if clip['success']:
    for item in clip['items']:              # 程序：按顺序遍历
        if item['type'] == 'text':
            print('文字:', item['content'])
        elif item['type'] == 'image':
            print('图片:', item['content'])   # 本地临时路径
        elif item['type'] == 'file':
            print('文件:', item['content'])
    texts  = [i['content'] for i in clip['items'] if i['type'] == 'text']
    images = [i['content'] for i in clip['items'] if i['type'] == 'image']

# 3. 清空 → 输入 → 回车发送
auto.type_and_send('你好', input_ctrl, mode='uia')

WinAuto.show_content(result)

点击弹窗后读内容（通用组合）

不提供 click_read_note 等专用封装；用现有通用方法分步即可（ClassName 按目标程序填写）：

POPUP_CLASSES = ['NoteWnd', 'ChatRecordWnd']   # 示例，请改为实际类名
before = auto.snapshot_popups(POPUP_CLASSES)
auto.click(msg_ctrl, mode='uia')
popup_hwnd = auto.wait_popup(POPUP_CLASSES, before, timeout=5.0)
if popup_hwnd:
    popup = WinAuto(popup_hwnd)
    popup.activate()
    body = popup.find(ctrl_type='EditControl', depth=25)   # 或 ListControl 等
    result = popup.copy_content(body, mode='uia')
    popup.close_window()
    print(result['report'])

返回字段（综合方法通用）

字段	说明
`success`	是否成功
`items`	按文档顺序的内容列表（text / image / file）
`text`	所有文字段拼接（顺序与 items 中 text 一致）
`files`	所有文件/图片路径（顺序与 items 中 file/image 一致）
`report`	可读测试报告（调试软件 / 直接 print）
`summary`	简短摘要
`item_count`	`items` 长度

兼容旧名：copy_and_parse() 等同 copy_content()。

与普通 `copy()` 的区别

方法	适用	返回
`copy(ctrl)`	普通输入框，只要纯文字	`str`
`copy(ctrl, items=True)`	已复制或刚复制后，需要 `items` 数组	`dict`（同 `inspect_clipboard()`）
`copy_content(ctrl)`	笔记、图文混排、带附件（推荐）	`dict`（含 `items` + `report`）
`inspect_clipboard()`	已 Ctrl+C，查看剪贴板	`dict`（含 `items` + `report`，同 copy_content）

# 笔记 / 图文：用 copy_content，items 可直接遍历
result = auto.copy_content(note_ctrl, mode='uia')
for item in result['items']:
    if item['type'] == 'text':
        print(item['content'])
    elif item['type'] == 'image':
        print('图片路径:', item['content'])

# 已手动 Ctrl+C 后：inspect_clipboard 返回相同结构，无需再 copy
clip = auto.inspect_clipboard()
assert clip['success']
for item in clip['items']:
    process(item['type'], item['content'])

# 等价写法：copy + 解析
result = auto.copy(note_ctrl, mode='uia', items=True)
items = result['items']   # list[dict]，与 inspect_clipboard()['items'] 相同

item 结构：{'type': 'text'|'image'|'file', 'content': str}，content 为文字或本地文件路径。

底层高级 API（一般不必直接用）：read_clipboard()、copy_rich()、parse_clipboard() 等，由 WinAuto.copy_content() / inspect_clipboard() 内部调用。

API 参考

剪贴板

✨set_clip

写入系统剪贴板纯文本。

auto.set_clip('要复制的文字')

参数：

参数名	类型	默认值	描述
text	str	无	要写入的文本

返回值：

类型：WinAuto

✨set_clip_files

将文件路径写入剪贴板（CF_HDROP），粘贴到聊天输入框可发送文件。

auto.set_clip_files(r'C:\Users\you\Desktop\demo.png')
# 或多个文件
auto.set_clip_files([r'C:\a.png', r'C:\b.pdf'])

ctrl = auto.find(ctrl_type='EditControl', aid='chat_input')
auto.paste('', ctrl, mode='uia')   # Ctrl+V 粘贴文件到输入框

参数：

参数名	类型	默认值	描述
paths	str \| list[str]	无	单个路径或路径列表

返回值：

类型：WinAuto

✨get_clip

读取系统剪贴板纯文本。

text = auto.get_clip()

返回值：

类型：str

✨copy

全选目标控件后复制；可选解析为结构化 dict。

text = auto.copy(ctrl)
result = auto.copy(ctrl, mode='uia', items=True)

参数：

参数名	类型	默认值	描述
ctrl	Control	None	复制前全选的目标控件
mode	str	None	操作模式
items	bool	False	`False` 返回纯文本；`True` 复制后解析，返回结构化 dict

返回值：

items=False：str — CF_UNICODETEXT 内容（笔记可能是 '标题\r[图片]' 占位符）
items=True：dict — 同 inspect_clipboard()，含 items 数组

✨paste

text 非空时先 set_clip，再 keys('{Ctrl}v', ctrl)。

auto.paste('粘贴内容', ctrl)

参数：

参数名	类型	默认值	描述
text	str	''	要粘贴的文本；空则粘贴当前剪贴板
ctrl	Control	None	目标控件
mode	str	None	操作模式

返回值：

类型：WinAuto

✨copy_content

推荐一站式：点击 → 全选 → 复制 → 解析。

result = auto.copy_content(note_ctrl, mode='uia')
assert result['success']
for item in result['items']:
    process(item['type'], item['content'])
WinAuto.show_content(result)

参数：

参数名	类型	默认值	描述
ctrl	Control	None	目标控件
mode	str	None	操作模式
clear_first	bool	True	复制前是否 `empty_clipboard()`
rich	bool	True	是否解析富文本笔记 HTML 元数据（保序）
poll_timeout	float	2.5	等待剪贴板数据的超时（秒）

返回值：

类型：dict

字段	类型	描述
success	bool	是否有有效内容
items	list[dict]	按文档顺序：`type` + `content`
text	str	所有文字段拼接
files	list[str]	所有文件/图片路径
report	str	可读调试报告
summary	str	简短摘要
item_count	int	`len(items)`
metadata	dict	原始剪贴板格式（可选）
error	str	失败原因（空串表示无错误）

✨inspect_clipboard

不触发复制，仅解析当前剪贴板。返回字段与 copy_content() 完全相同（含 items 数组；无 clear_first 行为）。

clip = auto.inspect_clipboard()

# 调试：可读报告
print(clip['report'])

# 程序：遍历 items（与 copy_content 相同）
if clip['success']:
    for item in clip['items']:
        print(item['type'], item['content'])
    texts  = [i['content'] for i in clip['items'] if i['type'] == 'text']
    images = [i['content'] for i in clip['items'] if i['type'] == 'image']
    files  = clip['files']   # items 中 image+file 的路径汇总

返回示例（富文本笔记图文混排）：

{
    'success': True,
    'items': [
        {'type': 'text',  'content': '第一段'},
        {'type': 'image', 'content': r'C:\Users\...\Temp\img.jpg'},
        {'type': 'text',  'content': '第二段'},
    ],
    'text': '第一段\n第二段',
    'files': [r'C:\Users\...\Temp\img.jpg'],
    'report': '══════ 剪贴板 ══════\n...',
    'summary': '第一段\n[图片] C:\\Users\\...\\img.jpg\n第二段',
    'item_count': 3,
    'metadata': {'13': '...', '15': [...]},
    'raw_clipboard': {'text': '...', 'files': [...], 'formats': [...]},
    'error': '',
}

纯文本剪贴板时 items 通常为 [{'type': 'text', 'content': '...'}]；files 为空列表。

参数：

参数名	类型	默认值	描述
rich	bool	True	是否解析富文本笔记 HTML 元数据

返回值：

类型：dict（字段同 copy_content；items 为 list[dict]，每项含 type + content）

字段	类型	描述
success	bool	是否有有效内容
items	list[dict]	按文档顺序：`{'type': 'text'\|'image'\|'file', 'content': str}`
text	str	所有文字段拼接
files	list[str]	所有文件/图片路径
report	str	可读调试报告
summary	str	简短摘要（`format_result` 风格）
item_count	int	`len(items)`
metadata	dict	原始剪贴板格式（可选）
raw_clipboard	dict	`{text, files, formats, metadata}` 原始读取结果
error	str	失败原因（空串表示无错误）

✨read_clipboard

读取全格式剪贴板元数据。

meta = auto.read_clipboard()
for fmt_id, data in meta.items():
    print(fmt_id, type(data), repr(str(data)[:80]))

返回值：

类型：dict
描述：全格式元数据 format_id -> data

✨read_clipboard_all

info = auto.read_clipboard_all()
print('text:', info.get('text', '')[:100])
print('files:', info.get('files'))
print('formats:', info.get('formats'))

返回值：

类型：dict
描述：{text, files, formats, metadata}

✨copy_rich

全选复制 + 元数据，不解析 items。

ctrl = auto.find(ctrl_type='DocumentControl', aid='RootWebArea', depth=9)
meta = auto.copy_rich(ctrl, mode='uia')
print(meta.keys())

返回值：

类型：dict

✨parse_clipboard

解析剪贴板为结构化内容。

# 解析当前剪贴板
parsed = auto.parse_clipboard(rich=True)
print(parsed.get('text'))
print(parsed.get('items'))

# 或传入已有 metadata
meta = auto.read_clipboard()
parsed = auto.parse_clipboard(metadata=meta, rich=True)

参数：

参数名	类型	默认值	描述
metadata	dict	None	原始元数据；不传则读当前剪贴板
rich	bool	True	是否解析笔记 HTML

返回值：

类型：dict
描述：{text, files, items}

✨empty_clipboard

清空剪贴板。

auto.empty_clipboard()
print(auto.get_clip())   # 通常为空

返回值：

类型：WinAuto

✨wait_clipboard

轮询直到剪贴板有数据。

auto.copy(ctrl)   # 或其他会写入剪贴板的操作
data = auto.wait_clipboard(timeout=3.0)
print(data.get('text', '')[:80])

参数：

参数名	类型	默认值	描述
timeout	float	3.0	超时（秒）

返回值：

类型：dict

#剪贴板

#剪贴板

#综合方法（推荐）

#综合方法（推荐）

#点击弹窗后读内容（通用组合）

#返回字段（综合方法通用）

#与普通 copy() 的区别

#API 参考

#剪贴板

#✨set_clip

#✨set_clip_files

#✨get_clip

#✨copy

#✨paste

#✨copy_content

#✨inspect_clipboard

#✨read_clipboard

#✨read_clipboard_all

#✨copy_rich

#✨parse_clipboard

#✨empty_clipboard

#✨wait_clipboard

剪贴板

剪贴板

综合方法（推荐）

综合方法（推荐）

点击弹窗后读内容（通用组合）

返回字段（综合方法通用）

与普通 `copy()` 的区别

API 参考

剪贴板

✨set_clip

✨set_clip_files

✨get_clip

✨copy

✨paste

✨copy_content

✨inspect_clipboard

✨read_clipboard

✨read_clipboard_all

✨copy_rich

✨parse_clipboard

✨empty_clipboard

✨wait_clipboard