Blazor路由参数类型约束可提前拦截非法URL,避免运行时异常;需在@page中声明约束(如{id:int}),组件参数类型必须严格匹配,支持基础类型、函数约束、可选参数及通配符捕获。

Blazor 路由参数类型约束能帮你提前拦截非法 URL,避免运行时类型转换失败或逻辑异常。关键在于:约束写在 @page 模板里,而组件参数类型必须严格匹配约束要求。
基础类型约束(如 int、bool、guid)
直接在路由占位符后加冒号和类型名,例如 {id:int}。框架会自动尝试将 URL 中的字符串转为对应类型,失败则不匹配该路由(跳转到 NotFound 页面)。
-
@page "/product/{id:int}"要求 URL 必须是/product/123这类整数结尾,/product/abc或/product/12.5都不会命中 - 组件中对应参数必须声明为
public int Id { get; set; },不能是string或可空int?(除非你用可选参数 + 默认值逻辑) - 常见支持类型包括:
int、long、bool、datetime、guid、float、double
函数约束(如 max、min、regex)
函数约束只接受 string 类型的参数,框架不会自动转换。它是在字符串层面做验证,不是类型转换。
- 写法示例:
@page "/user/{name:regex(^[a-zA-Z]{2,20}$)}",限制 name 只能是 2–20 个英文字母 - 数值范围约束如
{id:max(100)},实际接收的是string,但值必须能解析为 ≤100 的整数(否则不匹配) - 组件属性必须是
public string Name { get; set; },否则编译或运行时会出错 - 多个约束可叠加,比如
{id:int:min(1):max(999)},但注意int是类型约束,min/max是函数约束,顺序不影响效果
可选参数与默认值处理
在参数名后加问号 ? 表示可选,URL 中可以省略该段。但组件仍需提供合理默认值,否则可能为 null 或 0。
- 写法:
@page "/profile/{username?}",允许访问/profile或/profile/john - 参数属性建议设为可空或带默认值,例如
public string Username { get; set; } = "guest"; - 推荐在
OnParametersSet中设置默认值,因为该方法每次参数变化都会触发,比OnInitialized更可靠
通配符捕获(catch-all)
用 {*path} 捕获 URL 剩余全部路径段,适合构建动态嵌套路由或代理页面。
- 写法:
@page "/docs/{*slug}",可匹配/docs/intro、/docs/api/v1/users/list等任意深度 - 对应参数必须是
string类型,且允许为null,例如public string? Slug { get; set; } - 注意:catch-all 参数必须放在模板末尾,且一个路由只能有一个
基本上就这些。约束不是装饰,它直接影响路由是否生效,写完记得测试各种非法输入——比如故意输个字母进 {id:int},看是不是真跳 404。











