From 5aae939272c353fc4cef0eaa58885fafdfe093d6 Mon Sep 17 00:00:00 2001
From: DCloud_LXH <283700113@qq.com>
Date: Mon, 25 Sep 2023 16:05:13 +0800
Subject: [PATCH] fix: uni-app x api

---
 docs/uni-app-x/api/README.md                |  42 +++++++
 docs/uni-app-x/api/exit.md                  |  10 ++
 docs/uni-app-x/api/nodes-info.md            | 125 +++++++++++++++++++-
 docs/uni-app-x/api/pagescrollto.md          |   6 +
 docs/uni-app-x/api/pull-down-refresh.md     |   7 ++
 docs/uni-app-x/api/request.md               |  11 +-
 docs/uni-app-x/api/setnavigationbarcolor.md |   2 +
 docs/uni-app-x/api/storage.md               |  17 +++
 8 files changed, 218 insertions(+), 2 deletions(-)
 create mode 100644 docs/uni-app-x/api/README.md

diff --git a/docs/uni-app-x/api/README.md b/docs/uni-app-x/api/README.md
new file mode 100644
index 000000000..5d823efc6
--- /dev/null
+++ b/docs/uni-app-x/api/README.md
@@ -0,0 +1,42 @@
+# API概述
+
+uni-app x项目的uts代码中可以使用很多API。包括：
+
+- uts的api [详见](../../uts/buildin-object-api/global.md)
+- 全局api，前面不需要加`uni.`。如`getApp`
+- uni.xxx的内置api。见左侧
+- uniCloud.xxx的内置api。见左侧
+- dom的api [详见](dom/README.md)
+- vue的api [详见](../../tutorial/vue3-api.md)
+- 原生api
+	
+	由于uts可以直接调用Android和iOS的api，所以os和三方sdk的能力都可以在uts中调用。如下：
+
+```vue
+<script>
+	import Build from 'android.os.Build';
+	export default {
+		onLoad() {
+			console.log(Build.MODEL); //调用原生对象，返回手机型号
+			console.log(uni.getSystemInfoSync().deviceModel); //调用uni API，返回手机型号。与上一行返回值相同
+		}
+	}
+</script>
+```
+
+上面的示例，在页面启动时打印了2行日志，显示手机型号。
+
+- uni.getSystemInfoSync，是uni的api
+- import的Build，是Android os的api
+
+可以看出，在uni-app x里，可以直接调用os的能力，不受限制，语法是uts的语法，但需要了解什么功能在原生里是哪个api。
+
+使用`uni.getSystemInfoSync`则比较简单，看uni的文档即可，且可跨平台。
+
+其实，`uni.getSystemInfoSync`的内部实现就是一个uts模块，底层使用了一样的代码。
+
+大多数uni.的api，都是uts开发的，它们会陆续开源在[uni-api](https://gitcode.net/dcloud/uni-api)。
+
+插件市场也有很多做好的uts插件，方便开发者拿来即用。[uts插件](https://ext.dcloud.net.cn/?cat1=8&type=UpdatedDate)
+
+虽然上述页面可以直接调用原生能力，但一般原生能力建议封装为[uni_modules](../../plugin/uni_modules.md)形式的[uts插件](../../plugin/uts-plugin.md)。这样方便共享、方便跨平台。
\ No newline at end of file
diff --git a/docs/uni-app-x/api/exit.md b/docs/uni-app-x/api/exit.md
index f07be9db5..df6988bdc 100644
--- a/docs/uni-app-x/api/exit.md
+++ b/docs/uni-app-x/api/exit.md
@@ -8,6 +8,16 @@
 
 <!-- UTSAPIJSON.exit.compatibility -->
 
+本API仅Android App生效。
+
+Android平台的应用退出分热退出和冷退出。
+- 冷退出是彻底杀掉
+- 热退出是关闭可见的activity，后台进程不退出（比如push）
+
+基本上主流Android App都是热退出。本API也是热退出。
+
+热退出，即通知了os：这个app用户不用了，在os需要时可以回收。如果在os回收之前，用户又启动这个app，会感觉启动速度更快一些。
+
 <!-- UTSAPIJSON.exit.tutorial -->
 
 <!-- UTSAPIJSON.general_type.name -->
diff --git a/docs/uni-app-x/api/nodes-info.md b/docs/uni-app-x/api/nodes-info.md
index e5cc1ee18..8e0bc61c1 100644
--- a/docs/uni-app-x/api/nodes-info.md
+++ b/docs/uni-app-x/api/nodes-info.md
@@ -4,12 +4,135 @@
 
 <!-- UTSAPIJSON.createSelectorQuery.param -->
 
+**selector 说明：**
+
+``selector`` 类似于 CSS 的选择器，但仅支持下列语法。
+- ID选择器：``#the-id``
+- class选择器：``.a-class``
+
 <!-- UTSAPIJSON.createSelectorQuery.returnValue -->
 
+##### NodeInfo 属性值
+
+|属性		|类型		|说明							|
+|---		|---		|---							|
+|id			|String	|节点的 ID				|
+|dataset|Object	|节点的 dataset		|
+|left		|Number	|节点的左边界坐标	|
+|right	|Number	|节点的右边界坐标	|
+|top		|Number	|节点的上边界坐标	|
+|bottom	|Number	|节点的下边界坐标	|
+|width	|Number	|节点的宽度				|
+|height	|Number	|节点的高度				|
+
 <!-- UTSAPIJSON.createSelectorQuery.compatibility -->
 
 <!-- UTSAPIJSON.createSelectorQuery.tutorial -->
 
 <!-- UTSAPIJSON.general_type.name -->
 
-<!-- UTSAPIJSON.general_type.param -->
\ No newline at end of file
+<!-- UTSAPIJSON.general_type.param -->
+
+
+### 代码示例
+
+```html
+<template>
+  <view>
+    <button class="btn btn-get-node-info" @click="getNodeInfo">getNodeInfo</button>
+    <button class="btn btn-get-all-node-info" @click="getAllNodeInfo">getAllNodeInfo</button>
+    <view class="rect-1-2">
+      <view class="rect rect1"></view>
+      <view class="rect rect2"></view>
+    </view>
+    <view class="rect-info-1-2">
+      <view class="rect-info" v-for="(nodeInfo, index) in nodeInfoList" :key="index">
+        <view class="node-info-item">
+          <text class="node-info-item-k">left: </text>
+          <text class="node-info-item-v">{{nodeInfo.left}}</text>
+        </view>
+        <view class="node-info-item">
+          <text class="node-info-item-k">top: </text>
+          <text class="node-info-item-v">{{nodeInfo.top}}</text>
+        </view>
+        <view class="node-info-item">
+          <text class="node-info-item-k">right: </text>
+          <text class="node-info-item-v">{{nodeInfo.right}}</text>
+        </view>
+        <view class="node-info-item">
+          <text class="node-info-item-k">bottom: </text>
+          <text class="node-info-item-v">{{nodeInfo.bottom}}</text>
+        </view>
+        <view class="node-info-item">
+          <text class="node-info-item-k">width: </text>
+          <text class="node-info-item-v">{{nodeInfo.width}}</text>
+        </view>
+        <view class="node-info-item">
+          <text class="node-info-item-k">height: </text>
+          <text class="node-info-item-v">{{nodeInfo.height}}</text>
+        </view>
+      </view>
+    </view>
+  </view>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        nodeInfoList: [] as NodeInfo[]
+      }
+    },
+    methods: {
+      getNodeInfo() {
+        uni.createSelectorQuery().select('.rect1').boundingClientRect().exec((ret) => {
+          this.nodeInfoList.length = 0
+          this.nodeInfoList.push(ret[0] as NodeInfo)
+        })
+      },
+      getAllNodeInfo() {
+        uni.createSelectorQuery().selectAll('.rect').boundingClientRect().exec((ret) => {
+          this.nodeInfoList.length = 0
+          this.nodeInfoList.push(...(ret[0] as NodeInfo[]))
+        })
+      }
+    }
+  }
+</script>
+```
+
+组件内使用
+
+`this.createSelectorQuery()`, 等效于 `uni.createSelectorQuery().in(this)`
+
+```html
+<template>
+  <view>
+    <button @click="getNodeInfo">getNodeInfo</button>
+    <view class="rect-1-2">
+      <view class="rect rect1"></view>
+      <view class="rect rect2"></view>
+    </view>
+  </view>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        nodeInfoList: [] as NodeInfo[]
+      }
+    },
+    props: {
+    },
+    methods: {
+      getNodeInfo() {
+        this.createSelectorQuery().select('.rect1').boundingClientRect().exec((ret) => {
+          this.nodeInfoList.length = 0
+          this.nodeInfoList.push(ret[0] as NodeInfo)
+        })
+      }
+    }
+  }
+</script>
+```
diff --git a/docs/uni-app-x/api/pagescrollto.md b/docs/uni-app-x/api/pagescrollto.md
index 3c9cb9301..eedc5a9a0 100644
--- a/docs/uni-app-x/api/pagescrollto.md
+++ b/docs/uni-app-x/api/pagescrollto.md
@@ -2,8 +2,14 @@
 
 <!-- UTSAPIJSON.pageScrollTo.description -->
 
+可以滚动到指定的scrollTop值处，也可以滚动到指定的目标元素处（通过css选择器selector）, 仅支持一级 class
+
+app-uvue下，只有页面的根元素为scroll-view时，本API才生效。[详见](../css/readme.md#pagescroll)
+
 <!-- UTSAPIJSON.pageScrollTo.param -->
 
+`scrollTop` 和 `selector` 必须指定其中一个属性，否者触发 `fail` 回调
+
 <!-- UTSAPIJSON.pageScrollTo.returnValue -->
 
 <!-- UTSAPIJSON.pageScrollTo.compatibility -->
diff --git a/docs/uni-app-x/api/pull-down-refresh.md b/docs/uni-app-x/api/pull-down-refresh.md
index c77db359b..f5dd984cc 100644
--- a/docs/uni-app-x/api/pull-down-refresh.md
+++ b/docs/uni-app-x/api/pull-down-refresh.md
@@ -2,6 +2,13 @@
 
 <!-- UTSAPIJSON.stopPullDownRefresh.description -->
 
+使用：
+1. 首先pages.json里配置了页面可下拉刷新`"enablePullDownRefresh": true`
+2. 当用户下拉页面时触发页面生命周期`onPullDownRefresh`
+3. 在合适的时机（如联网刷新数据结束），调用本API`uni.stopPullDownRefresh()`，结束下拉刷新状态
+
+本API仅负责页面下拉刷新。如使用组件下拉刷新，另见scroll-view、list-view等组件的文档。
+
 <!-- UTSAPIJSON.stopPullDownRefresh.param -->
 
 <!-- UTSAPIJSON.stopPullDownRefresh.returnValue -->
diff --git a/docs/uni-app-x/api/request.md b/docs/uni-app-x/api/request.md
index 0635d80a8..cdf85982c 100644
--- a/docs/uni-app-x/api/request.md
+++ b/docs/uni-app-x/api/request.md
@@ -12,4 +12,13 @@
 
 <!-- UTSAPIJSON.general_type.name -->
 
-<!-- UTSAPIJSON.general_type.param -->
\ No newline at end of file
+<!-- UTSAPIJSON.general_type.param -->
+
+## 注意事项
+
+* request 接口内部通过[特殊方式读取了范型类型](../../uts/generics.md#使用限制)，不支持传入动态的范型：比如将外层方法的普通范型参数传入 request。
+* 如果使用泛型先创建RequestOptions实例，再传入uni.request()，此时请务必确保request要显式指定泛型，例：
+    ```typescript
+    const options: RequestOptions<Person> = ...
+    uni.request<Person>(options)
+    ```
diff --git a/docs/uni-app-x/api/setnavigationbarcolor.md b/docs/uni-app-x/api/setnavigationbarcolor.md
index d87084121..d3c565df7 100644
--- a/docs/uni-app-x/api/setnavigationbarcolor.md
+++ b/docs/uni-app-x/api/setnavigationbarcolor.md
@@ -2,6 +2,8 @@
 
 <!-- UTSAPIJSON.setNavigationBarColor.description -->
 
+即便pages.json里没有配置NavigationBar，如需修改状态栏的前景背景，也需要本API。
+
 <!-- UTSAPIJSON.setNavigationBarColor.param -->
 
 <!-- UTSAPIJSON.setNavigationBarColor.returnValue -->
diff --git a/docs/uni-app-x/api/storage.md b/docs/uni-app-x/api/storage.md
index c1831bcbe..0a96a0dd4 100644
--- a/docs/uni-app-x/api/storage.md
+++ b/docs/uni-app-x/api/storage.md
@@ -1,3 +1,20 @@
+## key-value本地数据存储
+
+app、小程序、web，均提供了方便的key-value模式的本地数据存储，通过键值对的方式存取数据。
+
+uni-app的Storage在不同端的实现不同：
+- H5端为localStorage，浏览器限制5M大小，是缓存概念，可能会被清理
+- App端为原生storage，无大小限制，不是缓存，是持久化的
+- 各个小程序端为其自带的storage api，数据存储生命周期跟小程序本身一致，即除用户主动删除或超过一定时间被自动清理，否则数据都一直可用。
+	* 微信小程序单个 key 允许存储的最大数据长度为 1MB，所有数据存储上限为 10MB。
+	* 支付宝小程序单条数据转换成字符串后，字符串长度最大200*1024。同一个支付宝用户，同一个小程序缓存总上限为10MB。
+	* 百度小程序策略[详见](https://smartprogram.baidu.com/docs/develop/api/storage/save_process/)
+	* 抖音小程序策略[详见](https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/api/data-caching/tt-get-storage)
+
+**注意**
+- `uni-`、`uni_`、`dcloud-`、`dcloud_`为前缀的key，为系统保留关键前缀。如`uni_deviceId`、`uni_id_token`，请开发者为key命名时避开这些前缀。
+- 非App平台清空Storage会导致uni.getSystemInfo获取到的deviceId改变
+
 ## uni.setStorage(options) @setstorage
 
 <!-- UTSAPIJSON.setStorage.description -->
-- 
GitLab