open-code-review：基于Git Diff与Embedding的开放代码审阅协议
2026/9/19 6:36:00
如何10分钟上手app-router：Polymer单页应用的路由快速入门
【免费下载链接】app-routerRouter for Web Components项目地址: https://gitcode.com/gh_mirrors/ap/app-router
app-router 是一款专为 Web Components 打造的轻量级路由库，与 Polymer 框架深度配合，帮你轻松搞定单页应用（SPA）最头疼的页面跳转问题。只需 10 分钟，你就能掌握 app-router 的安装、路由配置、参数绑定和页面动画等全部核心能力。
为什么需要 app-router？单页应用的路由痛点 🤔
传统多页应用每次切换页面都要刷新整个文档，用户体验割裂。单页应用虽然解决了刷新问题，但也带来新的挑战：
- URL 与页面对应关系：如何让
/order/123这样的地址自动渲染对应页面？ - 内容按需加载：页面资源能否只在访问时才加载，加快首屏速度？
- 参数传递：路径变量和查询参数如何自动传给页面组件？
- 优雅的体验：前进后退能不能正常工作？页面切换能否有动画过渡？
app-router 用一个<app-router>元素就全部解决。它声明式地管理页面状态，支持懒加载内容、路径变量与查询参数的自动数据绑定、多布局，并通过hashchange和 HTML5pushState两种方式导航，还能配合core-animated-pages实现平滑的页面过渡动画。
💡 app-router 不只限于 Polymer，它也兼容 X-Tag 和原生 Web Components，详见 bower.json 中的关键词定义。
第一步：安装 app-router（1分钟）
app-router 通过 bower 分发，在项目根目录执行一条命令即可完成安装：
bower install app-router --save如果想把源码拉到本地研究或二次开发，可以直接克隆仓库：
git clone https://gitcode.com/gh_mirrors/ap/app-router第二步：定义路由，URL 映射到页面（核心 5 分钟）
app-router 的核心思路是"声明式配置"：在 HTML 里放一个<app-router>，里面用<app-route>描述每个 URL 应该加载什么。
先在<head>中引入路由库，再在页面中声明路由表：
<head> <link rel="import" href="/bower_components/app-router/app-router.html"> </head> <body> <app-router> <!-- 精确匹配路径 --> <app-route path="/home" import="/pages/home-page.html"></app-route> <!-- 通配符匹配 --> <app-route path="/customer/*" import="/pages/customer-page.html"></app-route> <!-- 路径变量 --> <app-route path="/order/:id" import="/pages/order-page.html"></app-route> <!-- 正则匹配，如 /word/number --> <app-route path="/^\/\w+\/\d+$/i" regex import="/pages/regex-page.html"></app-route> <!-- 兜底：其他都走 404 页 --> <app-route path="*" import="/pages/not-found-page.html"></app-route> </app-router> </body>五种路由匹配方式一览表
| 写法 | 说明 | 示例 |
|---|---|---|
| 精确路径 | 完全一致才匹配 | /home |
通配符* | 匹配该位置任意内容 | /customer/* |
路径变量:name | 命名占位符，可自动绑定 | /order/:id |
正则regex | 按 JS 正则匹配 | /^\/\w+\/\d+$/i |
兜底* | 匹配所有未命中的路径 | * |
完整的路由匹配逻辑可以在 src/app-router.js 中查看，testRoute()函数正是负责逐个判断 URL 是否命中某条路由。
页面内容的四种加载方式
<app-route>不只支持import一个属性，按灵活度从低到高还有：
- 懒加载自定义元素：
import="/pages/customer-page.html"，仅在访问时才加载该 HTML import，天然实现按需加载； - 已打包的元素：用
element="customer-page"直接使用预先加载好的组件，适合用 vulcanize 打包后的场景； - 导入模板：加
template属性加载<template>，而非完整元素； - 内联模板：直接把
<template>写在<app-route>内部，连文件都不用。
项目自带的功能测试页 tests/functional-tests/test-main-features.html 把这四种方式全部演示了一遍，是最值得研读的示例。
第三步：实现页面导航的三种方式
路由定义好后，如何让页面跳转？app-router 同时监听popstate和hashchange事件，改变 URL 就会自动找到第一条匹配的路由并替换当前视图。
方式一：hashchange 导航（最简单）
<a href="#/home">首页</a>点击后触发hashchange事件，路由库会自动处理——#/home会匹配到path="/home"的路由，你无需写任何监听代码。
方式二：HTML5 pushState 导航（URL 更干净）
借助pushstate-anchor等扩展，把普通<a>升级为 pushState 链接：
<a is="pushstate-anchor" href="/home">首页</a>这种方式会调用pushState()并派发popstate事件，浏览器地址栏保持干净的无哈希地址。
方式三：JavaScript 命令式跳转
在代码中直接调用路由器的go()方法：
document.querySelector('app-router').go('/home'); // 或替换历史记录而非新增 document.querySelector('app-router').go('/home', {replace: true});go()的实现位于 src/app-router.js，它会写入历史记录并手动派发popstate事件，保证前进后退行为一致。
⚠️ 使用
go()或重定向时，记得给<app-router>指定mode="hash"或mode="pushstate"，否则默认auto模式下会使用哈希路径。
附赠：路由重定向
某条路由可以只负责"指路"：
<app-router mode="pushstate"> <app-route path="/home" import="/pages/home-page.html"></app-route> <app-route path="*" redirect="/home"></app-route> </app-router>第四步：路径变量与查询参数的自动数据绑定 ✨
这是 app-router 最省心的特性——URL 里的参数会自动绑定到页面元素属性上，无需手动解析：
<!-- 链接 --> <a is="pushstate-anchor" href="/order/123?sort=ascending">订单 123</a> <!-- 路由 --> <app-route path="/order/:orderId" import="/pages/order-page.html"></app-route> <!-- 渲染出的元素自动带上参数 --> <order-page orderId="123" sort="ascending"></order-page>123自动绑到orderId属性，ascending自动绑到sort属性。如果你在用 Polymer，还可以直接把变量绑进模板：
<app-route path="/order/:orderId"> <template> <p>您的订单号是 {{orderId}}</p> </template> </app-route>解析逻辑见 src/app-router.js 中的routeArguments()与typecast()——数字和布尔值还会被自动转换类型，typecast="string"可保留原始字符串。
进阶技巧：为页面切换加上动画 🎬
给<app-router>加一个core-animated-pages属性，即可让路由切换接入core-animated-pages组件的过渡动画：
<app-router core-animated-pages transitions="hero-transition cross-fade"> <!-- app-routes --> </app-router>然后在希望参与动画的元素上加hero、cross-fade等属性即可。动画期间旧页面不会立即销毁，过渡结束后才清理，效果非常顺滑。相关测试用例见 tests/functional-tests/test-core-animated-pages.html。
常用配置选项速查表
| 属性 | 位置 | 作用 |
|---|---|---|
mode | <app-router> | auto/hash/pushstate/hashbang，强制指定导航模式 |
trailingSlash | <app-router> | 设为ignore后/home与/home/视为同一路由 |
typecast | <app-router> | auto（默认，自动转数字/布尔）或string（保留原始字符串） |
import | <app-route> | 懒加载自定义元素或模板文件 |
element | <app-route> | 使用已加载的元素名，或指定元素名与文件名不一致时的名称 |
template | <app-route> | 加载<template>而非元素，可指定模板 ID |
regex | <app-route> | 按正则匹配路径 |
redirect | <app-route> | 重定向到另一个路径 |
onUrlChange | <app-route> | reload/updateModel/noop，嵌套路由时只更新最内层 |
更多细节可翻阅 changelog.md 了解各版本新增能力，例如 v2.6.0 引入的模板打包与async异步加载、v2.4.0 的**多段通配符等。
构建、测试与调试指南
源码位于src/目录，构建产物写入根目录。调试时建议直接引入未压缩的源码文件，而不是根目录的构建版本：
<script src="/bower_components/app-router/src/app-router.js"></script>完整构建流程（对应 gulpfile.js）：
- 执行
bower install和npm install安装开发依赖； - 运行
gulp一键完成 Lint、测试、构建与压缩； - 功能测试：启动任意静态服务器（如
python -m SimpleHTTPServer），打开 tests/functional-tests/ 下的页面手动验证。
单元测试基于 Jasmine，配置见 tests/karma.conf.js，测试用例入口为 tests/spec/routerSpec.js。
写在最后：10 分钟复盘 🎯
回顾一下你刚掌握的内容：
- 一条命令
bower install app-router --save完成安装； - 一个标签
<app-router>加上若干<app-route>声明全部路由； - 三种导航：哈希链接、pushState 链接、
go()命令式跳转； - 自动绑定：路径变量和查询参数无需解析直接进组件；
- 可选动画：一行
core-animated-pages属性获得平滑过渡。
app-router 用不到 4KB 的压缩代码，换来了声明式路由 + 懒加载 + 数据绑定 + 动画的完整 SPA 路由体验。对正在用 Polymer 或 Web Components 开发的朋友来说，这是上手成本最低的选择之一。现在就把它加入你的项目，让页面切换丝般顺滑吧！
📁 延伸阅读：完整官方说明见 README.md，CSP 兼容版本入口见 app-router.csp.html。
【免费下载链接】app-routerRouter for Web Components项目地址: https://gitcode.com/gh_mirrors/ap/app-router
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考