From 9c7aa46e23cf3d6f29a243a6d3bf50c772b69929 Mon Sep 17 00:00:00 2001 From: tukuaiai Date: Sat, 13 Dec 2025 17:05:52 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E5=8A=A8=E6=80=81?= =?UTF-8?q?=E8=A7=86=E5=9B=BE=E5=AF=B9=E9=BD=90=E5=AE=9E=E7=8E=B0=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../references/动态视图对齐实现文档.md | 814 +++++++++--------- 1 file changed, 407 insertions(+), 407 deletions(-) diff --git a/skills/telegram-dev/references/动态视图对齐实现文档.md b/skills/telegram-dev/references/动态视图对齐实现文档.md index 2cdeda4..e78e9fb 100644 --- a/skills/telegram-dev/references/动态视图对齐实现文档.md +++ b/skills/telegram-dev/references/动态视图对齐实现文档.md @@ -1,407 +1,407 @@ -# 📊 动态视图对齐 - Telegram 数据展示指南 - -> 专业的等宽字体数据对齐和格式化方案 - ---- - -## 📑 目录 - -- [核心原理](#核心原理) -- [实现代码](#实现代码) -- [格式化系统](#格式化系统) -- [应用示例](#应用示例) -- [最佳实践](#最佳实践) - ---- - -## 核心原理 - -### 问题场景 - -在 Telegram Bot 中展示排行榜、数据表格时，需要在等宽字体环境（代码块）中实现完美对齐： - -**❌ 未对齐：** -``` -1. BTC $1.23B $45000 +5.23% -10. DOGE $123.4M $0.0789 -1.45% -``` - -**✅ 动态对齐：** -``` -1. BTC $1.23B $45,000 +5.23% -10. DOGE $123.4M $0.0789 -1.45% -``` - -### 三步对齐算法 - -``` -步骤 1: 扫描数据，计算每列最大宽度 -步骤 2: 根据列类型应用对齐规则（文本左对齐，数字右对齐） -步骤 3: 拼接成最终文本 -``` - -### 对齐规则 - -| 列索引 | 数据类型 | 对齐方式 | 示例 | -|--------|----------|----------|------| -| 列 0 | 序号 | 左对齐 | `1. `, `10. ` | -| 列 1 | 符号 | 左对齐 | `BTC `, `DOGE ` | -| 列 2+ | 数值 | 右对齐 | ` $1.23B`, `$123.4M` | - ---- - -## 实现代码 - -### 核心函数 - -```python -def dynamic_align_format(data_rows): - """ - 动态视图对齐格式化 - - 参数: - data_rows: 二维列表 [["1.", "BTC", "$1.23B", ...], ...] - - 返回: - 对齐后的文本字符串 - """ - if not data_rows: - return "暂无数据" - - # ========== 步骤 1: 计算每列最大宽度 ========== - max_widths = [] - for row in data_rows: - for i, cell in enumerate(row): - # 动态扩展列表 - if i >= len(max_widths): - max_widths.append(0) - # 更新最大宽度 - max_widths[i] = max(max_widths[i], len(str(cell))) - - # ========== 步骤 2: 格式化每一行 ========== - formatted_rows = [] - for row in data_rows: - formatted_cells = [] - for i, cell in enumerate(row): - cell_str = str(cell) - - if i == 0 or i == 1: - # 序号列和符号列 - 左对齐 - formatted_cells.append(cell_str.ljust(max_widths[i])) - else: - # 数值列 - 右对齐 - formatted_cells.append(cell_str.rjust(max_widths[i])) - - # 用空格连接所有单元格 - formatted_line = ' '.join(formatted_cells) - formatted_rows.append(formatted_line) - - # ========== 步骤 3: 拼接成最终文本 ========== - return '\n'.join(formatted_rows) -``` - -### 使用示例 - -```python -# 准备数据 -data_rows = [ - ["1.", "BTC", "$1.23B", "$45,000", "+5.23%"], - ["2.", "ETH", "$890.5M", "$2,500", "+3.12%"], - ["10.", "DOGE", "$123.4M", "$0.0789", "-1.45%"] -] - -# 调用对齐函数 -aligned_text = dynamic_align_format(data_rows) - -# 输出到 Telegram -text = f"""📊 排行榜 -``` -{aligned_text} -``` -💡 说明文字""" -``` - ---- - -## 格式化系统 - -### 1. 交易量智能缩写 - -```python -def format_volume(volume: float) -> str: - """智能格式化交易量""" - if volume >= 1e9: - return f"${volume/1e9:.2f}B" # 十亿 → $1.23B - elif volume >= 1e6: - return f"${volume/1e6:.2f}M" # 百万 → $890.5M - elif volume >= 1e3: - return f"${volume/1e3:.2f}K" # 千 → $123.4K - else: - return f"${volume:.2f}" # 小数 → $45.67 -``` - -**示例：** -```python -format_volume(1234567890) # → "$1.23B" -format_volume(890500000) # → "$890.5M" -format_volume(123400) # → "$123.4K" -``` - -### 2. 价格智能精度 - -```python -def format_price(price: float) -> str: - """智能格式化价格 - 根据大小自动调整小数位""" - if price >= 1000: - return f"${price:,.0f}" # 千元以上 → $45,000 - elif price >= 1: - return f"${price:.3f}" # 1-1000 → $2.500 - elif price >= 0.01: - return f"${price:.4f}" # 0.01-1 → $0.0789 - else: - return f"${price:.6f}" # <0.01 → $0.000123 -``` - -### 3. 涨跌幅格式化 - -```python -def format_change(change_percent: float) -> str: - """格式化涨跌幅 - 正数添加+号""" - if change_percent >= 0: - return f"+{change_percent:.2f}%" - else: - return f"{change_percent:.2f}%" -``` - -**示例：** -```python -format_change(5.234) # → "+5.23%" -format_change(-1.456) # → "-1.46%" -format_change(0) # → "+0.00%" -``` - -### 4. 资金流向智能显示 - -```python -def format_flow(net_flow: float) -> str: - """格式化资金净流向""" - sign = "+" if net_flow >= 0 else "" - abs_flow = abs(net_flow) - - if abs_flow >= 1e9: - return f"{sign}{net_flow/1e9:.2f}B" - elif abs_flow >= 1e6: - return f"{sign}{net_flow/1e6:.2f}M" - elif abs_flow >= 1e3: - return f"{sign}{net_flow/1e3:.2f}K" - else: - return f"{sign}{net_flow:.0f}" -``` - ---- - -## 应用示例 - -### 完整排行榜实现 - -```python -def get_volume_ranking(data, limit=10): - """获取交易量排行榜""" - - # 1. 数据处理和排序 - sorted_data = sorted(data, key=lambda x: x['volume'], reverse=True)[:limit] - - # 2. 准备数据行 - data_rows = [] - for i, item in enumerate(sorted_data, 1): - symbol = item['symbol'] - volume = item['volume'] - price = item['price'] - change = item['change_percent'] - - # 格式化各列 - volume_str = format_volume(volume) - price_str = format_price(price) - change_str = format_change(change) - - # 添加到数据行 - data_rows.append([ - f"{i}.", # 序号 - symbol, # 币种 - volume_str, # 交易量 - price_str, # 价格 - change_str # 涨跌幅 - ]) - - # 3. 动态对齐格式化 - aligned_data = dynamic_align_format(data_rows) - - # 4. 构建最终消息 - text = f"""🎪 热币排行 - 交易量榜 🎪 -⏰ 更新 {datetime.now().strftime('%Y-%m-%d %H:%M')} -📊 排序 24小时交易量(USDT) / 降序 -排名/币种/24h交易量/价格/24h涨跌 -``` -{aligned_data} -``` -💡 交易量反映市场活跃度和流动性""" - - return text -``` - -### 输出效果 - -``` -🎪 热币排行 - 交易量榜 🎪 -⏰ 更新 2025-10-29 14:30 -📊 排序 24小时交易量(USDT) / 降序 -排名/币种/24h交易量/价格/24h涨跌 - -1. BTC $1.23B $45,000 +5.23% -2. ETH $890.5M $2,500 +3.12% -3. SOL $567.8M $101 +8.45% -4. BNB $432.1M $315 +2.67% -5. XRP $345.6M $0.589 -1.23% - -💡 交易量反映市场活跃度和流动性 -``` - ---- - -## 最佳实践 - -### 1. 数据准备规范 - -```python -# ✅ 推荐：使用列表嵌套结构 -data_rows = [ - ["1.", "BTC", "$1.23B", "$45,000", "+5.23%"], - ["2.", "ETH", "$890.5M", "$2,500", "+3.12%"] -] - -# ❌ 不推荐：使用字典（需要额外转换） -data_rows = [ - {"rank": 1, "symbol": "BTC", ...}, -] -``` - -### 2. 格式化顺序 - -```python -# ✅ 推荐：先格式化，再对齐 -for i, item in enumerate(data, 1): - volume_str = format_volume(item['volume']) # 格式化 - price_str = format_price(item['price']) # 格式化 - change_str = format_change(item['change']) # 格式化 - - data_rows.append([f"{i}.", symbol, volume_str, price_str, change_str]) - -aligned_data = dynamic_align_format(data_rows) # 对齐 -``` - -### 3. Telegram 消息嵌入 - -```python -# ✅ 推荐：使用代码块包裹对齐数据 -text = f"""📊 排行榜标题 -⏰ 更新时间 {time} -``` -{aligned_data} -``` -💡 说明文字""" - -# ❌ 不推荐：直接输出（Telegram会自动换行，破坏对齐） -text = f"""📊 排行榜标题 -{aligned_data} -💡 说明文字""" -``` - -### 4. 空数据处理 - -```python -# ✅ 推荐：在函数开头检查 -def dynamic_align_format(data_rows): - if not data_rows: - return "暂无数据" - # ... 正常处理逻辑 ... -``` - -### 5. 性能优化 - -```python -# ✅ 推荐：限制数据量 -sorted_data = sorted(data, key=lambda x: x['volume'], reverse=True)[:limit] -aligned_data = dynamic_align_format(data_rows) - -# ❌ 不推荐：处理全量后截取（浪费资源） -aligned_data = dynamic_align_format(all_data_rows) -final_data = aligned_data.split('\n')[:limit] -``` - -### 6. 中文字符支持（可选） - -```python -def get_display_width(text): - """计算文本显示宽度（中文=2，英文=1）""" - width = 0 - for char in text: - if ord(char) > 127: # 非ASCII字符 - width += 2 - else: - width += 1 - return width - -# 在 dynamic_align_format 中使用 -max_widths[i] = max(max_widths[i], get_display_width(str(cell))) -``` - ---- - -## 设计优势 - -### 与硬编码方式对比 - -| 特性 | 传统硬编码 | 动态对齐 | -|------|-----------|---------| -| 列宽适配 | 手动指定 | 自动计算 | -| 维护成本 | 高（需多处修改） | 低（一次编写） | -| 对齐精度 | 易出偏差 | 字符级精确 | -| 扩展性 | 需重构 | 自动支持任意列 | -| 性能 | O(n) | O(n×m) | - -### 技术亮点 - -- **自适应宽度**: 无论数据如何变化，始终完美对齐 -- **智能对齐规则**: 符合人类阅读习惯（文本左，数字右） -- **等宽字体完美支持**: 空格填充确保对齐效果 -- **高复用性**: 一个函数适用所有排行榜场景 - ---- - -## 快速参考 - -### 函数签名 - -```python -dynamic_align_format(data_rows: list[list]) -> str -format_volume(volume: float) -> str -format_price(price: float) -> str -format_change(change_percent: float) -> str -format_flow(net_flow: float) -> str -``` - -### 时间复杂度 - -- 宽度计算: O(n × m) -- 格式化输出: O(n × m) -- 总复杂度: O(n × m) - 线性时间，高效实用 - -### 性能基准 - -- 处理 100 行 × 5 列: ~1ms -- 处理 1000 行 × 5 列: ~5-10ms -- 内存占用: 最小 - ---- - -**这份指南提供了 Telegram Bot 专业数据展示的完整解决方案！** +# 📊 动态视图对齐 - Telegram 数据展示指南 + +> 专业的等宽字体数据对齐和格式化方案 + +--- + +## 📑 目录 + +- [核心原理](#核心原理) +- [实现代码](#实现代码) +- [格式化系统](#格式化系统) +- [应用示例](#应用示例) +- [最佳实践](#最佳实践) + +--- + +## 核心原理 + +### 问题场景 + +在 Telegram Bot 中展示排行榜、数据表格时，需要在等宽字体环境（代码块）中实现完美对齐： + +**❌ 未对齐：** +``` +1. BTC $1.23B $45000 +5.23% +10. DOGE $123.4M $0.0789 -1.45% +``` + +**✅ 动态对齐：** +``` +1. BTC $1.23B $45,000 +5.23% +10. DOGE $123.4M $0.0789 -1.45% +``` + +### 三步对齐算法 + +``` +步骤 1: 扫描数据，计算每列最大宽度 +步骤 2: 根据列类型应用对齐规则（文本左对齐，数字右对齐） +步骤 3: 拼接成最终文本 +``` + +### 对齐规则 + +| 列索引 | 数据类型 | 对齐方式 | 示例 | +|--------|----------|----------|------| +| 列 0 | 序号 | 左对齐 | `1. `, `10. ` | +| 列 1 | 符号 | 左对齐 | `BTC `, `DOGE ` | +| 列 2+ | 数值 | 右对齐 | ` $1.23B`, `$123.4M` | + +--- + +## 实现代码 + +### 核心函数 + +```python +def dynamic_align_format(data_rows): + """ + 动态视图对齐格式化 + + 参数: + data_rows: 二维列表 [["1.", "BTC", "$1.23B", ...], ...] + + 返回: + 对齐后的文本字符串 + """ + if not data_rows: + return "暂无数据" + + # ========== 步骤 1: 计算每列最大宽度 ========== + max_widths = [] + for row in data_rows: + for i, cell in enumerate(row): + # 动态扩展列表 + if i >= len(max_widths): + max_widths.append(0) + # 更新最大宽度 + max_widths[i] = max(max_widths[i], len(str(cell))) + + # ========== 步骤 2: 格式化每一行 ========== + formatted_rows = [] + for row in data_rows: + formatted_cells = [] + for i, cell in enumerate(row): + cell_str = str(cell) + + if i == 0 or i == 1: + # 序号列和符号列 - 左对齐 + formatted_cells.append(cell_str.ljust(max_widths[i])) + else: + # 数值列 - 右对齐 + formatted_cells.append(cell_str.rjust(max_widths[i])) + + # 用空格连接所有单元格 + formatted_line = ' '.join(formatted_cells) + formatted_rows.append(formatted_line) + + # ========== 步骤 3: 拼接成最终文本 ========== + return '\n'.join(formatted_rows) +``` + +### 使用示例 + +```python +# 准备数据 +data_rows = [ + ["1.", "BTC", "$1.23B", "$45,000", "+5.23%"], + ["2.", "ETH", "$890.5M", "$2,500", "+3.12%"], + ["10.", "DOGE", "$123.4M", "$0.0789", "-1.45%"] +] + +# 调用对齐函数 +aligned_text = dynamic_align_format(data_rows) + +# 输出到 Telegram +text = f"""📊 排行榜 +``` +{aligned_text} +``` +💡 说明文字""" +``` + +--- + +## 格式化系统 + +### 1. 交易量智能缩写 + +```python +def format_volume(volume: float) -> str: + """智能格式化交易量""" + if volume >= 1e9: + return f"${volume/1e9:.2f}B" # 十亿 → $1.23B + elif volume >= 1e6: + return f"${volume/1e6:.2f}M" # 百万 → $890.5M + elif volume >= 1e3: + return f"${volume/1e3:.2f}K" # 千 → $123.4K + else: + return f"${volume:.2f}" # 小数 → $45.67 +``` + +**示例：** +```python +format_volume(1234567890) # → "$1.23B" +format_volume(890500000) # → "$890.5M" +format_volume(123400) # → "$123.4K" +``` + +### 2. 价格智能精度 + +```python +def format_price(price: float) -> str: + """智能格式化价格 - 根据大小自动调整小数位""" + if price >= 1000: + return f"${price:,.0f}" # 千元以上 → $45,000 + elif price >= 1: + return f"${price:.3f}" # 1-1000 → $2.500 + elif price >= 0.01: + return f"${price:.4f}" # 0.01-1 → $0.0789 + else: + return f"${price:.6f}" # <0.01 → $0.000123 +``` + +### 3. 涨跌幅格式化 + +```python +def format_change(change_percent: float) -> str: + """格式化涨跌幅 - 正数添加+号""" + if change_percent >= 0: + return f"+{change_percent:.2f}%" + else: + return f"{change_percent:.2f}%" +``` + +**示例：** +```python +format_change(5.234) # → "+5.23%" +format_change(-1.456) # → "-1.46%" +format_change(0) # → "+0.00%" +``` + +### 4. 资金流向智能显示 + +```python +def format_flow(net_flow: float) -> str: + """格式化资金净流向""" + sign = "+" if net_flow >= 0 else "" + abs_flow = abs(net_flow) + + if abs_flow >= 1e9: + return f"{sign}{net_flow/1e9:.2f}B" + elif abs_flow >= 1e6: + return f"{sign}{net_flow/1e6:.2f}M" + elif abs_flow >= 1e3: + return f"{sign}{net_flow/1e3:.2f}K" + else: + return f"{sign}{net_flow:.0f}" +``` + +--- + +## 应用示例 + +### 完整排行榜实现 + +```python +def get_volume_ranking(data, limit=10): + """获取交易量排行榜""" + + # 1. 数据处理和排序 + sorted_data = sorted(data, key=lambda x: x['volume'], reverse=True)[:limit] + + # 2. 准备数据行 + data_rows = [] + for i, item in enumerate(sorted_data, 1): + symbol = item['symbol'] + volume = item['volume'] + price = item['price'] + change = item['change_percent'] + + # 格式化各列 + volume_str = format_volume(volume) + price_str = format_price(price) + change_str = format_change(change) + + # 添加到数据行 + data_rows.append([ + f"{i}.", # 序号 + symbol, # 币种 + volume_str, # 交易量 + price_str, # 价格 + change_str # 涨跌幅 + ]) + + # 3. 动态对齐格式化 + aligned_data = dynamic_align_format(data_rows) + + # 4. 构建最终消息 + text = f"""🎪 热币排行 - 交易量榜 🎪 +⏰ 更新 {datetime.now().strftime('%Y-%m-%d %H:%M')} +📊 排序 24小时交易量(USDT) / 降序 +排名/币种/24h交易量/价格/24h涨跌 +``` +{aligned_data} +``` +💡 交易量反映市场活跃度和流动性""" + + return text +``` + +### 输出效果 + +``` +🎪 热币排行 - 交易量榜 🎪 +⏰ 更新 2025-10-29 14:30 +📊 排序 24小时交易量(USDT) / 降序 +排名/币种/24h交易量/价格/24h涨跌 + +1. BTC $1.23B $45,000 +5.23% +2. ETH $890.5M $2,500 +3.12% +3. SOL $567.8M $101 +8.45% +4. BNB $432.1M $315 +2.67% +5. XRP $345.6M $0.589 -1.23% + +💡 交易量反映市场活跃度和流动性 +``` + +--- + +## 最佳实践 + +### 1. 数据准备规范 + +```python +# ✅ 推荐：使用列表嵌套结构 +data_rows = [ + ["1.", "BTC", "$1.23B", "$45,000", "+5.23%"], + ["2.", "ETH", "$890.5M", "$2,500", "+3.12%"] +] + +# ❌ 不推荐：使用字典（需要额外转换） +data_rows = [ + {"rank": 1, "symbol": "BTC", ...}, +] +``` + +### 2. 格式化顺序 + +```python +# ✅ 推荐：先格式化，再对齐 +for i, item in enumerate(data, 1): + volume_str = format_volume(item['volume']) # 格式化 + price_str = format_price(item['price']) # 格式化 + change_str = format_change(item['change']) # 格式化 + + data_rows.append([f"{i}.", symbol, volume_str, price_str, change_str]) + +aligned_data = dynamic_align_format(data_rows) # 对齐 +``` + +### 3. Telegram 消息嵌入 + +```python +# ✅ 推荐：使用代码块包裹对齐数据 +text = f"""📊 排行榜标题 +⏰ 更新时间 {time} +``` +{aligned_data} +``` +💡 说明文字""" + +# ❌ 不推荐：直接输出（Telegram会自动换行，破坏对齐） +text = f"""📊 排行榜标题 +{aligned_data} +💡 说明文字""" +``` + +### 4. 空数据处理 + +```python +# ✅ 推荐：在函数开头检查 +def dynamic_align_format(data_rows): + if not data_rows: + return "暂无数据" + # ... 正常处理逻辑 ... +``` + +### 5. 性能优化 + +```python +# ✅ 推荐：限制数据量 +sorted_data = sorted(data, key=lambda x: x['volume'], reverse=True)[:limit] +aligned_data = dynamic_align_format(data_rows) + +# ❌ 不推荐：处理全量后截取（浪费资源） +aligned_data = dynamic_align_format(all_data_rows) +final_data = aligned_data.split('\n')[:limit] +``` + +### 6. 中文字符支持（可选） + +```python +def get_display_width(text): + """计算文本显示宽度（中文=2，英文=1）""" + width = 0 + for char in text: + if ord(char) > 127: # 非ASCII字符 + width += 2 + else: + width += 1 + return width + +# 在 dynamic_align_format 中使用 +max_widths[i] = max(max_widths[i], get_display_width(str(cell))) +``` + +--- + +## 设计优势 + +### 与硬编码方式对比 + +| 特性 | 传统硬编码 | 动态对齐 | +|------|-----------|---------| +| 列宽适配 | 手动指定 | 自动计算 | +| 维护成本 | 高（需多处修改） | 低（一次编写） | +| 对齐精度 | 易出偏差 | 字符级精确 | +| 扩展性 | 需重构 | 自动支持任意列 | +| 性能 | O(n) | O(n×m) | + +### 技术亮点 + +- **自适应宽度**: 无论数据如何变化，始终完美对齐 +- **智能对齐规则**: 符合人类阅读习惯（文本左，数字右） +- **等宽字体完美支持**: 空格填充确保对齐效果 +- **高复用性**: 一个函数适用所有排行榜场景 + +--- + +## 快速参考 + +### 函数签名 + +```python +dynamic_align_format(data_rows: list[list]) -> str +format_volume(volume: float) -> str +format_price(price: float) -> str +format_change(change_percent: float) -> str +format_flow(net_flow: float) -> str +``` + +### 时间复杂度 + +- 宽度计算: O(n × m) +- 格式化输出: O(n × m) +- 总复杂度: O(n × m) - 线性时间，高效实用 + +### 性能基准 + +- 处理 100 行 × 5 列: ~1ms +- 处理 1000 行 × 5 列: ~5-10ms +- 内存占用: 最小 + +--- + +**这份指南提供了 Telegram Bot 专业数据展示的完整解决方案！**