SuperAPI AI 工具集

views-and-navigation

前端与建站

查看项目

更新于 10-16 06:26

技能介绍

本技能用于指导 Claude 在 Vaadin 25 中创建视图、配置路由布局并实现视图间导航与数据传递。使用时应配合 Vaadin MCP 工具(search_vaadin_docs、get_component_java_api、get_component_styling)查询最新文档,并始终将 vaadin_version 设为 "25"、ui_language 设为 "java"。

【适用范围】本技能覆盖:@Route、路由布局(@Layout、RouterLayout、AppLayout)、导航(RouterLink、UI.navigate())、URL 参数(路由参数、路由模板、查询参数)、@Menu、SideNav、DrawerToggle、嵌套布局(@ParentLayout、@RoutePrefix)以及主从(master-detail)模式。若问题涉及视图内部组件排列(HorizontalLayout、VerticalLayout、FlexLayout、对齐、间距、padding、flex-grow),应改用 vaadin-layouts;若用 React/Hilla 与 TypeScript 构建客户端视图,应改用 client-side-views(本技能仅覆盖 Java/Flow 视图,但说明了如何从 Java 导航到 React 视图);若构建基于 Composite 或 HasValue 的自定义可复用组件,应改用 reusable-components(本技能针对视图即路由目标,而非可复用组件)。

【创建视图】视图是带 @Route 注解并继承 Component 或其子类的 Java 类,注解值为 URL 路径。若省略路径值,Vaadin 会由类名派生:转小写并去掉结尾的 View 后缀;MainView 与 Main 映射到根路径("")。为避免意外,建议显式指定路径。可用 @RouteAlias 为同一视图创建多个路由(必须始终保留一个主 @Route)。用 @PageTitle 设置浏览器标签标题;动态标题可实现 HasDynamicTitle。

【菜单注解】@Menu 将视图注册到应用导航菜单,含三个属性:title(菜单标签,未设置时默认取 @PageTitle)、order(位置,数字越小越靠前,未排序项排在已排序项之后)、icon(图标字符串,由菜单构建代码解释,通常为 Vaadin 图标名)。

【路由布局】多数应用有共享 UI 元素(导航菜单、页眉、页脚),路由布局包裹视图以避免重复。RouterLayout 接口提供 showRouterLayoutContent 与 removeRouterLayoutContent;同一布局内切换视图时会复用现有布局实例。AppLayout 是应用外壳的内置路由布局,提供 navbar(顶栏)、drawer(侧面板)和 content(主区域,由路由器管理)三个内容区,可用 DrawerToggle 作为汉堡菜单按钮。@Layout 注解创建自动应用于所有视图的布局;传入以斜杠开头的路径参数可限定作用范围,多个布局匹配时路径最长者优先;视图可通过 autoLayout = false 退出自动布局。也可用 @Route(layout = ...) 为视图指定布局,同时禁用该视图的自动布局。

【视图间导航】优先使用 RouterLink,它创建 HTML <a> 元素,利于无障碍并允许用户在新标签页打开链接。在事件处理器中不适合用链接时,使用 UI.navigate()。推荐将导航逻辑封装为目标视图上的静态方法(“你自己的 API”模式),提升可读性并便于重构。导航到 React 视图时因无 Java 类,需使用基于字符串的导航。

【视图间传递数据】HasUrlParameter<T> 适合单个参数标识资源的场景,参数默认必填,可用 @OptionalParameter 设为可选,用 @WildcardParameter 捕获剩余整段路径。需要多个命名参数或正则约束时使用路由模板,语法包括 :name(必填,匹配一段)、:name?(可选)、:name?(regex)(可选带正则)、:name(regex)(必填带正则)、:name*(通配,捕获剩余路径,必须置于末尾)。查询参数适合可选筛选、排序或分页等不定义资源的场景,并可在不整页导航的情况下动态更新。

【嵌套布局】布局可嵌套以形成层级结构,用 @ParentLayout 声明父布局,用 @RoutePrefix 添加路径前缀;在 @Route 或 @RoutePrefix 上设置 absolute = true 可忽略父级前缀。

【主从模式】常见做法是左侧列表(Grid)、右侧详情,并将选中项 ID 放入 URL,可结合 SplitLayout、HasUrlParameter<Long> 与 @OptionalParameter 实现。

原文在 master-detail 示例的 showDetail 方法处被截断,未提供后续内容。各类 API 的具体细节、收费、平台与效果等信息,资料中暂未提供。