Flagventures · 腰旗小冒险

给家长和孩子一起使用的腰旗橄榄球教学工具，应用内名称为「Flagventures」。用动画看清每个人的跑位，停在关键帧上讲配合，再带着记住的路线去场上练习。

直接使用

• 在线使用：打开 Flagventures。可以在手机浏览器里「添加到主屏幕」，打开过一次后，在没有网络的球场也能使用。
• 本地使用：下载 Flagventures.html，双击后用浏览器打开。教学内容在文件内，无需安装软件、启动服务或联网。

两个版本均包含 71 个教学条目：原手册 64 条、补充的 In / Square In 路线，以及 6 种组合配合。运行不依赖 PDF 或原页图片。公开仓库和默认应用不包含原页图片。

• 中英文切换：右上角选择中文或 English；界面与全部 71 个内置条目同步切换，保留当前播放状态，并记住语言偏好。
• 层级目录：原手册 64 条保持原有顺序，补充的 In 位于基础路线末尾；基础路线、进攻阵型与战术、跑球战术、防守分工均可展开或收起，切换条目时目录自动滚到当前项。进攻分类内有 10 个阵型组，每组包含阵型站位和战术 1、2、3。
• 组合配合：第五章新增 Slant–Flat、Spacing、Stack 90 Degrees、Flood、Levels、Mesh，分三个层级组；每课含完整五人、四种传球选择与双语讲解。
• 可追溯出处：全部 71 条在标题旁提供原始资料链接和定位，另列教学改编。Flood、Levels、Mesh 可跳转到相近的原书战术并比较差异。
• 转向距离：基础路线从开球线起标注码数，按比例画出转向点，并区分官方示例与本次演示设置；点击标注可暂停讲解。
• 调速与讲解：默认 2× 播放。球场下方的控制栏集中播放、进度（带关键帧刻度）和 0.5×、1×、2×、3× 调速，当前画面讲解紧贴球场；电脑和平板横屏上，球场、讲解与整条控制栏始终在首屏，不用滚动就能点播放；较矮的笔记本（如 1366×768、1280×720）会收紧标题区，长的球路说明先显示一行（点「展开说明」看全），几个球路选项开头相同时只说一次。支持进度拖动、可持续暂停的关键帧和键盘快捷键：空格播放 / 暂停，← → 跳关键帧，[ ] 切换上一条 / 下一条，1–4 调速，0 回到站位，F 全屏。暂停时不占用 CPU。
• 深色模式：跟随手机或电脑的系统设置自动切换，晚上讲解不刺眼；打印讲义始终是浅色。
• 全屏观看：球场右上角的「全屏」让球场、讲解和控制栏占满屏幕，手机横屏或投到电视上讲解时更清楚；球场显示得较小或手机横屏放不下整块球场时，按钮会变成「全屏看大图」。
• 手机上随手播放：手机上的播放按钮在第一屏下方时，底部会浮出同样的播放按钮，点一下就滚到球场并开始演示；手机横着拿时直接进入全屏演示。
• 手机与平板：目录收进左上角菜单，球场占满屏宽，球员和标注按屏幕放大，关注球员的字母按钮就在球场上方。
• 可分享链接：地址栏记住当前条目（例如 #lesson=cover-2），刷新、收藏或发给家人后直接回到这一条；标签页标题显示条目名称，浏览器返回键回到上一条。标题旁的 ‹ › 可直接切换条目。
• 打印讲义：点标题旁的「打印讲义」，把当前画面、全部关键帧讲解和提问打印成一页，带去场上练习。
• 认识跑法：11 条基础路线默认放大到路线、开球线与 QB 站位参照，点「看全场」可看完整球场；配有常驻文字讲解，说明怎么跑、内外方向和相似路线的区别。悬停球员查看中英文名称，点击保留关注；支持键盘操作。
• 看懂配合：36 套进攻战术补充全队目标、配合说明、记忆口令和提问；球员说明包含队友配合与启动时机，并可查看官网、视频出处。
• 看球去哪里：36 套进攻战术各有 C / X / Y / Z 四种传球示例，可在页面切换；9 套跑球有 14 种交接、假动作和跑传情形。球路、小球和持球提示与跑位同步；点击场内动作标记或事件关键帧，可以跳到对应动作并暂停讲解。
• 教练画板：在「我的战术」空白新建或复制内置内容，直接在一张球场上编辑：点选后拖动摆人，长按球员画线或套跑法，点路线加讲解停点，随时播放和保存。支持进攻、跑球、基础路线、阵型和五人防守。
• 途中出手：长按持球者的跑动路线，选「从这里传球」再点接球人。支持 QB 交递给 Z 后由 Z 接着传球；拖动菱形调整出手位置，接球位置随队友跑动计算。可保留多个互斥接球选择；编号圆点仍只用于讲解。
• 本机战术库：在线／本地服务版自动保留草稿；手动保存更新教学版，不再保留版本历史。支持完整备份、逐条处理导入冲突、10 秒删除撤销；单文件版为临时编辑，请导出备份。
• 移动编辑：没有常驻属性表或绘图工具条；拖出路线后松开完成，说明按需打开小浮层。支持双指缩放／移动，电脑可右键打开对象菜单。真实手机／平板核心流程验收仍需单独完成，尺寸检查不等同于真机验收。

使用与保存方式见 中文使用说明。

编辑教学内容

每条战术独立保存在 content/lessons/，顺序由 content/catalog.yaml 管理。维护内置内容可参考 YAML 模板；日常自编使用网页画板。网页只导入 v3 完整编辑备份，不支持旧备份、YAML／战术包。新版画板首次打开会清空旧版教练战术库。

• 内容维护说明
• 内置手册维护格式
• 画板完整备份 v3

动画秒数是教学示意。NFL FLAG 官网与视频明确说明的相对先后、短暂等待和条件释放，分别写入对应进攻战术；条件释放需先选择教学情形再播放。资料未说明的启动先后、球权与跟防不会自动补造。每名球员的术语说明区分来源命名、形态对照与按图描述。

球路情形由独立文本明确编排并标注为教学选择，不代表原书唯一传法；交接双方在同一时刻到达会合点。关闭“显示球路”可恢复原图跑位。QB OPTION 的教学变式由 Y 接开球，Q 接 Y 的交接后再跑或传，界面会说明本次角色；不演示初始接开球者直接持球冲线。

图例采用球员色实线箭头表示人跑、橙色虚线箭头表示球飞；真交递在会合点标 ○＋交递 / HANDOFF，假交标 假交 / FAKE，球仍由原持球人持有；假传 / PUMP FAKE 标在出球人开始假动作的位置，球仍在其手里。持球跑继续显示球图标与白色已跑轨迹。场内标记随播放和进度跳转更新：未来事件显示为待演示，当前事件强调，过去事件保留作对照。这是本应用的教学约定，不是全行业强制标准。

开发

需要 Node.js 22 或更新版本：

npm ci
npm test
npm run build

测试和构建前会自动从 YAML 与目录生成完整内容包，无需原始 PDF 或原页图片。生成的内容包与预览副本不纳入版本控制；仓库保留可直接打开的主 HTML。

开发验收使用内置浏览器。可选的 npm run test:browser 使用单独安装的 Playwright Chromium，不使用个人 Chrome；首次使用需安装该运行时。仓库原有的 Firefox／WebKit 自动检查仍可单独运行。尺寸／鼠标检查不能代替真机双指和软键盘验收。

每个 PR 和推送到 main 都会运行测试工作流：单元测试、构建、检查 dist/Flagventures.html 已随源码重新构建，全部浏览器测试，以及 Firefox 和 WebKit 冒烟测试。修改 app/ 或 content/ 后记得运行 npm run build 并提交 dist/Flagventures.html。修改源码后先运行 npm run build。

推送到 main 后，发布工作流会自动运行测试、构建并部署到 GitHub Pages。仓库的 Settings → Pages → Build and deployment → Source 应选择 GitHub Actions。

目录	用途
app/	页面（main.js 状态与面板、field.js 球场绘制、catalog.js 目录、navigation.js 链接与快捷键）、场景计算与内容校验
content/	71 条 YAML 与目录
content-format/	格式定义、模板与示例
tools/	内容打包、单文件网页构建，以及应用图标生成（make-icons.mjs）
tests/	内容、场景、导入与浏览器测试
dist/	可直接使用的主 HTML 与开源许可