Block.con 組積木
所屬章節：積木 Block 以 2026-09-21 實際執行結果為準
Overview
把「積木 + 參數」組成 screener 吃的 dict。
| 參數 | 型態 | 說明 |
|---|---|---|
name |
str / dict / 省略 |
積木名稱（get_table 的 key）、積木 id，或一份帶 'id' 的條件 dict |
**params |
要覆寫的參數。沒指定的走該積木類別的預設值。id 是保留字，用來指定積木 |
回傳 dict，固定含 id，其餘是參數：
{'id': 'o1', 'operator': '>', 'ohlc_field': 'adj_High', 'percent': 3, 'close_field': 'adj_Close', 'period': 1}
指定的參數會對照 get_table 的合法值驗證，不合法就拋 ValueError。
三種指定積木的寫法
以下輸出完全相同，挑順手的用：
api.Block.con_tw('dataA<>dataB+C',
left='日_K.Volume', operator='>', const=3000)
api.Block.con_tw(id='a1', left='日_K.Volume', operator='>', const=3000)
api.Block.con_tw({'id': 'a1', 'left': '日_K.Volume',
'operator': '>', 'const': 3000})
dict 形式讓「先手寫條件、再補完驗證」變成同一條路徑：自己組的 dict 丟進來， 回傳的就是補齊預設值與規格固定值、且驗證過的版本。傳 dict 時不可再混用 keyword。
id 之所以能當保留字，是因為沒有任何積木的參數叫這個名字（台股 416、
美股 260 個積木都查過）。
Manual Sample Input/Output
Example 1：全用預設值
input
output
{'id': 'o1', 'operator': '>', 'ohlc_field': 'adj_Low', 'percent': 3, 'close_field': 'adj_Close', 'period': 1}
尾端的 close_field / period 是規格固定值，見 Example 7。
Example 2：指定參數
input
output
{'id': 'o1', 'operator': '>', 'ohlc_field': 'adj_High', 'percent': 3, 'close_field': 'adj_Close', 'period': 1}
Example 3：可以用中文標籤
Excel 規格為部分選項附了中文標籤，con 會自動轉回內部值：
input
output
{'id': 'o1', 'operator': '>', 'ohlc_field': 'adj_High', 'percent': 3, 'close_field': 'adj_Close', 'period': 1}
'最高價' 被轉成 'adj_High'。哪些選項有中文標籤，看
台股積木完整參考 的「合法值」欄（有標籤的會顯示成
adj_High（最高價））。
字串型數字也接受：percent='3' 等同 percent=3。
Example 4：用 id 指定積木
三種寫法等價：
input
api.Block.con_tw('o1') # id 當位置引數
api.Block.con_tw(id='o1') # id 當 keyword
api.Block.con_tw({'id': 'o1'}) # dict
output
{'id': 'o1', 'operator': '>', 'ohlc_field': 'adj_Low', 'percent': 3, 'close_field': 'adj_Close', 'period': 1}
但一個 id 可能對到多個名稱，那時用 id 會拋錯：
台股 4 組、美股 2 組 id 重複（m9、m21、s1、r4、r23），
這些積木只能用名稱。其餘一律可用 id。
同時給名稱和 id= 且兩者不同，會擋下來：
Example 5：negate 參數自動取負
有些積木語意上就是負值（跌幅、距低點），Excel 把該參數標記為 negate。 不論你傳正或負，輸出一律是負值：
input
output
input
output
台股共 9 個積木有 negate 參數：o10、o12、o14、o18、o20、o23、
o28、o36、mfunc1。
Example 6：三種錯誤訊息
參數名打錯：
input
output
值不合法：
input
output
積木名打錯（會提示相近的名稱）：
input
output
ValueError: 找不到積木 '今日收盤價'（market=tw），是不是想找：['今日收盤價<>開高低P%', '今日收盤價距今日最低價 <>-P%', '今日收盤價(開低高)與近D日內最高價<P%', '今日收盤價(開高低)與近D日內最低價<-P%', '今日收盤價(開高低)<>昨天收盤價P%']
Example 7：規格固定的參數會自動帶進輸出
Excel 的『python參數』欄會把部分 kwarg 釘死成字面常數（例如 'value': -0.4）。
這些值不是選項、使用者無從挑選，但規格已經指定，con() 會直接帶進輸出：
input
output
{'id': 'm9', 'period': [5, 10, 20, 60, 120, 240], 'operator': ['<', '>']}
{'id': 'm9', 'period': 20, 'operator': '>', 'value': 0.4}
固定值排在可選參數之後。因為是規格釘死的，不能指定：
input
output
台股 28 個、美股 10 個積木有這種固定值。少了它們，condition class 會退回自己
__init__ 的預設值，而那未必等於規格值——例如「開盤漲幅>P%」的 operator
規格是 '>'、class 預設卻是 '<'，語意相反。
Example 8：輸出可以直接餵回去（冪等）
con() 的輸出丟回 con() 得到同一份結果，所以可以拿既有條件回來改參數：
input
output
改其中一個參數：
規格固定值出現在輸入 dict 裡不會被拒絕（值相同即放行），只有想改成別的值 才會擋。
注意：
con()輸出的預設值會正規化成get_table的詞彙。Excel 規格與 condition class 對同一個值常用不同寫法（規格'以上'／class'up'、 規格'周'／class'week'），con()一律吐規格那一側，所以輸出的每個值 都找得到對應的合法值。兩者送進 class 後等價，選股結果不變。 其他已知落差見 已知落差與注意事項。