Blazor 路由参数类型约束使用教程

来源：这里教程网时间：2026-02-21 17:40:32 作者：

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 参数必须放在模板末尾，且一个路由只能有一个

基本上就这些。约束不是装饰，它直接影响路由是否生效，写完记得测试各种非法输入——比如故意输个字母进