读写当前网页来源的会话储存与本地储存中的键值文字，写入失败以返回值表示。
源码浏览已生成；不能解析的文件以纯文本展示，不表示通过类型检查。
# 网页储存接口规范 0.1.0
本包让浏览器里的豫言应用读写当前网页**来源**（协议、主机、端口）下的键值文字，用于未发送的草稿、界面偏好、展开状态之类只需在本机保存的小数据。它是浏览器 `sessionStorage` 与 `localStorage` 的最小公共子集：只有读、写、删三个函数；**写入失败是可恢复情形，以返回值表示，不抛事故**。应用依赖本包后，全部函数都必须实现。
## 区域
`区域` 参数只接受两个固定值：
| 区域 | 对应 | 生命周期 |
| --- | --- | --- |
| `会话` | `sessionStorage` | 当前标签页（含刷新）；标签页关闭即清除 |
| `本地` | `localStorage` | 持久，同来源的所有标签页共享 |
区域名不是这两个值之一时抛事故。
## 函数
### `读取网页储存 : 字符串(区域) → 字符串(键) → （爻 合 字符串）`
键存在时返回（阳，值）；键不存在，或浏览器禁用了储存（隐私模式、被用户或策略封锁）时返回（阴，空字符串）。要区分“键不存在”与“值是空字符串”，看元组的第一项：值是空字符串时返回（阳，空字符串）。
### `写入网页储存 : 字符串(区域) → 字符串(键) → 字符串(值) → 爻`
成功返回阳。**配额已满、储存被禁用、隐私模式的零配额**等运行时失败返回阴，且不改变原有内容；应用应提示用户（例如“草稿未能保留”）。区域无效、键为空或超长、值超过限额属于违规调用，抛事故。
### `删除网页储存 : 字符串(区域) → 字符串(键) → 有`
删除键；键不存在或储存不可用时什么也不做。
## 键与值
- 键**原样使用，宿主不加前缀**。同来源的不同应用共用同一个键空间，应用自己用带项目名的键（例如 `yy-cloud-draft:账户:项目:ai`）避免冲突；这也使从旧 JS 前端迁来的既有键值继续有效。
- 键至多 512 个 UTF-16 码元，不得为空；值至多 1048576 个 UTF-16 码元（1 Mi 码元），可以为空字符串。
- 值是任意豫言字符串（含 JSON 文字）。含孤立代理项（不能编码为合法 UTF-8 的字符串）不会出现，因为豫言字符串本身是合法 Unicode。
## 与网页事件的关系
本包不产生事件。其他标签页对同一 `localStorage` 的修改（`storage` 事件）本版不提供，应用需要跨标签页同步时应自己轮询或使用后续的广播包。
## 失败分类
| 情形 | 表现 |
| --- | --- |
| 区域名无效；键为空或超过 512 码元；值超过限额 | 抛豫言事故（违规调用，中文消息） |
| 配额已满、储存被禁用或抛出安全错误 | 写入返回阴；读取返回（阴，空字符串）；删除无事 |
| 宿主已关闭 | 抛事故 |
## 一致性样例
1. `写入网页储存("本地", "偏好", "云端")` 返回阳；`读取网页储存("本地", "偏好")` 返回（阳，“云端”）；`删除网页储存` 后再读返回（阴，“”）。
2. 会话与本地互不相通：会话里写入的键在本地里读不到。
3. `读取网页储存("临时", "键")`：抛事故（区域无效）。
4. 值恰为 1048576 个码元时写入成功（或因配额返回阴）；多一个码元抛事故。
5. 浏览器储存写入抛出 QuotaExceededError 时，`写入网页储存` 返回阴，原有键值不变。
## 边界
本包不规定：键的枚举与清空、`storage` 跨标签页事件、IndexedDB、Cache API、二进制值、加密储存、同步之外的持久化保证。敏感数据（口令、令牌）不应放入这两种储存。
# 网页储存之约 0.1.0 此包令浏览器中豫言之客读写当前网页**来源**（协议、主机、端口）下之键值文，用于未发之稿、界面之好、展开之态等仅须存于本机之小数。乃浏览器 sessionStorage 与 localStorage 之至简公共子集：惟读、写、删三术；**写败乃可复之情，以返值示之，不发事故**。客依此包，诸术皆当具。 ## 区 区参数惟受二定值： | 区 | 所应 | 寿 | | --- | --- | --- | | 会话 | sessionStorage | 当前标签页（含刷新）；标签页闭则除 | | 本地 | localStorage | 久存，同来源诸标签页共之 | 区名非此二者则发事故。 ## 诸术 ### 读取网页储存：字符串（区）、字符串（键），返（爻、字符串） 键在则返（阳，值）；键无，或浏览器禁用储存（隐私模式、为人或策略所封）则返（阴，空文）。欲辨“无键”与“值为空文”，观首项：值为空文则（阳，空文）。 ### 写入网页储存：字符串（区）、字符串（键）、字符串（值），返爻 成则返阳。**配额满、储存被禁、隐私模式零配额**等运行时之败返阴，且不改旧内容；客当告用户（如“草稿未能保留”）。区名无效、键空或过长、值逾限，乃违约之调用，发事故。 ### 删除网页储存：字符串（区）、字符串（键），返有 去其键；键无或储存不可用则无事。 ## 键与值 - 键**原样而用，宿主不加前缀**。同来源诸客共一键空间，客自以带项目名之键（如 yy-cloud-draft:账户:项目:ai）避冲突；由旧 JS 前端迁来之既有键值亦因而仍效。 - 键至多五百一十二 UTF-16 码元，不得为空；值至多一百零四万八千五百七十六码元，可为空文。 - 值乃任意豫言字符串（含癸象文）。 ## 与网页事件之涉 此包不生事。他标签页改同一 localStorage 所致之 storage 事，此版不供；客欲跨页相同步，当自轮询，或待后续之广播包。 ## 败之类 | 情 | 表 | | --- | --- | | 区名无效；键空或逾五百一十二码元；值逾限 | 发豫言事故（违约之调用，中文辞） | | 配额满、储存被禁或发安全之错 | 写返阴；读返（阴，空文）；删无事 | | 宿主已闭 | 发事故 | ## 一致性之例 1. 写入网页储存（本地，偏好，云端）返阳；读取（本地，偏好）返（阳，“云端”）；删除后再读返（阴，“”）。 2. 会话与本地不相通：会话所写之键，于本地读不到。 3. 读取网页储存（“临时”，“键”）：发事故（区无效）。 4. 值恰一百零四万八千五百七十六码元则写成（或因配额返阴）；多一码元则发事故。 5. 浏览器写发 QuotaExceededError 时，写入网页储存返阴，旧键值不变。 ## 界 此包不定：键之枚举与清空、storage 跨页事、IndexedDB、Cache API、二进制值、加密之储、同步以外之久存保证。口令、令牌等秘数不宜置于此二储。