网页环境接口规范 0.1.0
本包提供浏览器页面所处环境的两项只读事实:本地时区偏移与当前页面可见的饼(cookie)。前者让豫言应用能把 Unix 毫秒换算成用户本地时间并按自己的格式显示(豫言标准库没有时区数据);后者用来读取语言偏好之类由页面其他部分写下的小值。本包全部只读,不设置饼、不改时区。应用依赖本包后,全部函数都必须实现。
函数
读取本地时区偏移分钟 : 整数 → 整数
参数是 Unix 毫秒(自 1970-01-01T00:00:00Z 起,可为负)。返回浏览器所在时区在该时刻相对 UTC 的偏移分钟数,东为正、西为负:北京时间(1992 年起)恒为 480,日本 540,美国东部冬令时 −300、夏令时 −240,印度 330。按该时刻当地的夏令时与历史规则计算;历史上不是整分钟的偏移(如 1900 年前的某些城市)四舍五入为整分钟。毫秒的绝对值超过 8640000000000000 时抛事故。
本地时间 = Unix 毫秒 + 偏移分钟 × 60000,再按 UTC 历法拆成年月日时分秒即可,星期、月份名与格式由应用自定。(注意:这与 JavaScript getTimezoneOffset() 符号相反。)
读取页面饼 : 字符串 → (爻 合 字符串)
读取当前页面可见的饼里指定名称的值:名称须完全相同(区分大小写)。存在时返回(阳,值),值原样返回,宿主不做 URL 解码;不存在、浏览器禁用饼,或该饼带 HttpOnly(脚本不可见)时返回(阴,空字符串)。名称为空、超过 256 个 UTF-16 码元,或含 =、;、空白、控制字符时抛事故。同名的饼有多个(不同路径)时,取浏览器给出的第一个。
一致性样例
- 在东八区,
读取本地时区偏移分钟(0)为 480;在美国东部,2026-01-01 的毫秒得 −300,2026-07-01 的毫秒得 −240。 - 页面饼
yuyan_lang=wen; 别的=x:读取页面饼("yuyan_lang")为(阳,“wen”);读取页面饼("yuyan")为(阴,“”);读取页面饼("别的")为(阳,“x”)。 - 饼值为
a%20b时返回(阳,“a%20b”),不解码。 读取页面饼("a b")、读取页面饼(""):抛事故。
边界
本包不规定:写饼与删饼、document.cookie 的属性、第三方饼、时区名称与区域设置(Intl)、navigator.language。日期格式化、星期与月份名属应用库。