Skip to content

Commit 8ed2afc

Browse files
jinwandalaohu66jinwandalaohu66
committed
docs: 新增 sound/console/keychain 模块完整 API 文档
- sound-module.md: 音效播放、Player 类、全局设置、音效文件名规则、游戏集成指南 - console-module.md: 原生弹窗(alert/input/login/password)、HUD、控制台样式 - keychain-module.md: iOS 安全存储(get/set/delete_password)、与 console 组合用法
1 parent 14eed9b commit 8ed2afc

3 files changed

Lines changed: 858 additions & 49 deletions

File tree

‎docs/console-module.md‎

Lines changed: 291 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,86 +1,328 @@
1-
# console 模块 — 控制台样式控制
1+
# console 模块 — 完整 API 参考
22

3-
Pythonista 兼容的控制台模块，通过 ANSI 转义序列控制输出颜色和样式。
3+
> Pythonista 兼容控制台交互模块。
4+
> 提供原生 UIAlertController 弹窗、HUD 提示、控制台文本样式和清屏功能。
5+
> 所有弹窗阻塞调用线程直到用户响应，匹配 Pythonista 的同步 API 行为。
46
5-
## 完整 API
7+
---
68

7-
### clear() → None
8-
清除控制台所有输出。
9+
## 目录
10+
11+
- [快速开始](#快速开始)
12+
- [弹窗函数](#弹窗函数)
13+
- [alert()](#alert)
14+
- [input_alert()](#input_alert)
15+
- [login_alert()](#login_alert)
16+
- [password_alert()](#password_alert)
17+
- [hud_alert()](#hud_alert)
18+
- [控制台格式](#控制台格式)
19+
- [set_color()](#set_color)
20+
- [set_font()](#set_font)
21+
- [clear()](#clear)
22+
- [write_link()](#write_link)
23+
- [与其他模块组合使用](#与其他模块组合使用)
24+
- [完整示例](#完整示例)
25+
26+
---
27+
28+
## 快速开始
929

1030
```python
1131
import console
12-
console.clear()
32+
33+
# 弹出原生确认框
34+
choice = console.alert('确认', '是否继续?', '继续', '取消')
35+
36+
# 输入文本
37+
name = console.input_alert('姓名', '请输入你的名字')
38+
39+
# HUD 提示
40+
console.hud_alert('操作成功 ✓')
41+
42+
# 彩色输出
43+
console.set_color(1.0, 0.0, 0.0) # 红色
44+
print('这是红色文字')
45+
console.set_color() # 重置
1346
```
1447

15-
### set_color(r=-1, g=-1, b=-1) → None
16-
设置后续 `print()` 输出的前景色。参数为 0.0~1.0 的 RGB 值。不传参数或 r<0 时重置为默认颜色。
48+
---
49+
50+
## 弹窗函数
51+
52+
所有弹窗使用原生 `UIAlertController` 实现，阻塞当前线程直到用户响应。
53+
用户点击 Cancel 时抛出 `KeyboardInterrupt`。
54+
55+
### alert()
1756

1857
```python
19-
console.set_color(1, 0, 0) # 红色
20-
print('这是红色文字')
21-
console.set_color(0, 1, 0) # 绿色
22-
print('这是绿色文字')
58+
console.alert(title, message='', button1='OK', button2='', button3='',
59+
hide_cancel_button=False)
60+
```
61+
62+
显示模态弹窗，最多 3 个自定义按钮 + Cancel。
63+
64+
| 参数 | 类型 | 默认 | 说明 |
65+
|------|------|------|------|
66+
| `title` | str | 必填 | 弹窗标题 |
67+
| `message` | str | `''` | 弹窗消息体 |
68+
| `button1` | str | `'OK'` | 第 1 个按钮标题 |
69+
| `button2` | str | `''` | 第 2 个按钮标题（空则不显示） |
70+
| `button3` | str | `''` | 第 3 个按钮标题（空则不显示） |
71+
| `hide_cancel_button` | bool | `False` | 是否隐藏 Cancel 按钮 |
72+
73+
**返回值**：按钮索引（1-based）。Cancel 抛出 `KeyboardInterrupt`。
74+
75+
```python
76+
try:
77+
idx = console.alert('删除文件?', '此操作不可恢复', '删除', '保留')
78+
if idx == 1:
79+
print('用户选择删除')
80+
elif idx == 2:
81+
print('用户选择保留')
82+
except KeyboardInterrupt:
83+
print('用户取消')
84+
```
85+
86+
### input_alert()
87+
88+
```python
89+
console.input_alert(title, message='', input_text='',
90+
ok_button_title='OK', hide_cancel_button=False)
91+
```
92+
93+
带文本输入框的弹窗。
94+
95+
| 参数 | 类型 | 默认 | 说明 |
96+
|------|------|------|------|
97+
| `title` | str | 必填 | 标题 |
98+
| `message` | str | `''` | 消息 |
99+
| `input_text` | str | `''` | 输入框默认文本 |
100+
| `ok_button_title` | str | `'OK'` | 确认按钮标题 |
101+
| `hide_cancel_button` | bool | `False` | 是否隐藏 Cancel |
102+
103+
**返回值**：用户输入的文本（str）。Cancel 抛出 `KeyboardInterrupt`。
104+
105+
```python
106+
try:
107+
name = console.input_alert('姓名', '请输入你的名字', '张三')
108+
print(f'你好, {name}!')
109+
except KeyboardInterrupt:
110+
print('已取消')
111+
```
112+
113+
### login_alert()
114+
115+
```python
116+
console.login_alert(title, message='', login='', password='',
117+
ok_button_title='OK')
118+
```
119+
120+
登录弹窗，含用户名和密码两个输入框（密码框为安全文本）。
121+
122+
| 参数 | 类型 | 默认 | 说明 |
123+
|------|------|------|------|
124+
| `title` | str | 必填 | 标题 |
125+
| `message` | str | `''` | 消息 |
126+
| `login` | str | `''` | 用户名默认值 |
127+
| `password` | str | `''` | 密码默认值 |
128+
| `ok_button_title` | str | `'OK'` | 确认按钮标题 |
129+
130+
**返回值**：`(username, password)` 元组。Cancel 抛出 `KeyboardInterrupt`。
131+
132+
```python
133+
try:
134+
user, pw = console.login_alert('登录', '请输入服务器凭据')
135+
print(f'用户: {user}')
136+
except KeyboardInterrupt:
137+
print('已取消登录')
138+
```
139+
140+
### password_alert()
141+
142+
```python
143+
console.password_alert(title, message='', password='',
144+
ok_button_title='OK')
145+
```
146+
147+
密码输入弹窗（安全文本框，内容不可见）。
148+
149+
| 参数 | 类型 | 默认 | 说明 |
150+
|------|------|------|------|
151+
| `title` | str | 必填 | 标题 |
152+
| `message` | str | `''` | 消息 |
153+
| `password` | str | `''` | 默认密码 |
154+
| `ok_button_title` | str | `'OK'` | 确认按钮标题 |
155+
156+
**返回值**：用户输入的密码（str）。Cancel 抛出 `KeyboardInterrupt`。
157+
158+
```python
159+
try:
160+
pw = console.password_alert('授权', '请输入管理员密码')
161+
except KeyboardInterrupt:
162+
print('已取消')
163+
```
164+
165+
### hud_alert()
166+
167+
```python
168+
console.hud_alert(message, icon='', duration=1.5)
169+
```
170+
171+
显示一个短暂的 HUD 覆盖提示，自动消失。不阻塞。
172+
173+
| 参数 | 类型 | 默认 | 说明 |
174+
|------|------|------|------|
175+
| `message` | str | 必填 | 提示文本 |
176+
| `icon` | str | `''` | 可选 emoji 或图标 |
177+
| `duration` | float | `1.5` | 显示时长（秒） |
178+
179+
```python
180+
console.hud_alert('已保存 ✓', duration=2.0)
181+
console.hud_alert('下载完成', icon='📦')
182+
```
183+
184+
---
185+
186+
## 控制台格式
187+
188+
### set_color()
189+
190+
```python
191+
console.set_color(r, g, b) # 设置颜色
192+
console.set_color() # 重置为默认颜色
193+
```
194+
195+
设置后续 `print()` 输出的文本颜色。
196+
197+
| 参数 | 类型 | 范围 | 说明 |
198+
|------|------|------|------|
199+
| `r` | float | 0.0–1.0 | 红色分量 |
200+
| `g` | float | 0.0–1.0 | 绿色分量 |
201+
| `b` | float | 0.0–1.0 | 蓝色分量 |
202+
203+
无参数调用时重置为默认颜色。
204+
205+
```python
206+
console.set_color(1, 0, 0) # 红色
207+
print('错误信息')
208+
console.set_color(0, 0.8, 0) # 绿色
209+
print('成功信息')
23210
console.set_color() # 重置
24-
print('这是默认颜色')
25211
```
26212

27-
### set_bold(flag=True) → None
28-
开启或关闭粗体输出。
213+
### set_font()
214+
215+
```python
216+
console.set_font(name, size) # 设置字体
217+
console.set_font() # 重置
218+
```
219+
220+
设置控制台字体。iOS 上主要影响文字粗细（size > 16 显示粗体）。
221+
222+
| 参数 | 类型 | 说明 |
223+
|------|------|------|
224+
| `name` | str | 字体名称（信息性） |
225+
| `size` | float | 字号；> 16 使用粗体 |
226+
227+
### clear()
29228

30229
```python
31-
console.set_bold(True)
32-
print('粗体文字')
33-
console.set_bold(False)
230+
console.clear()
34231
```
35232

36-
### set_font(name='', size=0) → None
37-
设置控制台字体（兼容接口，本 App 固定等宽字体，无实际效果）。
233+
清空控制台输出。
234+
235+
### write_link()
236+
237+
```python
238+
console.write_link(title, url='', font=None)
239+
```
38240

39-
### reset_style() → None
40-
重置所有样式（颜色、粗体），等同于 `set_color()` + `set_bold(False)`。
241+
在控制台输出一个可点击的超链接。
41242

42-
### hud_alert(message, duration=1.0) → None
43-
显示短暂的 HUD 提示（委托给 dialogs.hud_alert 实现）。
243+
| 参数 | 类型 | 说明 |
244+
|------|------|------|
245+
| `title` | str | 链接显示文本 |
246+
| `url` | str | 目标 URL |
247+
| `font` | tuple | 可选 `(font_name, size)` 元组 |
44248

45249
```python
46-
console.hud_alert('操作成功！')
250+
console.write_link('打开 GitHub', 'https://github.com')
47251
```
48252

49-
### alert(title, message='', *button_titles, hide_cancel_button=False)
50-
弹出确认框（委托给 dialogs.alert，兼容接口）。
253+
---
51254

52-
### input_alert(title, message='', input_text='', ok_button_title='OK', hide_cancel_button=False) → str
53-
弹出输入框（委托给 dialogs.input_alert，兼容接口）。
255+
## 与其他模块组合使用
54256

55-
### print_raw(text) → None
56-
直接输出文本（不带换行），等同于 `sys.stdout.write(text)`。
257+
### console + keychain（安全存储 API Key）
258+
259+
```python
260+
import console
261+
import keychain
262+
263+
api_key = keychain.get_password('openai', 'api_key')
264+
if not api_key:
265+
api_key = console.input_alert('API Key', '请输入 OpenAI API Key')
266+
keychain.set_password('openai', 'api_key', api_key)
267+
268+
console.hud_alert('API Key 已就绪 ✓')
269+
```
270+
271+
### console + sound（游戏提示）
272+
273+
```python
274+
import console
275+
import sound
276+
277+
try:
278+
name = console.input_alert('玩家', '输入你的名字')
279+
sound.play_effect('ui:click1')
280+
console.hud_alert(f'欢迎, {name}!')
281+
except KeyboardInterrupt:
282+
pass
283+
```
284+
285+
---
57286

58287
## 完整示例
288+
289+
### 交互式笔记本
290+
59291
```python
60292
import console
61293

62294
console.clear()
63-
64-
# 彩色输出
65295
console.set_color(0.2, 0.6, 1.0)
66-
print('=== 天气预报 ===')
296+
print('=== 我的笔记本 ===')
297+
console.set_color()
67298

68-
console.set_bold(True)
69-
console.set_color(1, 0.3, 0)
70-
print('🌡️ 温度：28°C')
299+
notes = []
71300

72-
console.set_color(0, 0.8, 0.4)
73-
print('💧 湿度：65%')
301+
while True:
302+
try:
303+
choice = console.alert('操作', '', '添加笔记', '查看全部', '清空')
304+
except KeyboardInterrupt:
305+
break
74306

75-
console.reset_style()
76-
print('数据更新于 2025-01-01')
307+
if choice == 1:
308+
try:
309+
note = console.input_alert('新笔记', '输入内容')
310+
notes.append(note)
311+
console.hud_alert(f'已添加（共 {len(notes)} 条）')
312+
except KeyboardInterrupt:
313+
pass
314+
elif choice == 2:
315+
if notes:
316+
for i, n in enumerate(notes, 1):
317+
console.set_color(0.8, 0.8, 0.2)
318+
print(f'{i}. {n}')
319+
console.set_color()
320+
else:
321+
console.hud_alert('暂无笔记')
322+
elif choice == 3:
323+
notes.clear()
324+
console.clear()
325+
console.hud_alert('已清空')
77326

78-
console.hud_alert('数据已刷新')
327+
console.hud_alert('退出笔记本')
79328
```
80-
81-
## 注意事项
82-
- set_color 使用 0.0~1.0 的 RGB 浮点值（与 Pythonista 一致）
83-
- 颜色通过 ANSI 256 色转义序列实现
84-
- App 控制台支持完整 ANSI 彩色（16/256/RGB）
85-
- set_font 为兼容接口，无实际效果
86-
- hud_alert 和 alert 内部委托给 dialogs 模块

0 commit comments

Comments
 (0)