1. Delphi 透明光标为什么总是黑底从 CreateIconIndirect 的掩码机制说起在 Delphi 桌面应用里做自定义光标很多人第一次尝试都会遇到同一个现象明明加载的是一张带透明通道的 PNG 或设置了 TransparentColor 的 BMP结果鼠标指针显示出来却是一块黑底或者粉红底。这个问题的根源不在 Delphi而在 Windows 的CreateIconIndirect这个 API 对光标位图的要求——它需要两张位图一张 AND 掩码、一张 OR/XOR 图像两者配合才能实现真正的透明。我试过直接拿一张 32 位带 Alpha 的位图丢进去结果光标边缘全是锯齿加黑边。后来才搞明白Windows 光标HCURSOR本质上是单色掩码加彩色图像的双位图结构跟现代图形学里的 Alpha 混合不是一回事。你要么老老实实生成 AND/OR 掩码要么用CreateIconFromResourceEx走另一条路。本篇聚焦前者因为它在 Delphi 里最容易控制也最方便跟接口联调结合。所谓透明光标核心是让光标图像中某些像素不参与绘制露出下面的桌面或窗口内容。Windows 的做法是AND 掩码里白色1表示保留目标像素、黑色0表示把目标像素清成黑OR 掩码里再决定最终颜色。两张掩码一与一或就能表达透明反色实色三种状态。所以生成透明光标的关键就是正确构造这两张掩码而color_key就是用来标记哪些像素应该透明的占位色。这个场景适合谁适合正在做 Delphi VCL 或 FMX 桌面工具、需要自定义鼠标指针比如绘图软件、游戏编辑器、工业组态软件的开发者。你不需要精通 GDI但需要理解掩码的基本逻辑否则调出来的光标永远差那么一点。下面我会把可复制的代码、掩码配置、以及如何用 TaoToken 统一 Key 通道做接口联调验证串起来让你在本地就能跑通生成光标 → 渲染验证 → 接口连通的完整链路。先明确一个概念color_key默认用粉红$FF00FF也就是TColor($FF00FF)是因为这个颜色在正常图像里极少出现适合当透明占位色。你加载 BMP 后把TransparentColor设成它、Transparent设为 TrueDelphi 的TBitmap就会在绘制时把该颜色当透明处理。但注意CreateIconIndirect不认TBitmap.Transparent它只认你手动构造的掩码所以中间必须经过Mask()这一步转换。理解了这层后面代码就不会觉得为什么要这么麻烦了。麻烦是麻烦但这是 Windows 光标模型的硬性要求绕不过去。2. TaoToken 统一 Key 通道前置准备Base URL、API Key 与 Model ID 三件套在写光标代码之前先把接口联调的环境搭好。为什么要在这里讲 TaoToken因为很多 Delphi 项目的光标资源不是写死的而是从服务端拉取配置或图标资源或者你需要把光标渲染结果上报做验证。这时候一个统一的 Key 通道能省掉大量切换成本。TaoToken 提供的就是这样一个统一入口你拿一个 Key 就能访问多种模型接口不用为每个服务单独配一套鉴权。前置准备其实就三样东西我把它叫三件套Base URL、API Key、Model ID。任何接入类问题先检查这三件套是否齐全且一致能排掉一大半故障。Base URL 用https://taotoken.net/api注意这里不加任何查询参数保持干净。API Key 需要你到控制台创建路径是https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite进去后新建一个 Key复制出来保存好它只显示一次。Model ID 则取决于你要调用的模型比如做代码补全或对话验证时选对应的模型标识。如果你用的是 Claude Code 这类工具做辅助开发接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有各语言的调用示例。想先快速验证模型通不通可以直接用模型对话页面https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite发一条消息试试。长期做编码或 Agent 任务的话Coding Plan 页面https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite有更划算的套餐说明。这里要强调一点TaoToken 是合规的 API 聚合通道不是任何形式的非法中转你正常按文档调用即可。配置时把 Base URL 和 Key 写进你的 Delphi HTTP 客户端或配置文件Model ID 按需选择。三件套齐了再往下走光标代码联调时就不会因为鉴权问题卡住。对于 Delphi 项目我建议把这三件套放在一个独立的配置单元里比如Config.pas用常量或 ini 读取。这样光标模块和网络模块解耦调试时改一处就行。下面给一个配置片段示例你可以直接抄进项目unit Config; interface const TAOTOKEN_BASE_URL https://taotoken.net/api; TAOTOKEN_API_KEY sk-你的Key粘贴在这里; TAOTOKEN_MODEL_ID 你的模型ID; implementation end.实际项目里别把 Key 硬编码进源码提交到仓库用环境变量或加密配置读取。这里为了演示方便才写成常量。三件套准备好下一节进入光标生成的可复制配置。3. 可复制配置CreateCursorByGraphic 掩码生成与 JSON 联调参数这一节是核心给你能直接跑的代码和配置。先看光标生成部分基于CreateIconIndirect的双掩码方案。我把原始逻辑整理成两个函数CreateCursorByGraphic负责从任意TGraphic生成光标CreateCursorByBitmap是便捷封装处理TBitmap的透明色切换。function CreateCursorByGraphic(bm: TGraphic; const hotx, hoty: Integer; const color_key: TColor TColor($FF00FF)): HCursor; var IconSizeX, IconSizeY: Integer; AndMask, OrMask: TBitmap; IconInfo: TIconInfo; myrc: TRect; begin AndMask : TBitmap.Create; OrMask : TBitmap.Create; try IconSizeX : bm.Width; IconSizeY : bm.Height; AndMask.Width : IconSizeX; AndMask.Height : IconSizeY; OrMask.Width : IconSizeX; OrMask.Height : IconSizeY; myrc : Rect(0, 0, IconSizeX, IconSizeY); // 构造 AND 掩码先用 color_key 填充再绘制图像最后 Mask 成黑白 AndMask.Canvas.Brush.Color : color_key; AndMask.Canvas.FillRect(myrc); AndMask.Canvas.Draw(0, 0, bm); AndMask.Mask(color_key); // 构造 OR 掩码黑底绘制原图保留颜色信息 OrMask.Canvas.Brush.Color : clBlack; OrMask.Canvas.FillRect(myrc); OrMask.Canvas.Draw(0, 0, bm); // 组装 TIconInfofIcon 必须为 False 表示这是光标 IconInfo.fIcon : False; IconInfo.xHotspot : hotx; IconInfo.yHotspot : hoty; IconInfo.hbmMask : AndMask.Handle; IconInfo.hbmColor : OrMask.Handle; Result : CreateIconIndirect(IconInfo); finally AndMask.Free; OrMask.Free; end; end;注意xHotspot和yHotspot是热点坐标也就是光标点击生效的那个像素位置。原始代码里写了-hotx那是个笔误或者特定场景的偏移正常应该传正数比如箭头光标热点在左上角就是(0,0)。热点设错会导致点击位置偏移这是常见坑。再看TBitmap封装function CreateCursorByBitmap(bm: TBitmap; const hotx, hoty: Integer; const color_key: TColor TColor($FF00FF)): HCursor; var old_color: TColor; old_trans: Boolean; begin old_color : bm.TransparentColor; old_trans : bm.Transparent; bm.TransparentColor : color_key; bm.Transparent : True; try Result : CreateCursorByGraphic(bm, hotx, hoty, color_key); finally bm.TransparentColor : old_color; bm.Transparent : old_trans; end; end;它临时把位图的透明色设成color_key生成完再还原避免污染调用方的位图状态。这个细节很关键否则你后续复用同一张位图会出问题。接下来是联调参数。假设你要把光标配置或渲染结果通过 TaoToken 接口验证用 JSON 传参。一个典型的请求体配置如下路径和字段名按你实际接口调整{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model_id: 你的模型ID, task: cursor_render_verify, payload: { cursor_name: Popo, hotspot_x: 0, hotspot_y: 0, color_key: #FF00FF, image_format: bmp } }如果你用 TOML 管理配置比如配合某些 CLI 工具可以写成[taotoken] base_url https://taotoken.net/api api_key sk-你的Key model_id 你的模型ID [cursor] name Popo hotspot_x 0 hotspot_y 0 color_key #FF00FF三件套在这里体现为base_url、api_key、model_id三个字段缺一不可。Delphi 里读取 JSON 可以用System.JSON读取 TOML 需要第三方库或自己解析建议优先 JSON原生支持更省事。配置齐了下一节做实际验证请求看光标能不能正确渲染、接口能不能通。4. 验证请求与成功结果加载 BMP、注册光标、发一条联调请求代码和配置都有了现在跑起来验证。先做本地光标渲染验证再做接口连通验证两步都过了才算完整。本地验证的测试代码var b1: TBitmap; cursor: HCursor; begin b1 : TBitmap.Create; try b1.LoadFromFile(Popo.bmp); cursor : CreateCursorByBitmap(b1, 0, 0); if cursor 0 then begin Screen.Cursors[10] : cursor; Form1.Cursor : 10; end else ShowMessage(光标创建失败); finally b1.Free; end; end;这里Screen.Cursors[10]是把光标注册到全局光标表索引 10 是自定义位置0 到 15 左右是系统保留具体范围看 Windows 版本建议用 10 以上。Form1.Cursor : 10让窗体使用这个光标。运行后把鼠标移到窗体上如果看到的是带透明背景的 Popo 图像说明掩码生成正确如果还是黑底或粉红底回到第 3 节检查color_key和Mask()调用。成功的结果应该是光标图像边缘干净透明区域露出窗体背景热点位置点击准确。你可以故意把热点设成(5,5)再测看点击位置是否偏移以此确认热点参数生效。接口连通验证用 TaoToken。Delphi 里发 HTTP 请求可以用TNetHTTPClient较新版本或IdHTTPIndy。以TNetHTTPClient为例var http: TNetHTTPClient; req: TNetHTTPRequest; resp: IHTTPResponse; body: TStringStream; begin http : TNetHTTPClient.Create(nil); try http.CustomHeaders[Authorization] : Bearer TAOTOKEN_API_KEY; http.CustomHeaders[Content-Type] : application/json; body : TStringStream.Create( {model: TAOTOKEN_MODEL_ID ,messages:[{role:user,content:ping}]}, TEncoding.UTF8); try resp : http.Post(TAOTOKEN_BASE_URL /v1/chat/completions, body); if resp.StatusCode 200 then ShowMessage(接口连通返回 resp.ContentAsString(TEncoding.UTF8)) else ShowMessage(状态码 IntToStr(resp.StatusCode)); finally body.Free; end; finally http.Free; end; end;成功结果是返回 200 并且 body 里有模型回复内容。如果返回 401说明 Key 有问题如果连接超时检查 Base URL 是否写对、网络是否正常。这一步通了说明你的三件套配置正确后续把光标渲染结果上报或拉取远程光标资源都没问题。两步验证都过整个链路就闭环了本地生成透明光标 → 渲染确认 → 接口联调确认通道可用。下面讲常见报错怎么排。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth 对照调试过程中最容易撞的几个报错我按现象、原因、解法列出来你对照着查。401 Unauthorized接口返回 401基本是 Key 的问题。检查三件套里的api_key是否粘贴完整、有没有多余空格、是不是复制时漏了前缀。TaoToken 的 Key 在控制台创建后只显示一次如果丢了就重新建一个。另外确认请求头是Authorization: Bearer sk-xxx格式少个 Bearer 也会 401。local proxy failed这个报错通常出现在你本地配了代理或环境变量指向了不可用的地址。检查系统环境变量里有没有HTTP_PROXY、HTTPS_PROXY残留Delphi 的 HTTP 客户端有时会读取这些。清掉或改成正确值即可。注意这里说的是本地开发环境的代理配置问题跟任何网络访问方式无关纯粹是环境变量污染。reading choices 相关报错如果你在解析返回 JSON 时报reading choices之类的错误说明返回体结构跟你预期的不一样。可能是接口返回了错误对象而不是正常的choices数组。先打印完整返回内容看结构再决定解析路径。常见于 Model ID 写错导致接口返回错误信息。OAuth 相关报错如果你用的是需要 OAuth 流程的工具比如某些 CLI 的登录态报 OAuth 失败时检查 token 是否过期、回调地址是否配置正确。TaoToken 的 API Key 方式不涉及 OAuth直接用 Bearer 头即可所以如果你在 Delphi 里看到 OAuth 报错多半是误用了某个工具的登录配置换回 API Key 方式就行。再补一个光标相关的坑CreateIconIndirect返回 0 表示失败常见原因是掩码位图尺寸不一致或者hbmMask/hbmColor传了空句柄。确保两张位图都正确创建且尺寸相同。还有生成的 HCursor 用完要记得DestroyCursor否则句柄泄漏长时间运行的程序会累积资源。对照这些报错逐个排查大部分问题都能定位。排障时优先确认三件套再看网络环境最后看代码逻辑顺序别乱。6. 语义一致 CTA从光标调试到接口验证的下一步光标生成和接口联调都跑通之后你手里其实有了一套可复用的模式本地资源处理 统一 Key 通道验证。这套模式可以扩展到更多场景比如批量生成不同状态的光标正常、忙碌、拖拽、把光标配置存到服务端动态下发、或者用模型接口自动生成光标图像的描述再转成位图。如果你在排障或接入过程中卡住了优先看接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有各语言和各工具的完整示例。需要新建或管理 Key 就去 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite。想先验证某个模型能不能满足你的需求直接到模型对话https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite发消息试。长期做编码或 Agent 任务Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite更合适。最后给一个实用技巧把光标生成的color_key和热点坐标做成可配置项调试时不用重新编译。你可以用命令行参数或 ini 文件传入配合接口验证快速迭代。这样每次调整光标效果改配置重启即可效率高很多。
