LINE Bot Flex Message 筆記樣式設計指南

概述

本 skill 記錄 LINE Bot Flex Message 圖文筆記的設計規範與最佳實踐，以「元素週期表筆記」專案為範例。適用於教育類、知識卡片類的 LINE Bot 開發。

LINE Bot Flex Message 限制

aspectMode 血淚教訓

LINE API 回傳 HTTP 400 錯誤：

{"message":"invalid property","property":"/contents/1/hero/aspectMode"}

原因：使用了 "aspectMode": "contain"，但 LINE hero 圖片只支援：

• "cover" - 填滿區域，可能裁切
• "fit" - 完整顯示，可能留白

修正：將所有 "contain" 改為 "fit"

不支援的屬性（重要！）

LINE Flex Message 不支援以下屬性，使用會導致 HTTP 400 錯誤：

Bubble Size 限制

注意：內容超過限制時會被截斷，按鈕可能無法顯示！

卡片結構設計

標準 Flex Message 卡片結構

┌─────────────────────────┐
│       Hero 區域          │  ← 圖片或漸層背景
│    （圖片/符號/標題）     │
├─────────────────────────┤
│       Content 區域       │
│  ┌───────────────────┐  │
│  │ 標題 + 副標題      │  │
│  └───────────────────┘  │
│  ┌───────────────────┐  │
│  │ 資訊表格/內文      │  │
│  └───────────────────┘  │
│  ┌───────────────────┐  │
│  │ 化學式/重點框      │  │
│  └───────────────────┘  │
│  ┌───────────────────┐  │
│  │ 標籤/按鈕          │  │
│  └───────────────────┘  │
└─────────────────────────┘

Hero 區域設計

配色建議（Material Design）：

色塊模擬技巧

用 Box + backgroundColor 模擬色塊：

[
    'type' => 'box',
    'layout' => 'vertical',
    'contents' => [],
    'width' => '28px',
    'height' => '28px',
    'backgroundColor' => '#FF5733',
    'cornerRadius' => '6px',
]

導航按鈕設計

Flex Message JSON 實作：

{
  "type": "separator",
  "margin": "lg"
},
{
  "type": "box",
  "layout": "horizontal",
  "contents": [
    {
      "type": "button",
      "action": {
        "type": "message",
        "label": "📋 元素目錄",
        "text": "元素目錄"
      },
      "style": "primary",
      "height": "sm",
      "flex": 1
    },
    {
      "type": "button",
      "action": {
        "type": "message",
        "label": "下一個 ➡️",
        "text": "元素 2"
      },
      "style": "secondary",
      "height": "sm",
      "flex": 1,
      "margin": "sm"
    }
  ],
  "margin": "lg"
}

兩欄按鈕設計（重要教育原則）

當元素數量較多時，使用兩欄按鈕可節省空間。

閱讀順序原則：必須是「由上到下」（先左欄再右欄），不是「由左至右」！

正確（由上到下）：        錯誤（由左至右）：
21 Sc | 39 Y             21 Sc | 22 Ti
22 Ti | 40 Zr            23 V  | 24 Cr
23 V  | 41 Nb            25 Mn | 26 Fe
...                      ...
閱讀：21→22→23...→39→40   閱讀：21→22→23→24...

奇數元素處理：最後一個元素旁邊加 filler 佔位。

{
  "type": "box",
  "layout": "horizontal",
  "contents": [
    {
      "type": "button",
      "action": { "label": "71 Lu 鎦", "text": "元素 71" },
      "style": "secondary",
      "flex": 1
    },
    {
      "type": "filler",
      "flex": 1
    }
  ]
}

圖片生成規範（matplotlib）

基本設定

# -*- coding: utf-8 -*-
import matplotlib.pyplot as plt
import matplotlib.patches as patches
import os

# 中文字體（必須）
plt.rcParams['font.sans-serif'] = ['Microsoft JhengHei', 'SimHei', 'Arial Unicode MS']
plt.rcParams['axes.unicode_minus'] = False

圖片尺寸標準

字體大小標準（LINE Bot 手機可讀）

FONT_TITLE = 30   # 主標題、單字元元素符號
FONT_LARGE = 22   # 雙字元元素符號
FONT_MEDIUM = 18  # 一般文字
FONT_SMALL = 14   # 次要資訊（最小值）

重要：LINE Bot 圖片在手機上無法放大，字體必須足夠大！

儲存函數

def save_fig(fig, filename):
    """儲存圖片"""
    filepath = os.path.join(OUTPUT_DIR, filename)
    fig.savefig(filepath, dpi=150, bbox_inches='tight',
                facecolor='white', edgecolor='none', pad_inches=0.02)
    plt.close(fig)
    print(f"已儲存: {filename}")

常見錯誤與修正

1. Text 欄位不能為空字串

症狀：LINE Bot 無反應，API 回傳 HTTP 400

// ❌ 錯誤：空字串會導致 HTTP 400
{"type": "text", "text": ""}

// ✅ 正確：使用佔位符
{"type": "text", "text": "－"}

2. 長文字必須加 wrap: true

// ❌ 錯誤：長文字會被截斷
{"type": "text", "text": "很長的化學式..."}

// ✅ 正確：允許折行
{"type": "text", "text": "很長的化學式...", "wrap": true}

3. Button label 太長

改用 Box + Text（支援折行）：

// ✅ 改用 box + text
['type' => 'box', 'contents' => [
    ['type' => 'text', 'text' => '很長的文字...', 'wrap' => true]
], 'action' => [...]]

4. LINE 圖片快取問題

更新圖片後 LINE 仍顯示舊版時，在 URL 加上版本參數：

"image_url": "https://lt4.mynet.com.tw/linebot/images/H.png?v=2"

5. matplotlib 特殊字符顯示為方框

某些 Unicode 字符在微軟正黑體中不支援：

6. 診斷 LINE API 錯誤

當 LINE Bot 按鈕無反應時：

1. 檢查 debug.log：

tail -50 /path/to/linebot/debug.log

2. 解讀 property 路徑：

• /contents/0/body/contents/5/contents/1/text
• 代表 → carousel 第 1 張卡片 → body → 第 6 個元素 → 第 2 個子元素 → text

3. 常見 HTTP 狀態碼：

檔案命名規範

圖片檔案

# 週期表（每個元素一張，高亮該元素）
periodic_table_{symbol}.png
例：periodic_table_H.png, periodic_table_He.png

# 價電子圖
electron_{symbol}.png
例：electron_H.png, electron_He.png

# 內容圖片
{element}_{topic}.png
例：H_combustion.png, H_fuel_cell.png

JSON 資料檔

# 元素筆記資料
elements/{atomic_number}_{symbol}.json
例：elements/001_H.json, elements/002_He.json

# 目錄資料
menu/groups.json

導航流程設計

主選單
    │
    ▼
元素目錄（按族分類 Carousel）
    │
    ├── 1A族 → [H] [Li] [Na] [K] ...
    ├── 2A族 → [Be] [Mg] [Ca] ...
    └── ...
          │
          ▼
    元素筆記（4張卡片 Carousel）
          │
          ├── 卡片1: 基本資訊
          ├── 卡片2: 特性1
          ├── 卡片3: 特性2
          └── 卡片4: 特性3 + 導航按鈕
                      │
                      ├── [⬅️ 上一個] [➡️ 下一個]
                      ├── [📋 元素目錄]
                      └── [🏠 主選單]

相關 Skills

• linebot-architecture：LINE Bot 架構規範（憲法）
• quiz-builder：題庫系統專用指南
• linebot-setup：LINE Bot Messaging API 設定與除錯