视口控制

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);
}