跳轉至

建立 2026-10-13 更新 2026-10-13

共通參數全攻略

Plotly Express 的所有繪圖函式共用同一套參數名稱：x、y 決定位置，color、size、symbol 決定外觀，facet_row、facet_col 把圖拆成小圖，hover_name、hover_data 控制懸停資訊，labels、title、template 控制文字與風格。學會這一頁，就等於學會了大部分的 Plotly Express。

本頁範例都使用內建的餐廳小費資料集 tips：

import plotly.express as px

df = px.data.tips()
df.head()
#    total_bill   tip     sex smoker  day    time  size
# 0       16.99  1.01  Female     No  Sun  Dinner     2
# 1       10.34  1.66    Male     No  Sun  Dinner     3

參數速查表

類別 參數 作用
資料 data_frame 第一個參數，傳入 DataFrame
位置 x、y、z（3D）、r／theta（極座標）、lat／lon（地圖） 欄位對應到座標
外觀 color、size、symbol、line_dash、pattern_shape、text、opacity 欄位對應到顏色、大小、標記形狀、線型、填充花紋、文字
分面 facet_row、facet_col、facet_col_wrap、facet_row_spacing、facet_col_spacing 依類別拆成小圖
動畫 animation_frame、animation_group 依欄位值逐格播放
懸停 hover_name、hover_data、custom_data 滑鼠移上去時顯示的資訊
誤差 error_x、error_y、error_x_minus、error_y_minus 誤差線
順序 category_orders 指定類別的排列順序
顏色 color_discrete_sequence、color_discrete_map、color_continuous_scale、range_color、color_continuous_midpoint 配色
座標軸 log_x、log_y、range_x、range_y、orientation 刻度與範圍
邊際圖 marginal_x、marginal_y（scatter、histogram、density_*） 在主圖邊緣加小分布圖
文字 title、subtitle、labels 標題、副標題、欄位顯示名稱
版面 template、width、height 風格模板與尺寸

並非每個函式都有所有參數，例如 px.pie 沒有 x、y，而是 names、values。實際可用參數請以 help(px.函式) 為準。

位置：x、y

最基本的用法是傳入欄位名稱字串：

px.scatter(df, x="total_bill", y="tip")

也可以傳入 pandas Series 或 list（長度要與 DataFrame 相同），或者傳入欄位名稱的 list 來畫寬格式資料（見 長格式與寬格式資料）。

外觀對應：color、size、symbol

px.scatter(df, x="total_bill", y="tip",
           color="time",      # 類別欄位 → 每組一種顏色（離散）
           size="size",       # 數值欄位 → 點的大小
           symbol="smoker")   # 類別欄位 → 點的形狀

color 的行為取決於欄位型別：

  • 類別欄位（字串、布林、category）：每個類別一種顏色，產生多條 trace，圖例可點擊篩選。
  • 數值欄位：使用連續色階，右側出現色條（colorbar）。

想讓數值欄位被當成類別處理（例如 size 只有 1～6），先轉成字串：df["size"].astype(str)。

分面：facet_row、facet_col

facet_col 依欄位值把圖拆成左右排列的小圖，facet_row 拆成上下排列。類別很多時用 facet_col_wrap 自動換行：

px.histogram(df, x="total_bill", facet_col="day", facet_col_wrap=2)

詳細說明與範例見 分面與動畫。

懸停資訊：hover_name、hover_data

px.scatter(df, x="total_bill", y="tip",
           hover_name="day",                 # 懸停框標題（粗體）
           hover_data={"size": True,          # 額外顯示 size
                       "sex": True,
                       "total_bill": ":.1f",  # 改格式：小數一位
                       "tip": False})         # 不顯示 tip

hover_data 可以是欄位名稱的 list，或是 dict：值為 True／False 表示顯示／隱藏，值為字串則是 d3 格式 的數字格式（例如 ":.2f"、":,"、":.1%"）。想完全自訂懸停框，可以用 fig.update_traces(hovertemplate=...)，見 樣式與客製化。

顯示名稱：labels、title

labels 把欄位名稱換成要顯示的文字，同時套用到座標軸、圖例與懸停框：

px.scatter(df, x="total_bill", y="tip", color="sex",
           labels={"total_bill": "帳單金額（美元）", "tip": "小費（美元）", "sex": "性別"},
           title="小費與帳單金額", subtitle="資料來源：px.data.tips()")

類別順序：category_orders

類別預設依資料出現順序排列。星期、月份、等級這類有自然順序的資料，用 category_orders 指定：

px.bar(df, x="day", y="total_bill",
       category_orders={"day": ["Thur", "Fri", "Sat", "Sun"]})

配色參數

參數 用途 範例
color_discrete_sequence 類別顏色依序使用的色盤 px.colors.qualitative.Set2
color_discrete_map 指定每個類別的顏色 {"Male": "steelblue", "Female": "tomato"}
color_continuous_scale 連續色階 "Viridis"、px.colors.sequential.Blues
range_color 連續色階的數值範圍 [0, 100]
color_continuous_midpoint 發散色階的中點 0 
px.scatter(df, x="total_bill", y="tip", color="sex",
           color_discrete_map={"Male": "steelblue", "Female": "tomato"})

更多配色說明見 樣式與客製化。

座標軸：log_x、range_x、orientation

px.scatter(px.data.gapminder(), x="gdpPercap", y="lifeExp",
           log_x=True,            # X 軸改成對數刻度
           range_y=[20, 90])      # 固定 Y 軸範圍

長條圖、箱形圖等可以用 orientation="h" 改成水平方向；通常只要把 x、y 對調，Plotly Express 也會自動判斷方向。

尺寸與模板：width、height、template

px.scatter(df, x="total_bill", y="tip", template="plotly_white", height=400)

常用模板：plotly（預設）、plotly_white、plotly_dark、simple_white、ggplot2、seaborn、presentation、none。全域預設值可用 px.defaults 設定：

px.defaults.template = "plotly_white"
px.defaults.width = 700
px.defaults.height = 450
px.defaults.color_discrete_sequence = px.colors.qualitative.Safe

設定後，之後所有 px 函式都會套用這些預設值，適合放在 Notebook 第一格。

常見錯誤

錯誤訊息或狀況 原因與解法
ValueError: Value of 'x' is not the name of a column 欄位名稱打錯（大小寫、空白），先 print(df.columns) 確認
數值被畫成類別、長條很奇怪 欄位型別是字串，用 pd.to_numeric 轉換
想要離散顏色卻出現色條 color 欄位是數值，用 .astype(str) 轉成類別
星期、月份順序亂掉 用 category_orders 指定順序
長條圖有很多細橫線 同一個 x 有多筆資料，長條是逐筆堆疊；先 groupby().sum() 或改用 px.histogram(..., histfunc="sum")

推薦影音

How to use Plotly Express to create professional graphs in minutes!（Analytics with Adam）

簡述：5 分鐘示範 Plotly Express 的基本模式：一個函式加上 color、size、hover_data、facet 等參數，快速做出專業的互動圖。適合讀完本頁後當成複習。

相關頁面