系列四 04|Flex Message 裝置卡片、Quick Reply 與圖文選單
本篇重點
- 認識 Flex Message 的結構:bubble、carousel、header/body/footer
- 用 Python dict 動態產生每台裝置的狀態卡片
- 依上線/過期/離線切換卡片顏色
- 加上 Quick Reply 快速按鈕與加好友歡迎訊息
- 在官方帳號後台建立圖文選單,不寫程式就能做常駐按鈕
從文字到卡片
上一篇的「狀態」查詢已經能用,但一大串文字在手機上不太好讀。LINE 提供 Flex Message,可以用 JSON 描述版面,做出像 App 一樣的卡片。我們要做的效果是:每台裝置一張卡片,頂端顏色代表狀態,左右滑動切換裝置。
| 元件 | 說明 |
|---|---|
| bubble | 一張卡片,可分成 header、hero(圖片)、body、footer 四區 |
| carousel | 多張 bubble 橫向排列,可左右滑動,最多 12 張 |
| box | 版面容器,layout 可設為 vertical(直排)或 horizontal(橫排) |
| text | 文字,可設定大小、顏色、粗細、對齊 |
好用工具:Flex Message Simulator
LINE 官方提供線上的 Flex Message Simulator(在 LINE Developers 網站可找到),可以貼上 JSON 立即預覽,也能用拖拉方式設計。設計卡片時先在模擬器調好,再搬進程式,會省下很多來回測試的時間。
實作一:flex.py(卡片產生器)
在專案資料夾新增 flex.py。它跟 device_store.py 一樣只產生 Python dict,不需要網路就能測試:
# flex.py:把裝置狀態做成 Flex Message 卡片(純 dict,可單獨測試)
from device_store import HIDDEN_KEYS, LABELS, STATE_TEXT, ago_text
STATE_COLOR = {
"online": "#2e7d32",
"stale": "#e0a100",
"offline": "#c62828",
"unknown": "#888888",
}
def _row(label, value):
return {
"type": "box", "layout": "horizontal", "contents": [
{"type": "text", "text": label, "size": "sm", "color": "#666666", "flex": 2},
{"type": "text", "text": value, "size": "sm", "color": "#222222",
"weight": "bold", "align": "end", "flex": 3},
],
}
def _value_text(key, value):
unit = LABELS.get(key, (key, ""))[1]
if isinstance(value, bool):
return "開" if value else "關"
if isinstance(value, float):
return f"{value:.1f} {unit}".strip()
return f"{value} {unit}".strip()
def build_device_bubble(store, name, now=None):
snap = store.snapshot(name) or {"data": {}, "last_seen": None}
state = store.state_of(name, now)
rows = [_row(LABELS.get(k, (k, ""))[0], _value_text(k, v))
for k, v in snap["data"].items() if k not in HIDDEN_KEYS]
if not rows:
rows = [{"type": "text", "text": "尚無數據", "size": "sm", "color": "#888888"}]
return {
"type": "bubble", "size": "kilo",
"header": {
"type": "box", "layout": "vertical",
"backgroundColor": STATE_COLOR[state], "paddingAll": "12px",
"contents": [
{"type": "text", "text": name, "color": "#ffffff",
"weight": "bold", "size": "lg"},
{"type": "text", "text": STATE_TEXT[state], "color": "#ffffff", "size": "sm"},
],
},
"body": {"type": "box", "layout": "vertical", "spacing": "sm", "contents": rows},
"footer": {
"type": "box", "layout": "vertical", "contents": [
{"type": "text", "text": "更新:" + ago_text(snap["last_seen"], now),
"size": "xs", "color": "#888888", "align": "end"},
],
},
}
def build_status_carousel(store, now=None):
# 一個 carousel 最多 12 張卡片
bubbles = [build_device_bubble(store, n, now) for n in store.names()[:12]]
return {"type": "carousel", "contents": bubbles}
重點說明:
- 欄位自動展開:卡片的每一列來自裝置 JSON 的欄位,esp32-01 有溫濕度氣壓、esp32-02 只有照度,同一個函式都能處理。
- 狀態決定顏色:沿用本站的配色慣例,綠色上線、黃色過期、紅色離線。
- 避免空內容:Flex Message 的 text 不能是空字串,所以沒有數據時放「尚無數據」,否則 LINE 會回傳 400 錯誤。
實作二:app.py 改用卡片回覆
用下面的內容取代上一篇的 app.py。和上一篇相比,新增了 Flex 與 Quick Reply 的匯入、reply()/text_msg()/flex_msg() 三個小工具函式,以及加好友時的歡迎訊息:
# app.py(第 04 篇):Flex Message 卡片+Quick Reply+加好友歡迎訊息
import json
from flask import Flask, abort, request
from linebot.v3 import WebhookHandler
from linebot.v3.exceptions import InvalidSignatureError
from linebot.v3.messaging import (ApiClient, Configuration, FlexContainer,
FlexMessage, MessageAction, MessagingApi,
QuickReply, QuickReplyItem,
ReplyMessageRequest, TextMessage)
from linebot.v3.webhooks import FollowEvent, MessageEvent, TextMessageContent
import config
from device_store import DeviceStore
from flex import build_device_bubble, build_status_carousel
from mqtt_client import start_mqtt
app = Flask(__name__)
handler = WebhookHandler(config.LINE_CHANNEL_SECRET)
line_config = Configuration(access_token=config.LINE_CHANNEL_ACCESS_TOKEN)
# 裝置狀態倉庫+MQTT 連線(程式一啟動就開始訂閱)
store = DeviceStore(config.TOPIC_ROOT, config.SUB_DATA, config.SUB_STATUS,
config.SUB_INFO, config.STALE_SECONDS)
mqtt = start_mqtt(store.handle)
@app.route("/", methods=["GET"])
def home():
return f"Bridge OK, devices: {', '.join(store.names()) or 'none'}"
@app.route("/callback", methods=["POST"])
def callback():
signature = request.headers.get("X-Line-Signature", "")
body = request.get_data(as_text=True)
try:
handler.handle(body, signature)
except InvalidSignatureError:
abort(400)
return "OK"
# 每則回覆下方都附上的快速按鈕
QUICK = QuickReply(items=[
QuickReplyItem(action=MessageAction(label=word, text=word))
for word in ("狀態", "esp32-01", "esp32-02")
])
def reply(event, *messages):
with ApiClient(line_config) as api_client:
MessagingApi(api_client).reply_message(ReplyMessageRequest(
reply_token=event.reply_token, messages=list(messages)))
def text_msg(text):
return TextMessage(text=text, quick_reply=QUICK)
def flex_msg(alt_text, container):
# alt_text 會顯示在通知與聊天列表中
return FlexMessage(alt_text=alt_text, quick_reply=QUICK,
contents=FlexContainer.from_json(json.dumps(container)))
@handler.add(FollowEvent)
def handle_follow(event):
print("[新好友] userId =", getattr(event.source, "user_id", None))
reply(event, text_msg("歡迎使用 IoT 小管家!輸入「狀態」查看所有裝置。"))
@handler.add(MessageEvent, message=TextMessageContent)
def handle_text(event):
text = event.message.text.strip()
if text == "狀態":
if not store.names():
reply(event, text_msg("目前還沒有收到任何裝置的資料。"))
else:
reply(event, flex_msg("裝置狀態", build_status_carousel(store)))
elif text.lower() in store.names():
name = text.lower()
reply(event, flex_msg(name, build_device_bubble(store, name)))
else:
reply(event, text_msg("請輸入「狀態」,或輸入裝置名稱,例如 esp32-01"))
if __name__ == "__main__":
# use_reloader=False:避免開發模式重複啟動,建立兩條 MQTT 連線
app.run(host="0.0.0.0", port=config.PORT, use_reloader=False)
| 新功能 | 說明 |
|---|---|
FlexContainer.from_json() | 把 dict 轉成 JSON 再交給 SDK,與官方範例的寫法一致 |
alt_text | Flex 卡片的替代文字,會出現在手機通知與聊天列表 |
QuickReply | 訊息下方的一排按鈕,按下等於幫使用者輸入那段文字 |
FollowEvent | 有人加好友(或解除封鎖)時觸發,可回覆歡迎訊息,也能在終端機看到對方的 userId |
重新執行 python app.py,在 LINE 輸入「狀態」,就會看到可以左右滑動的裝置卡片,下方還有「狀態」「esp32-01」「esp32-02」三個快速按鈕。
實作三:用後台建立圖文選單
Quick Reply 只在 Bot 回覆後出現。如果希望聊天室下方永遠有一排按鈕,就用圖文選單(Rich Menu)。圖文選單可以用 API 建立,但官方帳號後台的操作介面就很夠用,不必寫程式:
- 進入 LINE Official Account Manager,選擇你的官方帳號,在「主頁」找到「圖文選單」,按「建立」。
- 標題填「IoT 主選單」,設定顯示期間(可設很長的期間),選單列顯示文字填「功能選單」。
- 「版型」選擇三格或四格的配置,並上傳一張背景圖(尺寸依後台提示,可用簡報軟體畫好再匯出)。
- 每一格的「動作」選擇文字,分別填入「狀態」「esp32-01」「esp32-02」,第 05 篇之後可以再加上「開燈」「關燈」。
- 儲存後,回到手機打開聊天室,下方就會出現選單。
為什麼動作選「文字」?
選「文字」時,按下按鈕就等於使用者傳出那段文字,會走同一個 Webhook、觸發同一段程式。好處是程式完全不用改,打字或按按鈕的結果一模一樣,也都是走免費的回覆。
常見問題
Q1:輸入「狀態」沒有反應,終端機出現 400 錯誤?
Flex JSON 有格式錯誤,最常見的是某個 text 是空字串。把 build_status_carousel(store) 的結果印出來,貼到 Flex Message Simulator 檢查。
Q2:通知只顯示「裝置狀態」四個字?
那就是 alt_text。手機通知與舊版 LINE 不會顯示卡片,只會顯示替代文字。
Q3:建立了圖文選單,手機上卻看不到?
確認選單的顯示期間包含今天,並已設為使用中;也可以把聊天室關掉重開一次。
Q4:裝置超過 12 台怎麼辦?
carousel 最多 12 張卡片,程式只會顯示前 12 台。裝置更多時,可以改成分組查詢,或讓「狀態」只顯示異常的裝置。
延伸挑戰
- 在卡片的 footer 加一個按鈕(
"type": "button"搭配 message action),按下就查詢該裝置的詳細資料。 - 當溫度超過 30°C 時,讓該列文字變成紅色。
- 把
QUICK的按鈕改成依目前的裝置清單動態產生。
下一篇預告
查詢做好了,接下來是雙向的另一半:從 LINE 控制裝置。下一篇讓「開燈」「關燈」透過 MQTT 送到 ESP32,還能把文字送到 esp32-02 的 OLED 上,並且加上只有管理員能下指令的權限控管。
系列四:LINE Bot 與裝置互動
📚 系列總整理 |
🗺️ 系列四學習地圖
← 上一篇:03|橋接 MQTT:查詢裝置狀態 |
下一篇:05|從 LINE 控制裝置 →
留言
張貼留言