設置與事件

ChartSettings trait 管理圖表級別的全局設置——主題、語言、標的、時間框架、磁吸行為和表情字形。ChartView 實現了此 trait。

導入

rust

use navi_chart::{
    ChartView, ChartSettings,
    Theme, MagnetConfig, MagnetMode, ChartEvent,
};

用法

rust

use navi_chart::{ChartSettings, Theme, MagnetConfig, MagnetMode};

fn initialize_chart<C>(cv: &C, dark: bool)
where
    C: ChartSettings,
{
    cv.set_theme(if dark { Theme::dark() } else { Theme::light() });
    cv.set_magnet(MagnetConfig {
        mode: MagnetMode::Weak,
        enabled: true,
    });
    cv.set_locale("zh-HK");
}

方法參考

方法	說明
`set_theme(theme)`	為圖表應用 `Theme`。內置主題：`Theme::dark()` 和 `Theme::light()`。自定義主題請參閱主題定制。
`set_locale(locale)`	設置圖例標籤和錯誤信息的顯示語言（如 `"en"`、`"zh-HK"`）。
`locale()`	返回當前顯示語言字符串。
`set_symbol(symbol)`	切換標的，保持當前時間框架。`symbol` 接受任何實現 `Into<String>` 的類型。會重啟資料流並重新執行所有腳本。
`set_timeframe(timeframe)`	切換時間框架，保持當前標的。會重啟資料流並重新執行所有腳本。
`symbol()`	返回當前標的字符串（如 `"NASDAQ:AAPL"`）。
`timeframe()`	返回當前時間框架。
`magnet()`	返回當前磁吸（吸附 OHLC）配置。
`set_magnet(config)`	設置磁吸行為。
`set_default_emoji_glyph(glyph)`	設置表情工具在未指定字符時放置新標記所用的默認字形字符。
`default_emoji_glyph()`	返回當前默認表情字形字符。
`set_candlestick_style(style)`	切換 K 線渲染風格。詳見 K 線風格。
`candlestick_style()`	返回當前 `CandlestickStyle`。
`set_candlestick_config(config)`	替換整個 K 線配置（編程式 API，直接傳入結構體）。
`candlestick_config()`	返回當前 `CandlestickConfig` 的克隆。
`reset_candlestick_config()`	將當前活躍風格的子配置重置為預設值（其他風格的設定不受影響）。
`candlestick_properties()`	返回活躍 K 線風格（如 Bars、HeikinAshi）對應的本地化 `PropertyDescriptor` 列表，用於自動生成該風格的設置控件。
`candlestick_property(name)`	按名稱讀取單個屬性（`None` 字段返回 theme 回退色）。
`set_candlestick_property(name, value)`	寫入單個屬性並重繪，成功返回 `true`。
`set_last_price_line_visible(visible)`	顯示或隱藏最後一根 K 線收盤價處的水平價格線。預設為 `true`。樣式由 `Theme::last_price_line` 控制。
`last_price_line_visible()`	返回當前是否顯示最新價格線。
`set_y_axis_mode(mode)`	控制 Y 軸的顯示模式。`mode` 為 bitflags 整數：`0b01` = 僅右軸，`0b10` = 僅左軸，`0b11` = 兩側均顯示（預設），`0b00` = 全隱藏。影響坐標軸刻度標籤、十字光標價格標籤、價格線標籤及標注的軸標籤。
`y_axis_mode()`	返回當前 Y 軸顯示模式的 bitflags 整數。
`set_cyq_visible(visible)`	顯示或隱藏籌碼分佈（CYQ）面板。預設為 `false`。詳見下文「籌碼分佈（CYQ）」。
`cyq_visible()`	返回當前是否顯示籌碼分佈面板。
`set_cyq_width(width)`	設定籌碼分佈面板寬度（像素，預設 `270`，有最小值限制）。K 線繪圖區會相應壓縮以騰出空間。
`cyq_width()`	返回當前籌碼分佈面板寬度（像素）。
`set_ui_font_size(size)`	設定所有 UI 字體大小：坐標軸刻度標籤、十字光標圖例、價格線標籤和腳本覆蓋標籤。預設為 `12.0`。
`ui_font_size()`	返回當前 UI 字體大小。

MagnetConfig

rust

pub struct MagnetConfig {
    /// 磁吸行為模式。
    pub mode: MagnetMode,
    /// 是否啟用磁吸吸附。
    pub enabled: bool,
}

`MagnetMode`	行為
`Off`	不吸附
`Weak`	光標在 OHLC 值附近小範圍內時吸附
`Strong`	始終吸附到最近的 OHLC 值

ChartEvent

poll_event() 返回用戶交互和程序調用產生的事件。每次調用交互方法後都應清空事件隊列：

事件	說明
`EditScript(ScriptId)`	用戶點擊了腳本圖例上的編輯按鈕。
`RemoveScript(ScriptId)`	用戶點擊了腳本圖例上的移除按鈕。
`ShowError(ScriptId)`	用戶點擊了錯誤圖標——調用 `script_error(id)` 獲取錯誤信息。
`ConfigureScript(ScriptId)`	用戶點擊了配置按鈕——調用 `script_inputs(id)` 和 `graph_configs(id)` 構建配置對話框。
`DoubleClick(ChartElement)`	用戶雙擊了某條系列圖形或 K 線。
`SelectionChanged(Option<ChartElement>)`	選中元素發生變化或被清除。`ChartElement` 為 `Bar(usize)`、`Series { script_id, graph_id }` 或 `Annotation(AnnotationId)`。
`AnnotationClicked(AnnotationId)`	用戶點擊了某個標注（用戶標注或系統標注）。始終在 `SelectionChanged` 之前發出。若標注不含 `SELECTABLE` flag，則只發此事件，不更新選中狀態。
`AnnotationCreated(AnnotationId)`	新標注被添加（繪圖工具手勢、`add_annotation` 或 `add_system_annotation`）。
`AnnotationUpdated(AnnotationId)`	標注 spec 通過 `update_annotation`、`update_system_annotation` 或用戶拖動被替換。
`AnnotationDeleted(AnnotationId)`	標注被移除。

ToggleVisibility 由圖表內部處理——圖表自動切換腳本可見性並重新渲染，不推送事件。

初始化設置示例

rust

use navi_chart::{ChartSettings, ChartView, Theme, MagnetConfig, MagnetMode};
use navi_vm::TimeFrame;

fn setup<P>(cv: &ChartView<P, String>, dark_mode: bool)
where
    P: DataProvider,
{
    cv.set_theme(if dark_mode { Theme::dark() } else { Theme::light() });
    cv.set_locale("zh-HK");
    cv.set_magnet(MagnetConfig {
        mode: MagnetMode::Weak,
        enabled: true,
    });
    cv.set_default_emoji_glyph('★');
}

事件清空循環

poll_event() 屬於 ChartInteraction。每次交互方法調用後循環調用，事件在兩次清空之間會持續積累：

rust

use navi_chart::{ChartInteraction, ChartSettings, ChartEvent, ChartElement, ScriptManagement};

fn handle_interaction<C>(cv: &C, event: UiEvent)
where
    C: ChartInteraction + ChartSettings + ScriptManagement<String>,
{
    // 轉發事件
    match event {
        UiEvent::MouseDown(pos) => { cv.on_mouse_down(pos, Modifiers::empty()); }
        UiEvent::MouseUp(pos) => cv.on_mouse_up(pos),
        UiEvent::MouseMove(x, y) => cv.on_mouse_move(x, y),
        // ...
        _ => {}
    }

    // 清空所有待處理圖表事件
    while let Some(chart_event) = cv.poll_event() {
        match chart_event {
            ChartEvent::EditScript(id) => {
                if let Some(tag) = cv.tag_for(id) {
                    open_editor(&tag);
                }
            }
            ChartEvent::RemoveScript(id) => {
                cv.remove_script(id);
            }
            ChartEvent::ShowError(id) => {
                if let Some(err) = cv.script_error(id) {
                    show_error_dialog(&err.to_string());
                }
            }
            ChartEvent::ConfigureScript(id) => {
                let inputs = cv.script_inputs(id).unwrap_or_default();
                let graphs = cv.graph_configs(id).unwrap_or_default();
                open_config_dialog(id, inputs, graphs);
            }
            ChartEvent::SelectionChanged(sel) => {
                update_toolbar_for_selection(sel);
            }
            ChartEvent::AnnotationCreated(id) => persist_annotation_added(id),
            ChartEvent::AnnotationUpdated(id) => persist_annotation_updated(id),
            ChartEvent::AnnotationDeleted(id) => persist_annotation_deleted(id),
            _ => {}
        }
    }
}

讀取標的與時間框架

rust

use navi_chart::ChartSettings;

fn display_header<C>(cv: &C) -> String
where
    C: ChartSettings,
{
    format!("{} — {}", cv.symbol(), cv.timeframe())
}

更多 ChartEvent 上下文和完整的 DrawingContext 參考，請參閱概述。

籌碼分佈（CYQ）

籌碼分佈（成本分佈）面板估算每個價位上的持倉量並繪製在圖表旁。預設關閉，在日線週期下最有意義。它完全由蠟燭序列（high / low / close / volume / turnover / turnover_rate）計算，因此數據需要帶換手率——無需外部流通股本或伺服端。

rust

use navi_chart::ChartSettings;

cv.set_cyq_visible(true);   // 顯示面板
cv.set_cyq_width(270.0);    // 可選：面板寬度（像素，預設 270）

繪製在價格軸右側的固定寬度帶內（K 線繪圖區會被壓縮以騰出空間）：

橫向直方圖——每個價位一根橫條，長度正比於持倉量，以最新收盤價為界分為獲利（下方）與套牢（上方）兩色（沿用 K 線漲跌色）。
三條參考線——平均成本、壓力位、支撐位，各為一條對齊價格軸的水平價格線，右端帶彩色數值徽標。
狀態欄——獲利比例、平均成本、壓力 / 支撐位、所選區間與集中度，以及 70% / 90% 切換（在圖上點擊即可切換區間）。

整段序列只滾動計算一次並按 bar 集合快取，因此平移、縮放、移動十字游標都是 O(1)；顯示的交易日跟隨選中 / 十字游標所在 bar。當繪圖區寬度不足以容納面板時會自動隱藏。

在 Playground 中，可透過工具列上最新價格線按鈕旁邊的按鈕開關（狀態儲存在 localStorage["navi.cyq"]）。

K 線風格

圖表支持 13 種 K 線渲染風格。所有配置類型位於 navi_chart::style。

切換風格

rust

use navi_chart::{ChartSettings, CandlestickStyle};

cv.set_candlestick_style(CandlestickStyle::HeikinAshi);

編程式配置（直接構造結構體）

rust

use navi_chart::{ChartSettings, style::{CandlestickConfig, CandlestickStyle, CandleConfig, CandleColors}};
use navi_chart::Color;

let config = CandlestickConfig {
    style: CandlestickStyle::Candlestick,
    candle: CandleConfig {
        color_based_on_prev_close: true,
        colors: CandleColors {
            up_body: Some(Color::from_rgb(0, 180, 90)),
            down_body: Some(Color::from_rgb(200, 40, 40)),
            ..Default::default()
        },
    },
    ..Default::default()
};

cv.set_candlestick_config(config);

UI property API（自動生成設置控件）

rust

// 獲取當前風格的屬性列表（含本地化顯示名）
let descriptors = cv.candlestick_properties();

// 讀取屬性（None 字段返回 theme 實際顏色，如 theme.bull）
let result = cv.candlestick_property("upBody");

// 寫入屬性
cv.set_candlestick_property("upBody", PropertyValue::Enableable(/* ... */));

風格列表

變體	說明
`Candlestick`	實心蠟燭圖（默認）
`Bars`	OHLC 柱：高低豎線加開收刻度
`HollowCandle`	漲空心、跌實心蠟燭
`VolumeCandle`	蠟燭寬度隨成交量縮放
`Line`	收盤價折線圖
`LineWithMarkers`	折線 + 每根 bar 圓點標記
`StepLine`	階梯折線
`Area`	折線 + 下方漸變面積填充
`HlcArea`	高低收盤三條線 + 色帶填充
`Baseline`	基準線上下分色填充
`Columns`	從底部到收盤價的豎柱
`HighLow`	僅高低豎線
`HeikinAshi`	平均 K 線（Heikin-Ashi）

詳細類型參考請見 navi_chart::style。

脚本管理

標注

附錄

設置與事件

導入

用法

方法參考

MagnetConfig

ChartEvent

初始化設置示例

事件清空循環

讀取標的與時間框架

籌碼分佈（CYQ）

K 線風格

切換風格

編程式配置（直接構造結構體）

UI property API（自動生成設置控件）

風格列表

設置與事件 ​

導入 ​

用法 ​

方法參考 ​

MagnetConfig ​

ChartEvent ​

初始化設置示例 ​

事件清空循環 ​

讀取標的與時間框架 ​

籌碼分佈（CYQ） ​

K 線風格 ​

切換風格 ​

編程式配置（直接構造結構體） ​

UI property API（自動生成設置控件） ​

風格列表 ​

設置與事件

導入

用法

方法參考

MagnetConfig

ChartEvent

初始化設置示例

事件清空循環

讀取標的與時間框架

籌碼分佈（CYQ）

K 線風格

切換風格

編程式配置（直接構造結構體）

UI property API（自動生成設置控件）

風格列表