Cloudflare Workers 兼容标志 writable_stream_spec_compliant_writer：WritableStream Writer 规范行为迁移指南
2026/9/18 9:38:05
简介：一份面向HTML5前端教学与自学场景的PDF教案，对应《响应式网页开发实战》第5章，内容围绕Geolocation API与百度地图JavaScript API展开，适合高职院校教师备课、学生实训及自学者快速上手地理定位开发。教案以任务驱动方式组织，包含教学目标、重难点、课时建议、任务描述、知识讲解与实施步骤，完整覆盖getCurrentPosition、watchPosition、位置数据来源、坐标安全处理及百度2D地图调用等知识，并给出配套源代码的实现解析。资源包仅含1个PDF文件，大小239KB，浏览轻便，便于直接打印或导入教学平台。资源目前已有88人学习，内容精炼集中，适合作为课堂教学或课前预习的补充材料。通过两个递进式任务，读者能理解定位流程，并独立实现从获取用户经纬度到在地图上打点标记的完整功能。
1. HTML5定位先过兼容性关，再说接口
在移动端页面里点一次“定位”，浏览器底部弹出授权框，几秒后页面上出现一组经纬度。这个交互看起来简单，背后却是设备传感器、网络定位服务和前端回调三层的衔接。如果只写一个getCurrentPosition调用，很容易在 PC 上看到错误回调，或者在百度地图上发现位置偏移几十米。HTML5 地理定位真正要解决的问题，不只是能不能取到坐标，而是拿到坐标之后能不能在业务页面里可靠地展示。
这个教学案例把定位任务拆成了两半：前半段用 Geolocation API 获取用户当前位置，后半段调用百度地图 JavaScript API 把坐标渲染成地图。这种拆法正好对应响应式网页开发中“数据获取”和“数据可视化”两个环节。适合正在学前端定位知识的人，也适合需要给“响应式网页开发”课程准备代码素材的教师。你要盯住的关键对象是navigator.geolocation和BMap，只要这两个都跑通，整个链路就算掌握了。
2. Geolocation的位置源与getCurrentPosition参数设计
2.1 位置信息数据的三种来源
浏览器不会凭空给出经纬度，它背后会组合多种数据源。最常见的是 GPS、Wi-Fi 定位和基站定位。GPS 依赖卫星信号，在开阔室外精度最高，能达到 10 米以内，但进入室内或被高楼遮挡时信号衰减，定位时间也会拉长；Wi-Fi 定位通过扫描附近无线接入点的 BSSID，再匹配服务端的地理数据库，在室内商场里也能工作，精度在 20 到 80 米左右；基站定位则使用移动通信基站做三角计算，覆盖范围大，但精度往往在 100 米以上。
这三种来源会在底层被浏览器或操作系统融合。实际拿到position.coords时，你很难判断这次结果到底来自哪条链路的权重更高，只能通过position.coords.accuracy粗略估计精度。在做 HTML5 地理定位教学时，我会要求学生先理解这一点：getCurrentPosition只是前端入口，真正的定位工作发生在浏览器之外。这也能解释为什么同一个网页在真机和 PC 模拟器上有时结果完全不同。用下表可以快速看清差异：
| 数据源 | 工作方式 | 典型精度 | 室内表现 |
|---|---|---|---|
| GPS | 卫星信号定位 | 5-20 米 | 基本不可用 |
| Wi-Fi | 扫描接入点匹配地址库 | 20-80 米 | 可用 |
| 蜂窝基站 | 运营商基站三角计算 | 100 米以上 | 可用但误差大 |
因为不同浏览器对数据源的调用策略不同，所以建议在定位按钮旁边展示accuracy字段，让用户直观看到当前环境下的定位质量。在很多移动端页面上，准确度数值能帮助区分“获取成功”和“获取成功但不可用”，后者比失败更隐蔽。
2.2 Geolocation对象在浏览器中的存在形式
navigator.geolocation是 Web 平台提供的对象，但不是所有页面都能用。Chrome、Edge、Firefox 和 Safari 都要求页面运行在安全上下文里，也就是 HTTPS 或本地开发地址http://localhost。把这个限制写进代码前，可以解释一个常见现象：用文件协议直接双击打开 HTML 页面时，控制台里navigator.geolocation显示undefined，根本原因是页面不在安全上下文内。
判断浏览器是否支持定位，最稳妥的写法不是直接判断navigator.geolocation是否存在，而是用in操作符：
if ("geolocation" in navigator) { console.log("当前浏览器支持 HTML5 地理定位"); } else { console.warn("当前浏览器不支持定位，请升级或更换浏览器"); }这个判断放在getLocation()函数的最前面，可以在老浏览器上提前拦截，避免后续调用直接抛TypeError。in操作符判断的是navigator对象的属性是否存在，即使值为null也会被识别，所以比navigator.geolocation !== undefined更可靠。开发响应式网页时，这个兼容性判断可以和按钮状态联动：页面初始化时探测支持性，不支持就把“点我”按钮置灰。
2.3 getCurrentPosition三个参数，各自管什么
getCurrentPosition方法接受三个参数：成功回调、错误回调和定位选项。第一个参数在定位成功时被调用，收到一个Position对象；第二个参数在定位失败时被调用，收到一个PositionError对象；第三个参数是可选的options对象，控制定位行为。很多初学者只传第一个参数，导致定位失败时页面无响应。我一般会建议把三个参数全部写上，哪怕错误回调里只打一句日志，也能让任务具备可诊断性。
第三个参数的常用配置如下：
navigator.geolocation.getCurrentPosition( showPosition, errorPosition, { enableHighAccuracy: true, timeout: 5000, maximumAge: 0 } );enableHighAccuracy为true时，浏览器会优先请求高精度数据，代价是耗电和定位时间变长；timeout以毫秒为单位，表示浏览器等待位置信息的最长时间，超过这个时间就触发错误回调，错误码为 3；maximumAge是允许使用缓存位置的最大时间，设为 0 表示必须重新获取，不要使用旧数据。在课时演示场景里，enableHighAccuracy可以用true，但如果应用场景是电池敏感型设备，建议降回false，让系统自己平衡。
与getCurrentPosition经常一起出现的还有watchPosition，它用于持续跟踪位置变化。两个方法的区别从用途就能判断：一次性定位用getCurrentPosition，连续导航或记录轨迹用watchPosition。
| 方法 | 触发次数 | 典型场景 | 停止方式 |
|---|---|---|---|
| getCurrentPosition | 一次 | 下单时获取当前地址 | 调用完成自动结束 |
| watchPosition | 多次 | 导航、运动轨迹 | clearWatch(watchId) |
注意watchPosition返回一个watchId，必须在页面卸载或用户停止追踪时调用navigator.geolocation.clearWatch(watchId)，否则回调会持续运行，在单页应用里可能造成内存泄漏。作为扩展任务，可以让学生自己写一个watchPosition版本，检验他们是否理解回调函数和资源清理。
2.4 Position对象里除经纬度外的可用字段
成功回调拿到的position并不仅仅是lat和lng那么简单。它包含coords和timestamp两部分，coords下常见的字段有latitude、longitude、accuracy、altitude、altitudeAccuracy、heading和speed。其中heading表示移动方向，speed表示移动速度，移动端定位时这两个字段才有实际意义；桌面浏览器通常只返回经纬度和精度。
timestamp是位置数据的时间戳，可以用来判断数据新鲜度。在业务里如果设置了maximumAge: 0，但回调返回的timestamp与当前时间差仍然很大，说明浏览器可能没有完全按配置执行，这时要主动拦截数据。把accuracy、timestamp输出到控制台，可以在不打断用户操作的情况下快速定位问题。
3. 把“点我”按钮变成可用的定位入口
3.1 在页面结构里预留位置和触发按钮
Task5-1 的页面效果是：用户点击“点我”按钮，页面上出现经度和纬度；获取失败时，弹出具体错误信息。按照任务驱动的方式，先把页面结构写出来，再填逻辑。按钮用onclick触发getLocation()，可以让新手一眼看懂事件入口在哪里。显示经纬度的地方用span，后续通过textContent更新文本，避免使用innerHTML造成潜在的安全风险。
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>HTML5 地理定位：获取用户当前位置</title> </head> <body> <button id="getLocationBtn" onclick="getLocation()">点我</button> <p>经度：<span id="longitude"></span></p> <p>纬度：<span id="latitude"></span></p> <script> // 定位入口 function getLocation() { if (!("geolocation" in navigator)) { alert("当前浏览器不支持定位"); return; } navigator.geolocation.getCurrentPosition(showPosition, errorPosition, { enableHighAccuracy: false, timeout: 5000, maximumAge: 0 }); } // 成功回调：提取经纬度 function showPosition(position) { var lat = position.coords.latitude; var lng = position.coords.longitude; var accuracy = position.coords.accuracy; document.getElementById("latitude").textContent = lat.toFixed(6); document.getElementById("longitude").textContent = lng.toFixed(6); console.log("定位精度：" + accuracy + "米"); } // 错误回调：捕获具体错误 function errorPosition(error) { switch (error.code) { case 1: alert("用户拒绝了位置请求"); break; case 2: alert("暂时拿不到位置信息"); break; case 3: alert("请求位置超时"); break; default: alert("未知错误：" + error.message); } } </script> </body> </html>3.2 用getLocation()判断支持性并发起定位
getLocation()函数承担了两个职责：第一，拦截不支持 Geolocation 的浏览器；第二，在支持的情况下发起定位请求。用in操作符检测到支持后，才调用getCurrentPosition，这样代码后续扩展时，可以在判断分支里加提示信息，比如引导用户升级浏览器或切换到 HTTPS 环境。
提示：用文件协议直接双击打开 HTML 页面，很可能看到定位失败，原因是没有走安全上下文。用本地静态服务器（
python -m http.server 8080或 VS Code Live Server）访问，才能正常触发定位请求。
3.3 showPosition成功回调提取经纬度
成功回调showPosition接收的position对象，核心结构包含coords和timestamp。coords下面的latitude、longitude是当前坐标，accuracy是精度，单位米。这里用toFixed(6)保留 6 位小数，既能让页面显示更整洁，又能避免过长的浮点数字在响应式布局里撑破容器。把accuracy打进日志，是判断定位质量最直接的方法。
在真实项目里，经纬度通常要同时传给后端和地图 SDK，所以showPosition里最好把position.coords整个保存到全局变量，避免重复读取。如果需要在多个模块中使用，还可以把它放进sessionStorage或 Vuex/Pinia 这类状态容器中。教学演示阶段可以只做页面展示，但代码结构要留出扩展空间。
3.4 errorPosition错误回调分离错误码
错误回调里的error.code是一个数值，在 Chrome、Edge 和 Firefox 中代表含义一致：1 代表用户拒绝授权，2 代表位置不可用，3 代表超时。下表可以直接用于教学板书：
| error.code | 常量名 | 含义 | 常见触发场景 |
|---|---|---|---|
| 1 | PERMISSION_DENIED | 用户拒绝授权 | 首次访问点击“禁止” |
| 2 | POSITION_UNAVAILABLE | 无法获取位置 | 室内无 GPS 且 Wi-Fi 地址库缺失 |
| 3 | TIMEOUT | 定位超时 | 设置了 timeout 但未及时返回 |
在演示时，如果用户误点了拒绝授权，第二次点击按钮通常不会再弹出授权框，这时需要引导用户去浏览器设置里重置站点权限。这一条很容易被忽略，但在实际项目中最影响体验。更好的做法是在按钮下方显示错误提示，而不是用alert打断操作。alert适合课堂演示，换成页面内的提示文本后，更接近生产环境中的表单校验交互。
代码里的switch是逐条列出错误码，比统一弹error.message更直观。产品上线后，可以把这些错误码统计上报，比如把1的数量高低作为定位功能转化率的参考。这样原本只用于教学的errorPosition就变成了数据采集点。
4. 用百度地图JavaScript API渲染定位结果
4.1 准备百度地图JavaScript API脚本
获取到经纬度后，下一步是把坐标画到地图上。这是典型的“数据可视化”环节。百度地图 JavaScript API 需要在<head>中引入外部脚本，并携带一个申请好的 AK 密钥。实际教学的Task5-3.html就是先引脚本，再写初始化代码。如果页面脚本加载顺序不对，调用new BMap.Map()时会报BMap is not defined，所以课程里要强调脚本引入位置。
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>调用百度地图显示用户位置</title> <script type="text/javascript" src="https://api.map.baidu.com/api?v=2.0&ak=你的AK"></script> <style> #mapContainer { width: 100%; height: 60vh; } </style> </head> <body> <button onclick="getLocation()">点我定位</button> <div id="mapContainer"></div> <script> // 定位成功后的地图渲染回调 function showPosition(position) { var lat = position.coords.latitude; var lng = position.coords.longitude; var map = new BMap.Map("mapContainer"); var point = new BMap.Point(lng, lat); map.centerAndZoom(point, 15); map.enableScrollWheelZoom(true); var marker = new BMap.Marker(point); map.addOverlay(marker); } function getLocation() { if (!("geolocation" in navigator)) { alert("不支持定位"); return; } navigator.geolocation.getCurrentPosition(showPosition, function (error) { alert("获取位置失败：" + error.message); }); } </script> </body> </html>4.2 创建Map实例并定义中心点
new BMap.Map("mapContainer")必须传入一个已在 DOM 中存在的容器元素 id。地图初始化时容器要有确定的高度，否则页面上只有空白。所以#mapContainer的height不能为 0。在响应式页面中，60vh比固定像素值更抗设备尺寸变化，但也可以配合min-height: 400px做兜底，避免 PC 小窗口下地图被压得太矮。
BMap.Point(lng, lat)接收的第一个参数是经度，第二个是纬度，这个顺序和很多地理坐标习惯相反，地图调试中常见的错误就是把两者写反。接着map.centerAndZoom(point, 15)把地图视野中心对准这个点。缩放级别 15 是城市街道级别，能看到具体街区；如果想看楼块，可以调高到 17 到 18。
4.3 用Marker标记定位点
BMap.Marker(point)生成一个图钉标记，然后通过map.addOverlay(marker)把标记挂到地图上。如果标记不可见，优先检查经纬度顺序和容器高度。map.enableScrollWheelZoom(true)是打开滚轮缩放，不开启的话，PC 用户只能用 Ctrl + 滚轮或按钮控制地图缩放，交互会别扭很多。
在定位场景里，Marker 的图标通常可以换成自定义图标。比如用new BMap.Icon("location.png", new BMap.Size(32, 32))替换默认图钉，更贴合业务需要。教学案例中保留默认图钉即可，主要是演示addOverlay这个挂载动作。
4.4 定位成功后再实例化地图的时序问题
把BMap.Map的创建放在showPosition里，可以避免页面还没加载完就去创建地图。整个流程是：点击按钮 -> 浏览器获取位置 -> 成功回调拿到坐标 -> 地图实例化。这种“后置初始化”的写法，在异步任务里最稳妥。但要注意，如果用户多次点击按钮，会创建多个地图实例，可能造成内存浪费。常见做法是定义全局变量var map = null，在函数里判断是否已经存在。
var map = null; function showPosition(position) { var lat = position.coords.latitude; var lng = position.coords.longitude; if (!map) { map = new BMap.Map("mapContainer"); map.enableScrollWheelZoom(true); } var point = new BMap.Point(lng, lat); map.centerAndZoom(point, 15); map.clearOverlays(); var marker = new BMap.Marker(point); map.addOverlay(marker); }这样的重构更接近真实业务：地图创建一次，定位结果只是更新视图。clearOverlays()的作用是清除上一次添加的标记，防止重复点击时标记叠加，影响阅读。如果业务里同时存在多个标记点，就要用map.removeOverlay(oldMarker)精确移除，而不是一次性清空。
还要提醒一个细节：百度地图 API 默认使用 BD09 坐标系，浏览器 Geolocation 返回的是 WGS84 坐标系。在大多数地区，两种坐标差值有几十米，直接叠加 Marker 会看到图钉落点不在实际位置。原教案里提到“经纬度会加密，位置可能有偏差”，指的就是这种坐标偏移。教学演示可以接受偏差，但在正式产品中需要用转换逻辑处理。
5. 坐标偏差、模拟定位与响应式地图容器调试
5.1 先区分WGS84与BD09坐标
前面提到，浏览器拿到的位置是 WGS84，而百度地图内部用的是加密后的 BD09。处理方式可以放在获取到坐标之后，先用百度地图的坐标转换接口把 WGS84 转成 BD09 再渲染。常用做法是使用BMap.Convertor：
function showPosition(position) { var lng = position.coords.longitude; var lat = position.coords.latitude; var convertor = new BMap.Convertor(); var pointArr = [new BMap.Point(lng, lat)]; convertor.translate(pointArr, 1, 5, function (data) { if (data.status === 0) { var point = data.points[0]; map.centerAndZoom(point, 15); map.addOverlay(new BMap.Marker(point)); } else { console.warn("坐标转换失败，状态码：" + data.status); } }); }这里的1表示 GPS 原始坐标，5表示百度经纬度坐标。回调里的data.points[0]就是转换后的结果。如果你使用的 API 版本回调参数名不同，先打印data看看结构再取值。
5.2 用DevTools模拟经纬度，不用真机外跑
在 PC 上调试定位页面时，可以打开 Chrome DevTools 的命令菜单，按下Cmd + Shift + P（Windows 是Ctrl + Shift + P），输入 “Sensors” 打开传感器面板。在 Latitude 和 Longitude 输入框里填入目标坐标，点击页面里的“点我定位”按钮，浏览器就会用模拟坐标走完整个回调流程。如果找不到面板，请确认页面是通过localhost或 HTTPS 访问的，因为非安全环境下 Chrome 会禁用 Geolocation 模拟。
这个技巧特别适合课堂演示：在教室大屏上模拟一个远程位置的经纬度，不需要带着笔记本跑动，就能验证百度地图的 Marker 和中心点逻辑。也可以在面板中故意填入非法坐标，比如 999，观察错误回调是否触发，用来测试异常分支。
5.3 在响应式容器里让地图撑开不塌陷
百度地图在容器尺寸变化后不会自动重绘，这是响应式页面里常见的地图空白问题。具体表现为：PC 窗口从小拉大时，地图区域出现灰色纹理或空白。解决办法是在容器尺寸变化后调用map.resize()。用ResizeObserver观察地图容器的尺寸变化：
var container = document.getElementById("mapContainer"); if (window.ResizeObserver) { var observer = new ResizeObserver(function () { if (map) { map.resize(); } }); observer.observe(container); }这段代码在页面宽度变化时触发map.resize()，让地图重新计算自身尺寸。移动端地址栏收起和弹出时会改变视口高度，使用60vh高度容器时也会发生尺寸变化，所以这个处理在响应式网页开发里几乎必须写上。
调试时先在控制台执行typeof BMap，如果返回'undefined'，去检查脚本地址里的 AK 是否正确；返回'object'再继续跑定位回调。验证完坐标转换，最后把map.resize()挂到ResizeObserver上，地图掉坑的概率会大大降低。
本文还有配套的精品资源，点击获取