快应用新增storage同步接口

Author: changhuii

rfcs/1300/0000-add-storage-sync-ability.md

@@ -0,0 +1,151 @@
+- 提案时间: 2023-05-26
+- 影响版本: 1300
+- 相关 Issues: 无
+
+## 【必填】概述
+
+数据存储storage增加同步调用能力。
+
+## 【必填】动机
+
+简化开发者在同步场景下开发工作，提供多种接口适应不同场景。
+
+## 【必填】API规格和使用案例
+
+#### 接口定义
+
+storage.getSync(OBJECT)
+
+同步方法，读取存储内容。同步方法会阻塞js线程，注意避免连续多次调用。
+
+参数：
+
+| 参数名  |  类型  | 必填 |                             说明                             |
+| :-----: | :----: | :--: | :----------------------------------------------------------: |
+|   key   | String |  是  |                             索引                             |
+| default | String |  否  | 如果 key 不存在，返回 default。如果 default 未指定，返回长度为 0 的空字符串 |
+
+success 返回值：
+
+key 对应的存储内容
+
+##### 代码案例
+\```javascript
+var result = storage.getSync({
+   key: 'A1'
+})
+\```
+
+storage.setSync(OBJECT)
+
+同步方法修改存储内容。同步方法会阻塞JS线程，后续同步JS代码会等待该方法执行完毕后才继续执行。
+
+参数：
+
+| 参数名   | 类型     | 必填 | 说明                                                         |
+| -------- | -------- | ---- | ------------------------------------------------------------ |
+| key      | String   | 是   | 索引                                                         |
+| value    | String   | 否   | 新值。如果新值是长度为 0 的空字符串，会删除以 key 为索引的数据项 |
+| success  | Function | 否   | 成功回调                                                     |
+| fail     | Function | 否   | 失败回调                                                     |
+| complete | Function | 否   | 执行结束后的回调                                             |
+
+##### 代码案例：
+
+\```javascript
+storage.setSync({
+      key: 'A1',
+      value: 'V1'
+ })
+\```
+
+storage.clearSync(OBJECT)
+
+同步方法清空存储内容。同步方法会阻塞js线程，后续同步JS代码会等待该方法执行完毕后才继续执行。
+
+参数：
+
+| 参数名   | 类型     | 必填 | 说明             |
+| -------- | -------- | ---- | ---------------- |
+| success  | Function | 否   | 成功回调         |
+| fail     | Function | 否   | 失败回调         |
+| complete | Function | 否   | 执行结束后的回调 |
+
+##### 代码案例
+
+\```javascript
+storage.clearSync()
+\```
+
+storage.deleteSync(OBJECT)
+
+同步方法删除存储内容。同步方法会阻塞js线程，后续同步JS代码会等待该方法执行完毕后才继续执行。
+
+参数：
+
+| 参数名   | 类型     | 必填 | 说明             |
+| -------- | -------- | ---- | ---------------- |
+| key      | String   | 是   | 索引             |
+| success  | Function | 否   | 成功回调         |
+| fail     | Function | 否   | 失败回调         |
+| complete | Function | 否   | 执行结束后的回调 |
+
+##### 代码案例
+
+\```javascript
+storage.deleteSync({
+      key: 'A1'
+})
+\```
+
+storage.keySync(OBJECT) `1050+`
+
+同步方法返回存储中某个 index 的键名。同步方法会阻塞js线程，后续同步JS代码会等待该方法执行完毕后才继续执行。
+
+参数：
+
+| 参数名   | 类型     | 必填 | 说明                   |
+| -------- | -------- | ---- | ---------------------- |
+| index    | Number   | 是   | 要查询的键名对应的索引 |
+| success  | Function | 否   | 成功回调               |
+| fail     | Function | 否   | 失败回调               |
+| complete | Function | 否   | 执行结束后的回调       |
+
+success 返回值：
+
+index 对应的键名
+
+##### 代码案例
+
+\```javascript
+var result =storage.keySync({
+      index: 0
+})
+\```
+
+
+## 【必填】提案人员是否愿意自行实现该功能
+
+*是：提案人员愿意在提案通过后自行实现该功能；
+
+## 详细设计
+
+可选，请向一个熟悉 hapjs内部实现的人讲解如何在 hapjs中实现这个功能，或讲解实现这一功能需要什么步骤。
+
+## 缺陷
+
+我们是不是可以不做这个功能，请考虑：
+
+- 实现这个功能的投入：包括代码的复杂度、代码体积的增加、实现功能投入的人力
+- 这个功能是不是不需要 hapjs提供，使用 hapjs的开发者也可以在应用层实现，甚至实现得更好
+- 对 hapjs既有惯用开发习惯的影响
+- 对已发布版本和现有功能的影响，以及用户进行迁移的成本
+- 对其它未有代码实现的 RFC 提案的影响
+
+## 替代选择
+
+还有其他的方案也可以实现这个功能吗？
+
+## 适配策略
+
+如果我们实现了这个提案，有没有什么办法可以帮助开发者更好地适应这个改动？