視口控制

ViewportControl trait 控制任意圖表視圖的視口——可見 K 線範圍、滾動位置和分欄佈局。ChartView 實現了此 trait。

導入

use navi_chart::{ChartView, ViewportControl};

用法

use navi_chart::ViewportControl;

/// 滾動到最新 K 線（最右側位置）。
fn scroll_to_latest<C>(cv: &C)
where
    C: ViewportControl,
{
    let last = cv.total_bars().saturating_sub(1);
    cv.scroll_to_bar(last);
}

/// 高亮指定 K 線（例如，點擊策略測試器中的某行時）。
fn highlight_bar<C>(cv: &C, bar_index: Option<usize>)
where
    C: ViewportControl,
{
    cv.set_highlighted_bar(bar_index);
}

方法參考

方法	說明
on_resize(size)	通知圖表畫布尺寸已變更。size 以邏輯/CSS 像素為單位，包含 width 和 height。宿主窗口或容器尺寸變化時調用。
pane_ratios()	返回當前所有分欄的高度比例。第一個元素為主欄，後續元素依次為各子欄。各值之和約為 1.0。
set_pane_ratios(ratios)	設置分欄高度比例。長度必須等於當前分欄總數（主欄 + 所有已加載腳本創建的子欄），各值之和須為 1.0。
scroll_to_bar(index)	滾動視口使索引為 index 的 K 線可見。K 線索引從最舊的 K 線起以 0 為基礎計數。
set_scroll_offset(offset)	直接設置視口左邊緣的分數 K 線索引。0.0 顯示最舊的 K 線；值越大越向右滾動到更新的 K 線。
set_viewport(offset, visible_bars)	在單次調用中同時設置滾動偏移和可見 K 線數（縮放級別）。等效於依次調用 set_scroll_offset 和調整縮放。
scroll_offset()	返回當前視口左邊緣的分數 K 線索引。
visible_bars()	返回當前縮放級別下可見的 K 線數量。
total_bars()	返回資料集中的 K 線總數。
set_highlighted_bar(index)	高亮指定 K 線（如標記策略交易）。傳入 Some(index) 高亮，傳入 None 清除高亮。已高亮的 K 線會以特殊背景渲染。
time_to_bar_index(time_ms)	返回時間戳 ≤ time_ms 的最新 K 線索引。若 time_ms 早於所有 K 線則返回 None。
bar_index_to_time(idx)	返回 idx 處 K 線的時間戳（毫秒），索引越界時返回 None。

分欄佈局

腳本調用 indicator(overlay=false) 時會自動創建子欄。使用 set_pane_ratios 控制各欄的相對高度：

// 主欄占 60%，兩個子欄各占 20%
cv.set_pane_ratios(vec![0.6, 0.2, 0.2]);

// 讀取當前比例
let ratios = cv.pane_ratios();
println!("分欄數量: {}", ratios.len());

比例切片的長度必須與當前分欄數相同。若腳本尚未加載，圖表只有一個主欄，此時 set_pane_ratios(vec![1.0]) 是唯一有效的調用。

K 線索引

K 線索引從最舊的 K 線起以 0 為基礎計數：

• 0 — 最舊（最左側）的 K 線
• total_bars() - 1 — 最新（最右側）的 K 線

visible_bars() 返回當前可見 K 線數，隨用戶縮放而變化。total_bars() 是已加載資料集的固定大小。

滾動到最新 K 線

use navi_chart::ViewportControl;

fn scroll_to_latest<C>(cv: &C)
where
    C: ViewportControl,
{
    let last = cv.total_bars().saturating_sub(1);
    cv.scroll_to_bar(last);
}

加載新資料或恢復快照後可調用此函數，確保最新 K 線可見。

懸停高亮 K 線

策略測試器中的常見模式：點擊交易記錄行時，滾動圖表到該 K 線並高亮顯示：

use navi_chart::ViewportControl;

fn jump_to_trade<C>(cv: &C, bar_index: usize)
where
    C: ViewportControl,
{
    cv.scroll_to_bar(bar_index);
    cv.set_highlighted_bar(Some(bar_index));
}

fn clear_highlight<C>(cv: &C)
where
    C: ViewportControl,
{
    cv.set_highlighted_bar(None);
}

保存與恢復視口狀態

use navi_chart::ViewportControl;

struct ViewportSnapshot {
    scroll_offset: f64,
    visible_bars: f64,
    pane_ratios: Vec<f64>,
}

fn save_viewport<C>(cv: &C) -> ViewportSnapshot
where
    C: ViewportControl,
{
    ViewportSnapshot {
        scroll_offset: cv.scroll_offset(),
        visible_bars: cv.visible_bars(),
        pane_ratios: cv.pane_ratios(),
    }
}

fn restore_viewport<C>(cv: &C, snap: ViewportSnapshot)
where
    C: ViewportControl,
{
    cv.set_viewport(snap.scroll_offset, snap.visible_bars);
    cv.set_pane_ratios(snap.pane_ratios);
}