1. 从一条折线图说起：为什么需要 Annotations 注释

做数据可视化时，图表本身能表达趋势，但很多关键信息光靠曲线是说不清的。比如一条温度曲线在某个时间点突然飙升，你希望直接在图上标一个「传感器异常」的文本框，还带个箭头指向那个尖峰；又比如做金融 K 线图，需要在某根柱子上挂一个「财报发布」的标签。这类需求，靠图例和坐标轴是解决不了的，必须用注释（Annotations）。

LightningChart 的 Annotations 就是干这个的。它允许你在图表区域的任意位置放置文本标签或自定义图形，这些注释可以跟随鼠标拖动、缩放、旋转，也可以用代码精确控制位置和样式。它和普通的 TextBox 不一样的地方在于：注释有一个 Target（箭头指向的目标点）和一个 Location（文本框所在位置），两者可以分别用轴值或屏幕坐标来定义，这就让「指向某个数据点、但文本框放在空白处」这种标注变得非常自然。

这篇教程面向的是已经在用 LightningChart 做数据可视化、但还没系统用过注释功能的开发者。我会从创建第一个 AnnotationXY 开始，把 Target 与 Location 的坐标系选择、Anchor 锚点、样式配置、尺寸控制、Z 序管理、性能优化这些点全部走一遍，每个环节都给可复制的代码和验证动作。你跟着做，最后能在一个 ViewXY 图表里放出一组带箭头、带样式、可交互编辑的注释，并且知道怎么排查常见的显示问题。

需要说明的是，本文基于 LightningChart 的 ViewXY 视图，AnnotationXY 对象挂在ViewXY.Annotations集合下。如果你用的是其他视图类型，集合名称可能不同，但属性逻辑是一致的。

2. 前置准备：环境、引用与 TaoToken 接入配置

在写注释代码之前，先把运行环境和模型接入这条链路理清楚。LightningChart 本身是本地渲染的图形控件，不依赖网络，但如果你在开发过程中想让 AI 辅助生成注释配置代码、或者用 Coding Agent 帮你补全属性，就需要一个稳定的模型接入点。我这边习惯用 TaoToken 来做这件事，它的 API 地址是https://taotoken.net/api，兼容常见的 OpenAI 风格调用，配置起来不折腾。

先说 LightningChart 这边的准备。你需要一个可用的 LightningChart 授权，然后在项目里引用对应的程序集。以 .NET 为例，安装包之后在代码里引入命名空间：

using Arction.Wpf.Charting; using Arction.Wpf.Charting.Views.ViewXY; using Arction.Wpf.Charting.Annotations;

如果你用的是 WinForms 版本，命名空间前缀换成Arction.WinForms.Charting即可，AnnotationXY 的属性和方法完全一致。创建图表和 ViewXY 的基础代码这里不展开，假设你已经有一个LightningChart _chart和一个ViewXY _viewXY，并且已经加了一条线系列。

接下来是 TaoToken 的接入。它的控制台在https://taotoken.net/console，你可以在里面创建 API Key。拿到 Key 之后，配置方式取决于你用的工具。如果你用的是 Cline 这类支持 MCP 的编辑器插件，配置片段大概长这样：

{ "mcpServers": { "taotoken": { "command": "npx", "args": ["-y", "@taotoken/mcp-server"], "env": { "TAOTOKEN_API_KEY": "sk-你的Key", "TAOTOKEN_BASE_URL": "https://taotoken.net/api" } } } }

如果你用的是 Claude Code，配置走的是 settings 文件，Base URL 填https://taotoken.net/api，Key 填你创建的那串，Model ID 按你选的模型填。这三件套——Base URL、Key、Model ID——缺一不可，很多人报 401 就是因为 Key 没填对或者 Base URL 多加了斜杠。

这里要提醒一句：TaoToken 是模型接入服务，不是编辑器替代品，它不会帮你写 LightningChart 的渲染逻辑，但可以在你查属性、生成样板代码、解释报错的时候省不少时间。模型对话入口在https://taotoken.net/models，接入文档在https://taotoken.net/doc，需要的时候可以直接翻。

环境准备好之后，我们就可以进入注释的正式配置了。

3. 可复制配置：创建 AnnotationXY 并控制 Target 与 Location

注释的核心是AnnotationXY对象。创建它的第一步是实例化并加入集合：

AnnotationXY annotation = new AnnotationXY(_viewXY); _viewXY.Annotations.Add(annotation);

但光这样加进去，你什么都看不到，因为 Target 和 Location 都还没设。这两个属性是注释的骨架：Target 是箭头尖端指向的点，Location 是文本框的起始位置。它们各自可以用不同的坐标系来定义，这就是TargetCoordinateSystem和LocationCoordinateSystem的作用。

先看 Target。如果你想让箭头指向某个数据点，用轴值坐标系最直观：

annotation.TargetCoordinateSystem = AnnotationTargetCoordinates.AxisValues; annotation.TargetAxisValues.X = 50; annotation.TargetAxisValues.Y = 120;

这段代码的意思是，箭头尖端指向 X 轴值 50、Y 轴值 120 的那个位置。如果你更习惯用屏幕像素来定位，把坐标系换成ScreenCoordinates，然后用TargetScreenCoords设置：

annotation.TargetCoordinateSystem = AnnotationTargetCoordinates.ScreenCoordinates; annotation.TargetScreenCoords.X = 400; annotation.TargetScreenCoords.Y = 300;

Location 的选择更多，有三个坐标系：LocationScreenCoords、LocationAxisValues、LocationRelativeOffset。最常用的是相对偏移，因为它能让文本框相对 Target 保持一个固定的偏移量，图表缩放时注释不会跑偏：

annotation.LocationCoordinateSystem = AnnotationLocationCoordinates.RelativeOffset; annotation.LocationRelativeOffset.X = 80; annotation.LocationRelativeOffset.Y = -60;

这里的 80 和 -60 是相对于 Target 的像素偏移，正值向右、负值向上。这样设置之后，无论你怎么缩放图表，文本框都会待在箭头起点右上方 80、60 像素的位置。

接下来是 Anchor。Anchor 控制文本框在 Location 上的放置方式，取值在 0 到 1 之间。Anchor.X = 0.5、Anchor.Y = 0.5表示箭头起点在文本框正中间；Anchor.X = 0.1、Anchor.Y = 0.25表示起点靠近文本框左上角。这个属性在你想让箭头从文本框边缘而不是中心伸出时特别有用。

把上面这些拼起来，一个完整的注释配置片段如下：

AnnotationXY annotation = new AnnotationXY(_viewXY); annotation.TargetCoordinateSystem = AnnotationTargetCoordinates.AxisValues; annotation.TargetAxisValues.X = 50; annotation.TargetAxisValues.Y = 120; annotation.LocationCoordinateSystem = AnnotationLocationCoordinates.RelativeOffset; annotation.LocationRelativeOffset.X = 80; annotation.LocationRelativeOffset.Y = -60; annotation.Anchor.X = 0.5; annotation.Anchor.Y = 0.5; annotation.Text = "峰值点"; annotation.Style = AnnotationStyle.RoundedRectangleArrow; annotation.Fill.Color = Color.FromArgb(200, 255, 240, 200); annotation.TextStyle.FontSize = 14; annotation.TextStyle.Color = Colors.Black; _viewXY.Annotations.Add(annotation);

这段代码创建了一个圆角矩形带箭头的注释，填充淡黄色，文字是「峰值点」，箭头指向数据点 (50, 120)，文本框在箭头起点右上方。你可以直接把这段贴进你的项目，改一下坐标和文字就能用。

样式方面，Style属性支持的选项有 Rectangle、RectangleArrow、RoundedRectangle、RoundedRectangleArrow、Arrow、Callout、RoundedCallout、Ellipse、EllipseArrow、Triangle、TriangleArrow。带 Arrow 后缀的会显示箭头线，箭头末端的样式用ArrowStyleEnd控制，可选 None、Square、Arrow、Circle、Caliper。填充用Fill，边框用BorderLineStyle，圆角半径用CornerRoundRadius。

尺寸控制用Sizing属性，三个选项：Automatic 根据内容自动调整，AxisValuesBoundaries 用轴值定义边界，ScreenCoordinates 用屏幕像素定义宽高。大多数场景用 Automatic 就够了，配合AutoSizePadding留出内边距。

4. 验证请求与成功结果：确认注释正确显示

配置写完，怎么确认注释真的按预期显示了？我一般分三步验证。

第一步，编译运行，看注释有没有出现在图表上。如果什么都没看到，先检查_viewXY.Annotations.Add(annotation)有没有执行，以及 Target 和 Location 的坐标是不是落在当前可见的轴范围内。轴范围是 0 到 100，你把 Target 设成 500，注释自然在屏幕外。

第二步，验证 Target 和 Location 的对应关系。把鼠标移到注释上，进入编辑状态，你会看到几个交互节点：Target 节点、Location 节点、resize 节点、旋转节点。拖动 Target 节点，箭头末端应该跟着走；拖动文本框，Location 应该变化；拖动圆形的 location/锚节点，Anchor 和 Location 会同时调整，但文本框位置保持不变。按住 Shift 再拖 resize 节点，可以对称调整大小；按住 Shift 旋转，会以 15 度为单位吸附。

第三步，用代码读取属性，确认值和预期一致。比如：

Console.WriteLine($"Target: {annotation.TargetAxisValues.X}, {annotation.TargetAxisValues.Y}"); Console.WriteLine($"Location offset: {annotation.LocationRelativeOffset.X}, {annotation.LocationRelativeOffset.Y}"); Console.WriteLine($"Anchor: {annotation.Anchor.X}, {annotation.Anchor.Y}");

如果这些值和你在代码里设的一致，说明配置生效了。如果 Target 是轴值坐标系，缩放图表时箭头应该始终指向同一个数据点；如果 Location 是相对偏移，文本框应该跟着 Target 一起移动。这两点是判断坐标系选对没选对的关键。

还有一个验证点是 KeepVisible。开启annotation.KeepVisible = true之后，无论你怎么平移视图或调整轴，文本框都会被强制留在图表内部。你可以把 Target 设到边缘，然后平移图表，观察文本框是不是被「推」回可见区域。这个属性在做交互式图表时很有用，避免用户把注释拖丢。

如果一切正常，你应该能看到类似这样的效果：一条折线，某个峰值上有一个带箭头的圆角矩形标签，鼠标移上去可以拖动、旋转、缩放，移开鼠标退出编辑状态。这就是 Annotations 的基本工作流。

5. 常见报错与排查：401、local proxy failed、reading choices 等

配置过程中最容易踩的坑，往往不在 LightningChart 本身，而在模型接入和工具链上。我把几个高频报错和排查思路列一下。

401 Unauthorized：这个基本是 Key 的问题。检查 TaoToken 的 API Key 有没有填对，有没有多余空格，Base URL 是不是https://taotoken.net/api而不是别的路径。如果你用的是 Cline MCP 配置，确认TAOTOKEN_API_KEY环境变量真的传进去了，有时候 JSON 里写了但没生效，重启一下编辑器。

local proxy failed：这个报错通常出现在你本地起了代理但配置没对齐的时候。检查你的工具里 Base URL 是不是被错误地指向了 localhost 端口，正确做法是直接填https://taotoken.net/api，不要经过本地转发。如果你确实需要本地代理，确认端口和上游地址一致。

reading choices 报错：这个一般出现在调用返回结构不符合预期的时候。检查你用的 Model ID 是否在 TaoToken 支持的列表里，模型对话页面https://taotoken.net/models可以查到可用模型。如果 Model ID 拼错了，返回结构会异常，解析 choices 时就报错。

OAuth 相关报错：如果你用的是 Claude Code 或类似工具，OAuth 流程走的是浏览器回调。报错时先确认回调地址有没有被防火墙拦，再确认 settings 里的 Base URL 和 Key 是不是三件套齐全。Claude Code 的配置里，Base URL、Key、Model ID 任何一个缺失都会导致认证失败。

注释不显示：回到 LightningChart 这边，如果注释加进去了但看不到，检查ClipInsideGraph是不是设成了 true 而注释位置在图形外；检查RenderBehindAxes是不是 true 导致注释被轴挡住；检查Behind属性是不是 true 导致注释被系列盖住。这几个属性都会影响可见性。

文本渲染错乱：如果你开了LayerGrouping = true并且有多个注释重叠，文本的 Z 序会丢失，出现渲染错误。这是性能优化的代价，注释数量少的时候建议关掉 LayerGrouping，保持默认的按 Z 序渲染。

Z 序不对：注释默认在系列上方显示。如果想让某个注释在系列下方，设Behind = true。同一层级内，注释按加入集合的顺序显示，可以用ChangeOrder方法调整，选项有 BringToFront、SendToBack、MoveBack、MoveFront。

排查的时候，我习惯先把问题范围缩小：是模型接入的问题，还是 LightningChart 渲染的问题？前者看报错关键词，后者看属性配置。两边分开查，效率高很多。

6. 进阶配置与长期编码建议

把基础注释跑通之后，有几个进阶点值得花时间掌握。

轴值与屏幕坐标的混合使用。有时候你希望 Target 用轴值、Location 用屏幕坐标，或者反过来。LightningChart 提供了ValueToCoord和CoordToValue两个方法来做转换。比如你想把某个轴值转成屏幕坐标再设置 Location：

double screenX = _viewXY.XAxes[0].ValueToCoord(50); double screenY = _viewXY.YAxes[0].ValueToCoord(120); annotation.LocationCoordinateSystem = AnnotationLocationCoordinates.ScreenCoordinates; annotation.LocationScreenCoords.X = screenX + 80; annotation.LocationScreenCoords.Y = screenY - 60;

这种混合配置在需要精确控制像素位置、但又想锚定数据点的场景里很有用。

性能优化。当图表上有数百个带文本的注释时，文本渲染会成为瓶颈。开启LayerGrouping = true可以把文本渲染压缩到两个平面层，一个用于 Behind 为 true 的注释，一个用于 Behind 为 false 的注释，性能提升明显。代价是重叠注释的文本 Z 序会丢失。如果你的注释不重叠，或者用的是 Arrow 样式、填充不可见，这个限制通常不会显现。

鼠标交互的精细控制。注释的编辑状态由鼠标悬停触发，移开就退出。如果你想让注释默认就处于可编辑状态，或者禁用某些交互节点，可以通过 NibStyle 调整交互节点的外观，通过属性控制哪些操作可用。这在做演示或者教学图表时很有用。

长期编码的工具选择。如果你经常写这类图形控件的配置代码，建议配一个稳定的 Coding Agent。TaoToken 的 Coding Plan 入口在https://taotoken.net/coding-plan，适合长期编码场景。把 Base URL、Key、Model ID 三件套配好之后，让 Agent 帮你生成注释配置的样板、解释属性含义、排查报错，比手动翻文档快。API Key 管理在https://taotoken.net/api-keys，接入文档在https://taotoken.net/doc，需要的时候直接查。

最后说一个我自己的经验：注释的坐标系选择，优先用相对偏移（RelativeOffset）而不是绝对屏幕坐标。因为图表一旦缩放或平移，绝对坐标就失效了，而相对偏移能让注释始终跟着数据点走。只有在需要精确像素对齐的特殊场景，才用屏幕坐标。这个习惯能帮你省掉大量「为什么注释跑偏了」的调试时间。