设置与事件

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

方法参考

方法	说明
`set_theme(theme)`	为图表应用 `Theme`。内置主题：`Theme::dark()` 和 `Theme::light()`。自定义主题请参阅主题定制。
`set_locale(locale)`	设置图例标签和错误信息的显示语言（如 `"en"`、`"zh-CN"`）。
`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-CN");
    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（自动生成设置控件）

风格列表