Các Anti-Pattern Visual
Sai vs đúng khi thiết kế visual — chọn sai họ visual, trộn danh tính fill tĩnh và bridge, và tọa độ attrs cũ.
Sai vs Đúng Cho Các Lỗi Thiết Kế Thường Gặp#
Chọn sai họ visual#
# Wrong: create object machinery for a simple row-aligned line.
def build_visuals(frame, params=None, ctx=None):
return ctx.line.new(key="ema_line", x1=0, y1=100, x2=10, y2=101)
# Right: if the frame already has one value per row, stay with plot(...).
plot("ema_fast", key="ema_fast", title="EMA Fast", color="#00c853", width=2)Trộn danh tính fill tĩnh và bridge#
# Wrong: trying to fill between static keys with the bridge helper.
# ctx.atk.fill_between(line1="bb_upper", line2="bb_lower", ...)
# Right: bridge fills between bridge line keys.
ctx.atk.plot_line(key="fast_line", source="fast", color="#00c853")
ctx.atk.plot_line(key="slow_line", source="slow", color="#f23645")
ctx.atk.fill_between(key="trend_fill", line1="fast_line", line2="slow_line", fill_alpha=24)Tính toán bên trong build_visuals#
# Wrong: TA computation inside the render stage.
def build_visuals(frame, params=None, ctx=None):
ema = ta.ema(frame["close"], 20) # DO NOT do this here
last_ema = float(ema.iloc[-1])
return ctx.label.new(key="ema_label", x=int(frame.iloc[-1]["index"]), y=last_ema, text="EMA")
# Right: compute in build_indicator_frame, read in build_visuals.
def build_indicator_frame(df, params=None):
frame = df.copy().reset_index(drop=True)
frame["ema_fast"] = ta.ema(frame["close"], 20)
return frame
def build_visuals(frame, params=None, ctx=None):
last = frame.iloc[-1]
return ctx.label.new(
key="ema_label",
x=int(last["index"]),
y=float(last["ema_fast"]),
text="EMA",
)attrs Dành Cho Cấu Hình Tĩnh, Không Phải Tọa Độ Cố Định#
Quy tắc an toàn rất đơn giản: màu sắc, tiêu đề, nhãn, và các cấu hình ổn định khác có thể nằm trong frame.attrs.
Tọa độ, điểm neo dẫn xuất từ tail, và hình học slice hiện tại nên được lấy từ frame truyền
vào build_visuals. Nếu không, quá trình render lịch sử hoặc render theo slice có thể tái sử dụng payload cũ.
Không bao giờ lưu tọa độ chỉ số bar hoặc mức giá trong frame.attrs. Các giá trị đó thay đổi với mỗi lần cập nhật.
Chỉ lưu cấu hình hiển thị ổn định — màu sắc, kích thước font, chuỗi tiêu đề, token style.