Blazor WebGL 从零入门：用 Blazor.Extensions.Canvas 绘制你的第一个三角形

Blazor WebGL 从零入门：用 Blazor.Extensions.Canvas 绘制你的第一个三角形

【免费下载链接】CanvasHTML5 Canvas API implementation for Microsoft Blazor项目地址: https://gitcode.com/gh_mirrors/canvas/Canvas

想用 C# 在浏览器里画出 3D 图形？Blazor WebGL 帮你轻松实现。本文将带你认识Blazor.Extensions.Canvas——一个把 HTML5 Canvas 与 WebGL API 完整封装给 Microsoft Blazor 的开源库，让你不必编写一行 JavaScript，就能用纯 C# 绘制出第一个彩色三角形。全文面向零基础新手，安装、编码、避坑三步走，读完即可上手。

什么是 Blazor.Extensions.Canvas？它适合 WebGL 新手吗？

Blazor.Extensions.Canvas 是 Blazor 生态中一个非常实用的开源组件库，它把浏览器原生的 Canvas 2D 和 WebGL 两套绘图 API，翻译成了 .NET 开发者熟悉的异步方法。你在 C# 中调用ClearColorAsync、DrawArraysAsync，底层通过 JS 互操作（Interop）去驱动浏览器画布，体验和写原生 WebGL 几乎一致。

对新手来说，它最大的价值是：不用学 JavaScript，也不用碰复杂的 DOM 操作，用熟悉的 C# 语法就能开始图形编程。无论你用的是 Blazor Server 还是 Blazor WebAssembly，它都开箱即用。

快速安装 Blazor.Extensions.Canvas 的 3 个步骤

动手之前，先把依赖准备好，整个过程不到 3 分钟：

第 1 步：NuGet 安装。在项目里执行：

Install-Package Blazor.Extensions.Canvas

第 2 步：引入 JS 脚本。Blazor WebAssembly 项目在wwwroot/index.html中、Blazor Server 项目在Pages/_Host.cshtml中，加入一行引用：

<script src="_content/Blazor.Extensions.Canvas/blazor.extensions.canvas.js"></script>

第 3 步：添加命名空间。在_Imports.razor中写入：

@using Blazor.Extensions.Canvas

完成这三步，你的 Blazor 项目就具备 WebGL 能力了 🚀

理解 WebGL 绘制三角形的最小流程

在写代码前，先花 30 秒理解 WebGL 的"套路"。WebGL 绘制图形靠的不是"画线"，而是GPU 渲染管线，画一个三角形最少需要四步：

1. 编写着色器：用 GLSL 语言写两个小程序——顶点着色器负责定位顶点，片元着色器负责给像素上色。
2. 准备顶点数据：把三角形的三个顶点坐标放进缓冲区（Buffer），交给 GPU。
3. 配置顶点属性：告诉 GPU 缓冲区里哪些数据是位置、哪些是颜色。
4. 发起绘制命令：调用DrawArrays，让 GPU 完成渲染。

这个流程在 Blazor.Extensions.Canvas 中被封装为一连串清晰的异步方法，逐行对照即可理解。核心实现都集中在 WebGLContext.cs 中，方法命名与原生 WebGL 保持一一对应。

第一步：在 Blazor 页面中放置画布

在任意.razor页面中放置一个画布组件，并给它绑定一个引用（ref）：

<BECanvas Width="800" Height="600" @ref="_canvasReference"></BECanvas>

BECanvas组件会渲染出一个真正的<canvas>标签，宽高属性直接生效。其组件定义见 BECanvas.razor，底层字段封装在 BECanvasComponent.cs 中。

第二步：编写绘制三角形的核心代码

这是全文最关键的一步。在对应的组件代码中（.razor的@code块或独立的.cs文件均可），依次完成以下操作。

首先声明字段，并在OnAfterRenderAsync中创建 WebGL 上下文：

private WebGLContext _context; protected BECanvasComponent _canvasReference; protected override async Task OnAfterRenderAsync(bool firstRender) { _context = await _canvasReference.CreateWebGLAsync(); await _context.ClearColorAsync(0.2f, 0.3f, 0.3f, 1); // ... 后续绘制代码 }

接着定义着色器源码与顶点数据：

private const string VS_SOURCE = "attribute vec3 aPos; attribute vec3 aColor; varying vec3 vColor;" + "void main() { gl_Position = vec4(aPos, 1.0); vColor = aColor; }"; private const string FS_SOURCE = "precision mediump float; varying vec3 vColor;" + "void main() { gl_FragColor = vec4(vColor, 1.0); }"; private readonly float[] _vertices = { -0.5f, -0.5f, 0.0f, 1.0f, 0.0f, 0.0f, // 左下角：红色 0.5f, -0.5f, 0.0f, 0.0f, 1.0f, 0.0f, // 右下角：绿色 0.0f, 0.5f, 0.0f, 0.0f, 0.0f, 1.0f // 顶部：蓝色 };

然后编译着色器、上传数据并绘制。这里给出完整可运行的核心逻辑：

// 1. 编译并链接着色器程序 var vs = await _context.CreateShaderAsync(ShaderType.VERTEX_SHADER); await _context.ShaderSourceAsync(vs, VS_SOURCE); await _context.CompileShaderAsync(vs); var fs = await _context.CreateShaderAsync(ShaderType.FRAGMENT_SHADER); await _context.ShaderSourceAsync(fs, FS_SOURCE); await _context.CompileShaderAsync(fs); var program = await _context.CreateProgramAsync(); await _context.AttachShaderAsync(program, vs); await _context.AttachShaderAsync(program, fs); await _context.LinkProgramAsync(program); await _context.UseProgramAsync(program); // 2. 创建缓冲区并上传顶点数据（位置 + 颜色交错排列） var buffer = await _context.CreateBufferAsync(); await _context.BindBufferAsync(BufferType.ARRAY_BUFFER, buffer); await _context.BufferDataAsync(BufferType.ARRAY_BUFFER, _vertices, BufferUsageHint.STATIC_DRAW); // 3. 配置顶点属性：0 号属性为位置（前 3 个 float），1 号属性为颜色（后 3 个 float） await _context.VertexAttribPointerAsync(0, 3, DataType.FLOAT, false, 6 * sizeof(float), 0); await _context.VertexAttribPointerAsync(1, 3, DataType.FLOAT, false, 6 * sizeof(float), 3 * sizeof(float)); await _context.EnableVertexAttribArrayAsync(0); await _context.EnableVertexAttribArrayAsync(1); // 4. 清屏并绘制三角形 await _context.BeginBatchAsync(); await _context.ClearAsync(BufferBits.COLOR_BUFFER_BIT); await _context.DrawArraysAsync(Primitive.TRIANGLES, 0, 3); await _context.EndBatchAsync();

运行后，一个红绿蓝三色渐变三角形就会出现在画布中央 🎨 项目中完整的官方示例见 WebGLComponent.cs，各种枚举类型（如ShaderType、Primitive、DataType）都在 WebGLEnums.cs 中定义。

Blazor WebGL 常见坑：为什么我的三角形不显示？

新手最容易踩的坑有三个，提前避开能省下大量排查时间：

坑 1：在OnInitAsync中创建上下文❌。此时<canvas>元素还没渲染到 DOM 上，无法获取上下文。务必把创建逻辑放在OnAfterRenderAsync中，或参考 README 中 README.md 的说明。

坑 2：Blazor Server 下绘制"丢失"⚠️。服务端渲染时，多个绘制操作可能被分批发送，导致只有最后一个操作生效。解决办法是把所有绘制类调用用BeginBatchAsync和EndBatchAsync显式包裹起来——这正是上面代码第 4 步的做法。这一机制在 RenderingContext.cs 中实现。

坑 3：着色器编译失败却不报错🔍。建议像官方示例那样，编译和链接后主动检查GetShaderParameterAsync<bool>(shader, ShaderParameter.COMPILE_STATUS)与GetProgramParameterAsync<bool>(program, ProgramParameter.LINK_STATUS)，失败时用GetShaderInfoLogAsync取出日志，方便定位拼写错误。

继续深入 Blazor WebGL：下一步可以学什么？

三角形只是起点，掌握了这套流程后，你可以继续探索：

• 调用批量优化：理解 RenderingContext.cs 中的自动批处理机制，让复杂场景保持流畅。
• WebGL 上下文配置：通过WebGLContextAttributes调整抗锯齿、深度缓冲、电源偏好等参数，定义见 WebGLObjects.cs。
• 进阶图形知识：从三角形升级到立方体，学习矩阵变换、纹理贴图、光照模型，逐步做出真正的 3D 场景。
• 阅读官方测试项目：客户端与服务端两个示例工程都在test/目录下，是很好的学习素材。

总结

通过本文，你已经完成了 Blazor WebGL 的入门三部曲：安装 Blazor.Extensions.Canvas、在页面中放置画布、用纯 C# 绘制出第一个三角形。相比原生 JavaScript WebGL，这套方案让 .NET 开发者能以最低的学习成本踏入图形编程世界。现在，打开你的 Blazor 项目，动手画出属于自己的第一个三角形吧！💪

【免费下载链接】CanvasHTML5 Canvas API implementation for Microsoft Blazor项目地址: https://gitcode.com/gh_mirrors/canvas/Canvas