practical-aspnetcore 实战:在 Hydro 组件中读写删除 Cookie、全局事件与页面刷新导航

原创2026-10-14 13:41:411,923 阅读
文章标签:示例工程

practical-aspnetcore 实战:在 Hydro 组件中读写删除 Cookie、全局事件与页面刷新导航

本文以 practical-aspnetcore 仓库中 projects/hydro/cookies 示例为核心,系统讲解如何在 Hydro 组件中通过 CookieStorage 设置、读取和删除浏览器 Cookie,如何借助 Hydro 的全局事件(Global Dispatch)在多个组件间广播消息,以及如何通过 Redirect 触发带页面刷新的重定向导航。读完本文,你将掌握 Hydro 组件中 Cookie 操作、事件订阅与导航跳转的一整套可复用的实战写法,并了解这些机制在 Hydro 框架 各示例中的一致用法。

示例概览:这个项目演示了什么

原文档对示例的定位非常清晰:从 Hydro 组件中设置和删除 Cookie,同时使用 Hydro 全局 dispatch 事件展示消息,并执行带页面刷新的重定向导航。整个示例由两个 Hydro 组件和一个事件类构成,对应 Pages/Components 目录下的四个文件:

文件 职责
CookieControl.cshtml + CookieControl.cshtml.cs 根据 Cookie 是否存在渲染「Set New Cookie / Remove Cookie」按钮,执行写入、删除与导航
Message.cshtml + Message.cshtml.cs 订阅全局事件,展示事件消息或当前 Cookie 值
MessageUpdatedEvent.cs 定义全局事件载荷(一条消息文本)

组件在页面中的挂载位置见 Pages/Index.cshtml:一个 <message> 组件负责展示信息,一个 <cookie-control> 组件负责交互操作。两个组件彼此独立,靠全局事件完成解耦通信。

运行前提与工程配置

示例基于 .NET 10.0 构建,工程文件 cookies.csproj 中 TargetFramework 为 net10.0,LangVersion 为 preview,唯一的外部依赖是 Hydro 1.3.0。仓库根目录的 global.json 指定 SDK 版本为 10.0.0 并开启 rollForward: major,因此只要本机安装了匹配的 .NET SDK,即可直接运行:

cd projects/hydro/cookies
dotnet run

启动后访问首页(/),你会看到当前未设置 Cookie 时展示的提示文本,以及「Set New Cookie」按钮。

Hydro 的启用集中在 Program.cs,与 hello-world 等其他 Hydro 示例完全一致,是标准的五步管线:

using Hydro.Configuration;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddHydro(); // Hydro 服务注册

var app = builder.Build();

app.UseStaticFiles();
app.UseRouting();
app.MapRazorPages();
app.UseHydro(); // Hydro 中间件

app.Run();

组件标签之所以能直接以 <message>、<cookie-control> 形式出现在 Razor 页面中,依赖 _ViewImports.cshtml 里的 TagHelper 声明:

@addTagHelper *, Hydro
@addTagHelper *, Cookies
@using Cookies.Pages.Components

而 _Layout.cshtml 中引用了 Hydro 的前端运行时脚本,并带上了 hydro-config 元标记:

<meta name="hydro-config" />
<script defer src="~/hydro/hydro.js" asp-append-version="true"></script>
<script defer src="~/hydro/alpine.js" asp-append-version="true"></script>

这些是 Hydro 组件在浏览器端完成局部渲染更新的必要前提。

在组件中读写与删除 Cookie:CookieStorage

CookieStorage 是 Hydro 提供给组件的 Cookie 访问入口,封装了对浏览器 Cookie 的读取、写入与删除操作。示例在 CookieControl.cshtml.cs 中完整演示了三种操作:

public void SetCookie()
{
    CookieStorage.Set("date", DateTime.Now.ToString());
    Dispatch(new MessageUpdatedEvent("A cookie is now set"), scope: Scope.Global);
    Redirect(Url.Page("/Index"));
}

public void RemoveCookie()
{
    CookieStorage.Delete("date");
    Dispatch(new MessageUpdatedEvent("Cookie removed"), scope: Scope.Global);
    Redirect(Url.Page("/Index"));
}

三个 API 的语义非常直观:

  • CookieStorage.Set("date", value):写入名为 date 的 Cookie,值为当前时间字符串;
  • CookieStorage.Get<string>("date"):按泛型类型读取 Cookie 值,示例中用于读取已存储的时间文本;
  • CookieStorage.Delete("date"):删除名为 date 的 Cookie。

用 Mount 生命周期决定按钮状态

组件并非无条件渲染同一个按钮,而是依据 Cookie 是否存在动态切换。这一判断放在 Mount 生命周期钩子中——它是组件被实例化到页面时回调的初始化方法:

public override void Mount()
{
    var msg = CookieStorage.Get<string>("date");
    ShowSetCookies = string.IsNullOrWhiteSpace(msg);
}

ShowSetCookies 是组件的公开状态属性,模板 CookieControl.cshtml 据此分支渲染:

@if(Model.ShowSetCookies){
    <button class="btn btn-primary" on:click="@(() => Model.SetCookie())">Set New Cookie</button>
}else{
    <button class="btn btn-primary" on:click="@(() => Model.RemoveCookie())">Remove Cookie</button>
}
  • 尚未设置 Cookie(读取为空)时,显示「Set New Cookie」;
  • 已存在 Cookie 时,显示「Remove Cookie」。

按钮通过 on:click 指令绑定组件方法,点击后由 Hydro 在服务端执行对应方法,并自动完成局部刷新。从源码结构看,Mount 在这里承担了「服务端渲染时读取 Cookie 决定初始 UI」的角色,与 hello-world 等基础示例中组件属性随方法调用更新的模式一致。

全局事件:Dispatch + Subscribe 解耦组件通信

设置或删除 Cookie 后,示例并没有让 CookieControl 直接修改 Message 组件的文本,而是通过全局事件广播通知,由订阅方自行响应。这是 Hydro 组件间通信的标准模式,也是本示例的核心看点之一。

定义事件载荷

事件本身是一个简单的 record 类型,携带一条消息文本(见 MessageUpdatedEvent.cs):

public record MessageUpdatedEvent(string Message);

发布方:指定 Global 作用域

发布方在 SetCookie / RemoveCookie 方法内调用 Dispatch,并显式传入 scope: Scope.Global:

Dispatch(new MessageUpdatedEvent("A cookie is now set"), scope: Scope.Global);
Dispatch(new MessageUpdatedEvent("Cookie removed"), scope: Scope.Global);

Scope.Global 表示事件将广播给所有订阅了该事件类型的组件,而不限于父子关系或当前组件树。

订阅方:构造函数中 Subscribe

Message 组件在构造函数中完成订阅,把事件载荷写入自己的展示属性(见 Message.cshtml.cs):

public Message()
{
    Subscribe<MessageUpdatedEvent>(data => Text = data.Message);
}

public override void Mount()
{
    var msg = CookieStorage.Get<string>("date");

    if (!string.IsNullOrWhiteSpace(msg))
        Text = msg;
    else
        Text = "No cookies set";
}

Subscribe<MessageUpdatedEvent> 是泛型订阅 API:只要全局事件被派发,回调就会执行,data.Message 即事件中携带的文本。模板 Message.cshtml 最终把 Model.Text 渲染为标题:

<h1>@Model.Text</h1>

与同系列示例的印证

这种「构造函数 Subscribe<T> + 事件方法 Dispatch」的模式在 event-global 示例中体现得更为纯粹:MessageButton 通过 DispatchGlobal(new MessageChangedEvent(text)) 发布事件,页面上的两个 <message> 组件都订阅了 MessageChangedEvent 并同时更新文本(参见 MessageButton.cshtml.cs、Message.cshtml.cs 与 Index.cshtml)。cookies 示例使用 Dispatch(..., scope: Scope.Global) 的写法与 DispatchGlobal 是同一机制的不同调用形态。此外,hydro 根 README 还展示了带 subject 过滤的全局事件(event-global-subject)与子组件向父组件派发事件(event-child-parent)两种进阶场景,说明事件机制是 Hydro 组件通信的主干。

带页面刷新的重定向导航:Redirect + Url.Page

写入或删除 Cookie 之后,示例执行了页面跳转:

Redirect(Url.Page("/Index")); // Url.Page 是生成 Razor 页面 URL 的辅助方法,起始于 /Pages 目录

这里的要点有两层:

  1. Url.Page("/Index"):Url.Page 是 ASP.NET Core 为 Razor Pages 提供的 URL 生成辅助方法,路径从 /Pages 目录开始解析。在本项目中即指向 Pages/Index.cshtml(@page "/")。使用它而不是硬编码字符串,可以保证路由与页面的对应关系始终准确。
  2. Redirect:Hydro 组件方法内调用 Redirect 会触发一次真实的页面导航(伴随浏览器整页刷新),而不是仅做组件局部重渲染。这正是原文档强调的「perform redirect navigation with page reload」——刷新后 Message 组件重新执行 Mount,从 CookieStorage 读回新写入的 Cookie 值并展示,从而让「设置/删除 Cookie → 全局事件提示 → 刷新回读验证」的完整闭环可见。

完整的运行闭环与验证路径

把上面所有机制串起来,一次「设置 Cookie」操作的实际流程是:

  1. 用户点击「Set New Cookie」,Hydro 服务端执行 CookieControl.SetCookie();
  2. CookieStorage.Set("date", ...) 写入浏览器 Cookie;
  3. Dispatch(new MessageUpdatedEvent("A cookie is now set"), scope: Scope.Global) 广播全局事件,Message 组件订阅回调把页面标题更新为提示文本;
  4. Redirect(Url.Page("/Index")) 触发带刷新的整页导航;
  5. 页面重新加载,CookieControl.Mount() 读回 Cookie,发现已存在,按钮切换为「Remove Cookie」;Message.Mount() 同步读回 Cookie 值并显示在标题中。

删除 Cookie 的流程完全对称,仅把 Set 换成 Delete,事件文本换成「Cookie removed」。整个示例在 Pages/Components 目录下不足百行代码,却完整覆盖了 Hydro 组件三大核心能力——Cookie 存储访问、全局事件通信、服务端导航。

实战注意事项

结合本示例与同目录其他 Hydro 项目(如 event-global 和 event-child-parent)的文档说明,有几个容易被忽略的细节值得注意:

  • 组件根标签要用容器包裹:如果组件的根节点直接是 <button>,点击后该按钮可能在重渲染时消失;应像本示例那样以容器标签(div 等)作为根元素,或在事件组件外层套一层 div。
  • CookieStorage.Get<T> 需要指定泛型类型:读取时使用 Get<string>("date") 显式声明期望的返回类型,便于 Hydro 正确反序列化 Cookie 值。
  • 全局事件的成本与语义:Scope.Global 意味着所有订阅该事件的组件都会响应,适合「一处发布、多处消费」的场景;如果只需要通知单个父子链路上的组件,应优先考虑组件树内的事件,避免不必要的广播面。
  • Url.Page 的路径基准:它解析的是 /Pages 目录下的 Razor 页面,传入参数应与页面 @page 路由保持一致,否则会生成无效 URL。

小结

通过 projects/hydro/cookies 这个短小精悍的示例,可以同时掌握 Hydro 框架的三种高频能力:用 CookieStorage.Set/Get/Delete 完成 Cookie 的读写删除与生命周期状态判断;用 Dispatch(..., scope: Scope.Global) 与 Subscribe<T> 实现组件间的全局解耦通信;用 Redirect(Url.Page(...)) 触发带页面刷新的导航。这些模式在 projects/hydro 系列示例(hello-world、event-global、component-1 至 component-3)中反复出现,是构建可交互 ASP.NET Core 页面时最值得先掌握的 Hydro 基础能力。

登录后查看全文
practical-aspnetcore