diff --git a/README.md b/README.md index e0b6774..e68ea15 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,6 @@ -->

- 构建状态 许可证 主要语言 代码量 diff --git a/i18n/en/skills/telegram-dev/references/dynamic-view-alignment-implementation-document.md b/i18n/en/skills/telegram-dev/references/dynamic-view-alignment-implementation-document.md new file mode 100644 index 0000000..a6ffd4a --- /dev/null +++ b/i18n/en/skills/telegram-dev/references/dynamic-view-alignment-implementation-document.md @@ -0,0 +1,413 @@ +# 📊 Dynamic View Alignment - A Guide to Data Display in Telegram + +> A professional solution for monospaced font data alignment and formatting + +--- + +## 📑 Table of Contents + +- [Core Principles](#core-principles) +- [Implementation Code](#implementation-code) +- [Formatting System](#formatting-system) +- [Application Examples](#application-examples) +- [Best Practices](#best-practices) + +--- + +## Core Principles + +### Problem Scenario + +When displaying leaderboards or data tables in a Telegram Bot, perfect alignment is required in a monospaced font environment (code block): + +**❌ Unaligned:** +``` +1. BTC $1.23B $45000 +5.23% +10. DOGE $123.4M $0.0789 -1.45% +``` + +**✅ Dynamically Aligned:** +``` +1. BTC $1.23B $45,000 +5.23% +10. DOGE $123.4M $0.0789 -1.45% +``` + +### Three-Step Alignment Algorithm + +``` +Step 1: Scan the data to calculate the maximum width of each column +Step 2: Apply alignment rules based on the column type (text left-aligned, numbers right-aligned) +Step 3: Concatenate into the final text +``` + +### Alignment Rules + +| Column Index | Data Type | Alignment | Example | +|---|---|---|---| +| Column 0 | Sequence No. | Left-aligned | `1. `, `10. ` | +| Column 1 | Symbol | Left-aligned | `BTC `, `DOGE ` | +| Column 2+ | Numeric Value | Right-aligned | ` $1.23B`, `$123.4M` | + +--- + +## Implementation Code + +### Core Function + +```python +def dynamic_align_format(data_rows): + """ + Dynamically aligns and formats the view. + + Args: + data_rows: A 2D list [["1.", "BTC", "$1.23B", ...], ...] + + Returns: + An aligned text string. + """ + if not data_rows: + return "No data available" + + # ========== Step 1: Calculate the maximum width of each column ========== + max_widths = [] + for row in data_rows: + for i, cell in enumerate(row): + # Dynamically expand the list + if i >= len(max_widths): + max_widths.append(0) + # Update the maximum width + max_widths[i] = max(max_widths[i], len(str(cell))) + + # ========== Step 2: Format each row ========== + 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: + # Sequence number and symbol columns - left-aligned + formatted_cells.append(cell_str.ljust(max_widths[i])) + else: + # Numeric columns - right-aligned + formatted_cells.append(cell_str.rjust(max_widths[i])) + + # Join all cells with a space + formatted_line = ' '.join(formatted_cells) + formatted_rows.append(formatted_line) + + # ========== Step 3: Concatenate into the final text ========== + return '\n'.join(formatted_rows) +``` + +### Usage Example + +```python +# Prepare the data +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%"] +] + +# Call the alignment function +aligned_text = dynamic_align_format(data_rows) + +# Output to Telegram +text = f""" +📊 Leaderboard +``` +{aligned_text} +``` +💡 Explanatory text""" +``` + +--- + +## Formatting System + +### 1. Smart Abbreviation for Trading Volume + +```python +def format_volume(volume: float) -> str: + """Intelligently formats trading volume.""" + if volume >= 1e9: + return f"${volume/1e9:.2f}B" # Billions → $1.23B + elif volume >= 1e6: + return f"${volume/1e6:.2f}M" # Millions → $890.5M + elif volume >= 1e3: + return f"${volume/1e3:.2f}K" # Thousands → $123.4K + else: + return f"${volume:.2f}" # Decimals → $45.67 +``` + +**Example:** +```python +format_volume(1234567890) # → "$1.23B" +format_volume(890500000) # → "$890.5M" +format_volume(123400) # → "$123.4K" +``` + +### 2. Smart Precision for Price + +```python +def format_price(price: float) -> str: + """Intelligently formats price - automatically adjusts decimal places based on value.""" + if price >= 1000: + return f"${price:,.0f}" # Above 1000 → $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. Formatting for Price Change Percentage + +```python +def format_change(change_percent: float) -> str: + """Formats price change percentage - adds a '+' sign for positive numbers.""" + if change_percent >= 0: + return f"+{change_percent:.2f}%" + else: + return f"{change_percent:.2f}%" +``` + +**Example:** +```python +format_change(5.234) # → "+5.23%" +format_change(-1.456) # → "-1.46%" +format_change(0) # → "+0.00%" +``` + +### 4. Smart Display for Fund Flow + +```python +def format_flow(net_flow: float) -> str: + """Formats net fund flow.""" + 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}" +``` + +--- + +## Application Examples + +### Complete Leaderboard Implementation + +```python +def get_volume_ranking(data, limit=10): + """Gets the trading volume leaderboard.""" + + # 1. Data processing and sorting + sorted_data = sorted(data, key=lambda x: x['volume'], reverse=True)[:limit] + + # 2. Prepare data rows + data_rows = [] + for i, item in enumerate(sorted_data, 1): + symbol = item['symbol'] + volume = item['volume'] + price = item['price'] + change = item['change_percent'] + + # Format each column + volume_str = format_volume(volume) + price_str = format_price(price) + change_str = format_change(change) + + # Add to data rows + data_rows.append([ + f"{i}.", # Sequence No. + symbol, # Coin + volume_str, # Volume + price_str, # Price + change_str # Change % + ]) + + # 3. Dynamic alignment and formatting + aligned_data = dynamic_align_format(data_rows) + + # 4. Build the final message + text = f""" +🎪 Hot Coins - Volume Ranking 🎪 +⏰ Updated {datetime.now().strftime('%Y-%m-%d %H:%M')} +📊 Sorted by 24h Volume (USDT) / Descending +Rank/Coin/24h Vol/Price/24h Change +``` +{aligned_data} +``` +💡 Volume reflects market activity and liquidity.""" + + return text +``` + +### Output Effect + +``` +🎪 Hot Coins - Volume Ranking 🎪 +⏰ Updated 2025-10-29 14:30 +📊 Sorted by 24h Volume (USDT) / Descending +Rank/Coin/24h Vol/Price/24h Change + +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% + +💡 Volume reflects market activity and liquidity. +``` + +--- + +## Best Practices + +### 1. Data Preparation Standards + +```python +# ✅ Recommended: Use a nested list structure +data_rows = [ + ["1.", "BTC", "$1.23B", "$45,000", "+5.23%"], + ["2.", "ETH", "$890.5M", "$2,500", "+3.12%"] +] + +# ❌ Not recommended: Use a dictionary (requires extra conversion) +data_rows = [ + {"rank": 1, "symbol": "BTC", ...}, +] +``` + +### 2. Formatting Order + +```python +# ✅ Recommended: Format first, then align +for i, item in enumerate(data, 1): + volume_str = format_volume(item['volume']) # Format + price_str = format_price(item['price']) # Format + change_str = format_change(item['change']) # Format + + data_rows.append([f"{i}.", symbol, volume_str, price_str, change_str]) + +aligned_data = dynamic_align_format(data_rows) # Align +``` + +### 3. Embedding in Telegram Messages + +```python +# ✅ Recommended: Wrap aligned data in a code block +text = f""" +📊 Leaderboard Title +⏰ Update Time {time} +``` +{aligned_data} +``` +💡 Explanatory text""" + +# ❌ Not recommended: Direct output (Telegram's auto-wrapping will break alignment) +text = f""" +📊 Leaderboard Title +{aligned_data} +💡 Explanatory text""" +``` + +### 4. Handling Empty Data + +```python +# ✅ Recommended: Check at the beginning of the function +def dynamic_align_format(data_rows): + if not data_rows: + return "No data available" + # ... Normal processing logic ... +``` + +### 5. Performance Optimization + +```python +# ✅ Recommended: Limit the amount of data +sorted_data = sorted(data, key=lambda x: x['volume'], reverse=True)[:limit] +aligned_data = dynamic_align_format(data_rows) + +# ❌ Not recommended: Process all data then truncate (wastes resources) +aligned_data = dynamic_align_format(all_data_rows) +final_data = aligned_data.split('\n')[:limit] +``` + +### 6. Chinese Character Support (Optional) + +```python +def get_display_width(text): + """Calculates the display width of text (Chinese=2, English=1).""" + width = 0 + for char in text: + if ord(char) > 127: # Non-ASCII characters + width += 2 + else: + width += 1 + return width + +# Use in dynamic_align_format +max_widths[i] = max(max_widths[i], get_display_width(str(cell))) +``` + +--- + +## Design Advantages + +### Comparison with Hardcoding + +| Feature | Traditional Hardcoding | Dynamic Alignment | +|---|---|---| +| Column Width Adaptation | Manual specification | Automatic calculation | +| Maintenance Cost | High (requires multiple modifications) | Low (write once) | +| Alignment Precision | Prone to deviation | Character-level precision | +| Scalability | Requires refactoring | Supports any number of columns automatically | +| Performance | O(n) | O(n×m) | + +### Technical Highlights + +- **Adaptive Width**: Perfect alignment regardless of data changes +- **Smart Alignment Rules**: Conforms to human reading habits (text left, numbers right) +- **Perfect Monospaced Font Support**: Space padding ensures alignment +- **High Reusability**: One function for all leaderboard scenarios + +--- + +## Quick Reference + +### Function Signatures + +```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 +``` + +### Time Complexity + +- Width Calculation: O(n × m) +- Formatted Output: O(n × m) +- Total Complexity: O(n × m) - Linear time, highly efficient + +### Performance Benchmarks + +- Processing 100 rows × 5 columns: ~1ms +- Processing 1000 rows × 5 columns: ~5-10ms +- Memory Usage: Minimal + +--- + +**This guide provides a complete solution for professional data display in Telegram Bots!** + +``` \ No newline at end of file