Wuldas.Square.Backends.AndroidCanvas 0.2.0

Square

Square 是一个纯 C#、编译优先、NativeAOT 友好的实验性跨平台桌面 UI 框架。

它借鉴 Vue、HTML 与 CSS 的开发体验，但不是浏览器，也不引入 Vue 运行时或 JavaScript 引擎。.sqv / .sqx 模板会在编译期由 Roslyn Source Generator 生成普通 C# 组件。

项目仍处于早期开发阶段，API 与模板语法可能调整。目前主要验证 Windows / Win32 与 Linux / X11 桌面宿主。

0.2.0 性能优化

• 优化分词缓存热路径：按需剪枝、二分前驱查询、复用跨行状态，已缓存读取保持零托管分配。
• 优化大文本回跳：固定检查点预算内保留全局恢复点与目标附近密集点，减少跨区跳转和编辑失效后的重新分词。
• 继续降低布局、CSS 动画、绘制与局部失效路径的 CPU 和分配开销，完善性能对比与回归测试。

百万行混合 C# 文本测试中，相比前阶段优化版，回跳至第 8,192 行的真实 TextMate 分词从 1,727.7 ms 降至 434.2 ms，重扫行数由 8,192 降至 2,048；已缓存读取保持零托管分配。这是指定轨迹的分词缓存测量，不是整帧或任意访问模式的保证。环境、采样及复现方法见完整性能报告。

版本改动与平台边界见 0.2.0 发布说明。

截图

示例

Main.sqv：

<template>
  <View class="page">
    <Text class="title">Hello {{ Name.Value }}</Text>

    <Input :value="Name" @input="OnNameChanged" />

    <Button ref="SaveButton" @click="OnSave">
      Save
    </Button>

    <Text v-if="Saved.Value">Saved</Text>
  </View>
</template>

<script lang="csharp">
  public ObservableValue<string> Name = new("Square");
  public ObservableValue<bool> Saved = new(false);

  private void OnNameChanged(Event e)
  {
      Name.Value = ((Input)e.Target!).Value;
  }

  private void OnSave()
  {
      Saved.Value = true;
  }
</script>

<style>
  .page {
      display: flex;
      flex-direction: column;
      gap: 12px;
      padding: 16px;
  }

  .title {
      font-size: 20px;
  }
</style>

Program.cs：

using Square.Hosting;

var window = new AppWindow("My App", 800, 600);
window.Load(new Main());

new DesktopApplication(window).Run();

创建独立应用

Wuldas.Square.Templates 0.2.0 已发布到 NuGet.org。安装 .NET 10 SDK 后，无需克隆仓库或配置本地包源：

dotnet new install Wuldas.Square.Templates@0.2.0
dotnet new square -n MyApp
dotnet run --project MyApp

也可生成桌面与 Android 共用的应用，或添加组件：

dotnet new square -n MyMobileApp --platforms desktop,android --markup sqx
dotnet new square-component -n UserCard -o MyApp/Components --namespace MyApp.Components

默认使用 SQV + Software，依赖直接从 NuGet.org 还原；通过共享 SquareProgram.CreateWindow() 复用桌面与可选 Android 的应用初始化。平台要求、模板选项和框架开发者的本地打包流程见入门指南。

运行示例

dotnet restore Square.slnx
dotnet build Square.slnx
dotnet run --project samples/Square.Sample.Vue/Square.Sample.Vue.csproj

静态 HTML/CSS 外壳与 SQX/SQV 局部挂载示例（可选包默认不启用）：

dotnet run --project samples/Square.Sample/Square.Sample.csproj -c Release -p:SquareSampleUseNativeHtml=true -- --backend Software --html-mount-demo

用 --html-file <path> 指定自定义外壳；组件挂载到 #sqx-root / #sqv-root，卸载永久释放绑定与生成样式，再挂载须新实例。完整 API 和文件资源边界见 本地静态 HTML 与组件挂载。

Debug 模式下可使用 dotnet watch 热更新普通 C#、.sqx / .sqv 模板和组件 <style>：

dotnet watch --project samples/Square.Sample.Vue/Square.Sample.Vue.csproj

模板或组件样式变化时，Square 复用顶层生成组件实例并重建其后代，因此顶层 C# 字段和响应式状态会保留；窗口 Content / 自定义标题栏需要以生成组件作为顶层根。根组件及后代会重新执行 unload/detach/attach/load 生命周期，生命周期代码应支持重复挂载。后代控件的局部状态、焦点、滚动位置和选择区不保证保留。组件或文件重命名、删除成员及部分 ref 结构变化仍可能要求重启。

主示例可选择 CPU Skia 后端：

dotnet run --project samples/Square.Sample/Square.Sample.csproj -- --backend Skia

Windows 主示例也可选择原生 Direct2D HWND 后端：

dotnet run --project samples/Square.Sample/Square.Sample.csproj `
  -p:SquareTargetPlatform=Win32 `
  -p:SquareSampleUseDirect2D=true `
  -- --backend Direct2D

运行 RichText 示例：

dotnet run --project samples/Square.Sample.RichText/Square.Sample.RichText.csproj

运行测试：

dotnet test Square.slnx

Android Experimental

Android 首期使用 .NET 10 for Android、单 Activity 和单 SquareView，通过 ApplicationSession 由 Activity/Looper/Choreographer 驱动。默认路径为 Software BGRA bitmap 到 Android ARGB_8888 bitmap；也可通过 Activity extra 选择 AndroidCanvas、AndroidSkia 或 Vulkan 直绘路径。Android 不引入 MAUI、原生 View/Compose 控件树或桌面窗口操作。

dotnet workload restore Square.Android.slnx
dotnet restore Square.Android.slnx -p:SquareTargetPlatform=Android
dotnet build Square.Android.slnx -c Debug -p:SquareTargetPlatform=Android
dotnet publish samples/Square.Sample.Android/Square.Sample.Android.csproj \
  -c Release -f net10.0-android -r android-arm64 --self-contained false \
  -p:SquareTargetPlatform=Android -p:PublishAot=false -p:TrimMode=full

adb shell am start -n <package>/<activity> --es backend AndroidCanvas
adb shell am start -n <package>/<activity> --es backend AndroidSkia
adb shell am start -n <package>/<activity> --es backend Vulkan

Release 的 x86_64 Android 门禁使用 trimming + profiled Mono AOT：PublishAot=false、RunAOTCompilation=true、AndroidEnableProfiledAot=true。当前 arm64 APK/AAB 产物使用 Release trimming；PublishAot=true 仍会触发官方 XA1040 实验性限制，不作为生产支持声明。

当前 Android 支持等级为 Experimental：代码、x86_64 emulator 的 IME/像素/性能/生命周期/虚拟 accessibility tree smoke、Canvas/Skia/Vulkan 路径以及 APK/AAB 构建已落地；arm64 真机验证、稳定版多设备门禁和官方 NativeAOT 仍未完成。详细边界与验收矩阵见 Android 平台 TODO。

NativeAOT 发布

Hot Reload 仅用于框架依赖运行时的 Debug 构建，不适用于 Release、trimming 或 NativeAOT 发布。

Windows x64：

dotnet publish samples/Square.Sample.Vue/Square.Sample.Vue.csproj \
  -c Release \
  -r win-x64 \
  -p:SquareSamplePublishAot=true \
  --self-contained true

Linux x64 / X11：

dotnet publish samples/Square.Sample.Vue/Square.Sample.Vue.csproj \
  -c Release \
  -r linux-x64 \
  -p:SquareSamplePublishAot=true \
  -p:SquareTargetPlatform=X11 \
  --self-contained true

文档

• 入门指南
• SQV / Vue 模板语法
• SQX 原生语法
• 总体架构
• API 参考
• CSS 规范
• 布局
• 渲染
• DevTools 调试服务
• Web Server 与静态 HTML
• 开发路线

项目状态

Square 适合框架设计验证、实验和贡献开发，暂不建议用于生产项目。

首个版本 0.1.0 已发布，包含 20 个 NuGet 包，入口为核心包与模板包。当前版本为 0.2.0，包含 22 个框架及模板包；源码默认版本与发布标签保持一致。docs/ 文档头部的版本号是各文档的独立修订号，不代表包版本。

贡献流程见 CONTRIBUTING.md。安全问题请按 SECURITY.md 私下报告。

NuGet 发布

NuGet 包 ID 统一为 Wuldas.Square / Wuldas.Square.*，避免与已存在的 Square 支付 SDK 冲突。程序集、C# 命名空间、源码项目名及 dotnet new square 命令不变。

v0.1.0 已通过 CI、Android 和正式发布工作流，并完成全新缓存下从 NuGet.org 安装模板、生成项目和构建验证。以下流程用于后续版本发布。

.github/workflows/publish.yml 使用 NuGet Trusted Publishing，无需长期 API Key。策略 SquarePublish 绑定 wuldas/Square、工作流文件名 publish.yml、包所有者 wuldas，允许发布新包及新版本；Environment 留空。包匹配范围为以下两行：

Wuldas.Square
Wuldas.Square.*

先在 GitHub Actions 手动运行 Publish NuGet，输入版本号。这只构建、验证并上传工作流产物，不向 NuGet.org 发布。本地也可以验证（需要 .NET 10、Android workload 与 JDK 17）：

pwsh -File tools/Pack-Release.ps1 -Version 0.2.0 -OutputDirectory artifacts/packages

输出目录必须为空。脚本打包全部 22 个框架及模板包，检查内部依赖闭环和版本一致性，并让模板中的包引用使用发布版本；不会修改模板源码。正式发布前应确认该提交的 CI 和 Android 工作流通过，并确认账号有权使用所有目标包 ID。

推送 v 开头的版本标签会正式发布。v0.1.0 已存在，不要重建或移动；以下以 0.2.0 演示发布，版本须与手动验证时一致，仅在准备好正式发布时执行：

git tag -a v0.2.0 -m "Release Wuldas.Square 0.2.0"
git push origin v0.2.0

标签去掉 v 后成为统一包版本，也支持 v0.2.0-preview.1。发布任务仅在标签推送时运行，通过 NuGet/login 获取短期凭据后上传 .nupkg 及配套符号包。相同版本已存在时跳过；已发布版本不可覆盖，修复应发布新版本。工作流不会在普通 main 推送或手动验证时发布。

License

MIT