tmui-cli 2.0.3 → 2.0.4

package/data/uniappx/api/dom/README.md

@@ -0,0 +1,319 @@
+# UVUE DOM
+
+每个uvue页面，在内存中都有一个 DOM（文档对象模型）。它和浏览器的 [DOM规范](https://www.w3.org/DOM/?spm=a2c7j.-zh-docs-api-weex-variable.0.0.2a5537c6FrgbYp) 类似。
+
+DOM 是页面元素内容的结构数据。DOM 模型用一个逻辑树来表示一个页面文档，树的每个分支的终点都是一个节点，每个节点都对应一个节点对象（UniElement）。
+
+实际上 uvue 的template、数据绑定，在底层调用的也是 DOM API。
+
+在浏览器中，开发者一旦跳过vue框架直接操作dom，vue框架将无法管理相应dom，开发者需要注意两端的冲突。
+
+为了减少冲突，目前不支持通过 DOM API 创建和删除 DOM 树中的元素。只支持获取元素UniElement。
+
+DOM在Web、Android、iOS、鸿蒙、微信小程序均存在。微信小程序受微信限制，只实现了部分DOM API，请注意兼容性表格。
+
+> HBuilderX4.0 开始DOM元素的类型统一调整为 UniElement 对象。废弃之前 HBuilderX 3.91 的 Element对象 和 HBuilderX 3.91以前的 INode 对象。
+
+## 使用场景
+通常情况下，使用 uvue 框架的数据绑定来操作更新页面组件就可以。但有2个场景，需要使用 DOM API。
+
+1. 跟手动效
+
+	响应触屏事件更新组件的位置，要想不掉帧，需要保证16毫秒绘制一帧。
+
+	uvue的data更新，有一套diff机制，每次触发data更新，会多几毫秒的耗时。
+
+	此时推荐通过 DOM API 跳过 vue 框架直接操作组件的样式。
+
+2. Draw API
+
+	Android和iOS的原生view，有一些底层的高性能绘制能力，这些API的调用，需要先获取到 UniElement 对象，然后再调用其方法。
+
+在[性能](../../performance.md)章节，对这2个场景有详细的阐述。
+
+## DOM元素对象@getDomNode
+
+在操作DOM元素对象前，需要先获取 `UniElement` 对象，可通过 `uni.getElementById` 或 `this.$refs` 获取。
+
+### 通过uni.getElementById获取DOM元素
+
+app-uvue 页面中可以为页面元素节点设置 id 属性，然后通过 [uni.getElementById](../get-element-by-id.md#getelementbyid) 获取 DOM 元素对象。
+
+但注意这个方法只能获取栈顶页面的element。如需绑定调用的页面，需使用下方的[this.$refs](#refs)
+
+首先需要为组件设置 id 属性值：
+```vue
+
+<view id="myView" class="container">
+	<text>Hello World</text>
+</view>
+```
+
+在页面`onReady` 后（太早组件可能没有创建），通过 `uni.getElementById` 获取。如果长期使用，可以保存在vue的 data 中。
+::: preview
+
+> 组合式 API
+```ts
+const color = ref('red')
+const myView = ref<UniElement | null>(null)
+
+onReady(() => {
+	myView.value = uni.getElementById('myView')
+})
+```
+
+> 选项式 API
+```ts
+export default {
+	data() {
+		return {
+			color: 'red',
+			myView: null as UniElement | null
+		}
+	},
+	onReady() {
+			// 获取组件对象并保存在 this.myView 中
+			this.myView = uni.getElementById('myView');
+	},
+}
+```
+
+### 通过this.$refs获取DOM元素@refs
+uvue页面中可以通过 vue 框架中的组件实例对象 [this.$refs](https://uniapp.dcloud.net.cn/tutorial/vue3-api.html#%E5%AE%9E%E4%BE%8B-property) 获取 DOM 元素对象。
+
+首先需要为组件设置 ref 属性值，它类似于id：
+```vue
+
+<view ref="myView" class="container">
+	<text>Hello World</text>
+</view>
+```
+
+在页面`onReady` 后（太早组件可能没有创建），通过 `this.$refs` 获取。如果长期使用，可以保存在vue的 data 中。
+::: preview
+
+> 组合式 API
+```ts
+const color = ref('red')
+const myView = ref<UniElement | null>(null)
+
+onReady(() => {
+	// 通过模板 ref 获取时，myView.value 即为组件对象
+})
+```
+
+> 选项式 API
+```ts
+export default {
+	data() {
+		return {
+			color: 'red',
+			myView: null as UniElement | null
+		}
+	},
+	onReady() {
+			// 获取组件对象并保存在 this.myView 中
+			this.myView = this.$refs['myView'] as UniElement;  //需要使用 as 转换
+	},
+}
+```
+
+### 操作DOM元素对象
+获取DOM元素对象Element后，可通过其属性或方法操作组件，完整API参考[UniElement对象文档](unielement.md)
+
+如通过UniElement对象的 style 属性更新组件的样式：
+```ts
+this.myView?.style?.setProperty('background-color', 'red');
+```
+
+### 示例
+以下是完整的操作示例：
+::: preview
+
+> 组合式 API
+```vue
+<template>
+	
+	<scroll-view style="flex:1;">
+	
+		<view id="myView" ref="myView" class="container">
+			<text>Hello World</text>
+		</view>
+		<button class="button" @tap="updateElement">操作UniElement</button>
+	
+	</scroll-view>
+	
+</template>
+
+<style>
+	.container {
+		align-self: center;
+		align-items: center;
+		justify-content: center;
+		background-color: lightgray;
+		width: 100%;
+		height: 200px;
+	}
+	.button {
+		margin: 10px auto;
+	}
+</style>
+```
+
+> 选项式 API
+```vue
+<template>
+	
+	<scroll-view style="flex:1;">
+	
+		<view id="myView" ref="myView" class="container">
+			<text>Hello World</text>
+		</view>
+		<button class="button" @tap="updateElement">操作UniElement</button>
+	
+	</scroll-view>
+	
+</template>
+
+<style>
+	.container {
+		align-self: center;
+		align-items: center;
+		justify-content: center;
+		background-color: lightgray;
+		width: 100%;
+		height: 200px;
+	}
+	.button {
+		margin: 10px auto;
+	}
+</style>
+```
+
+>以上例子仅为演示DOM API的使用，实际上点击按钮修改背景色这种简单场景，使用数据绑定更简单，class绑定到一个data上，动态修改data即可。
+
+## 通过 DrawableContext 绘制View
+
+uni-app x 在 app 端提供 DrawableContext 绘制内容到 uvue 页面的`view`标签上。可用于绘制文本、形状等内容。
+
+### 获取 DrawableContext 对象
+
+DrawableContext 可通过`view`组件节点对象（UniElement）的`getDrawableContext()`方法获取
+
+::: preview
+
+> 组合式 API
+```vue
+<template>
+	<view ref="drawable" class="drawableView"></view>
+</template>
+
+```
+
+> 选项式 API
+```vue
+<template>
+	<view ref="drawable" class="drawableView"></view>
+</template>
+
+```
+
+**注意**  
+`DrawableContext` 对象需等元素渲染到页面后才能正常使用，要在页面 `onReady` 生命周期后获取。  
+
+### 绘制内容
+
+通过 DrawableContext 提供的 Draw API 绘制文本、形状等内容
+
+::: preview
+
+> 组合式 API
+```vue
+
+```
+
+> 选项式 API
+```ts
+
+```
+
+### 更新到画布
+
+DrawableContext 在调用 API 之后不会主动更新到画布上，需要主动调用`update()`方法更新。
+
+::: preview
+
+> 组合式 API
+```vue
+
+```
+
+> 选项式 API
+```ts
+
+```
+
+### 清除画布内容
+
+如果清除已经绘制的内容重新绘制，需要调用`reset()`方法清除内容再进行绘制。
+
+::: preview
+
+> 组合式 API
+```vue
+
+```
+
+> 选项式 API
+```vue
+
+```
+
+### 示例
+以下是完整的操作示例：
+
+::: preview
+
+> 组合式 API
+```vue
+<template>
+	<view ref="drawable" class="drawableView"></view>
+	<button class="button" @tap="refreshDrawable">重新绘制</button>
+</template>
+
+<style>
+	.drawableView {
+		width: 750rpx;
+		height: 750rpx;
+		background-color: #FFFFFF;
+	}
+	.button {
+		margin: 10px auto;
+		width: 50%;
+	}
+</style>
+```
+
+> 选项式 API
+```vue
+<template>
+	<view ref="drawable" class="drawableView"></view>
+	<button class="button" @tap="refreshDrawable">重新绘制</button>
+</template>
+
+<style>
+	.drawableView {
+		width: 750rpx;
+		height: 750rpx;
+		background-color: #FFFFFF;
+	}
+	.button {
+		margin: 10px auto;
+		width: 50%;
+	}
+</style>
+```
+
+## 注意事项
+
+由于排版和渲染是异步的，在修改 DOM 后，立刻使用 DOM 的同步接口获取 DOM 状态可能获取到的是排版之前的，如果需要及时准确的获取到排版之后的 DOM 状态需要使用 [uni.createSelectorQuery](../nodes-info.md) 。

package/data/uniappx/api/dom/cssstyledeclaration.md

@@ -0,0 +1,341 @@
+## CSSStyleDeclaration
+
+CSSStyleDeclaration表示一个CSS 声明块对象，它是一个 CSS 属性键值对的集合，暴露样式信息和各种与样式相关的方法和属性。
+
+### 方法
+
+#### App平台
+
+> HBuilderX4.51版本调整 `getPropertyValue` 返回值类型为 string
+
+App平台获取样式值与Web平台存在部分差异：
+- 组件通过 class 设置的 CSS 样式，App平台可通过 `getPropertyValue` 获取生效的样式值，Web平台不可获取（返回空字符串）。
+  如下示例，在class中设置background-color样式，App平台可通过 getPropertyValue 获取：
+  ```vue
+  <template>
+  
+  <scroll-view style="flex: 1;">
+  
+    <text class="inf">{{text}}</text>
+    <button @click="onClick">获取样式值</button>
+    <view ref="testElement" class="element">
+      <view class="des">
+        <text>获取通过class设置的样式</text>
+      </view>
+    </view>
+  
+  </scroll-view>
+  
+  </template>
+
+  
+
+  <style>
+  .element {
+    background-color: #FFFF00;
+  }
+  .inf {
+    width: 100%;
+    height: 50px;
+    text-align: center;
+  }
+  .des {
+    width: 100px;
+    height: 100px;
+    background-color: aquamarine;
+    align-self: center;
+  }
+  </style>
+  ```
+  注意：App平台在 class 中设置部分的css样式会做转换，规则如下
+  + named-color 会转换为十六进制颜色六值语法（即 #RRGGBB 格式），如在class中设置 background-color 为 blue，获取的值为 #0000FF
+
+- 组件通过 class 和 style 同时设置的 CSS 样式，App平台通过 `getPropertyValue` 获取的是合并计算后生效的样式，Web平台获取的是 style 属性设置的样式。
+  如下示例，在class中设置的border-top-style样式覆盖了style中设置的border-top-style样式，App平台可通过 getPropertyValue 获取计算后生效的样式值：
+  ```vue
+  <template>
+  
+  <scroll-view style="flex: 1;">
+  
+    <text class="inf">{{text}}</text>
+    <button @click="onClick">获取样式值</button>
+    <view ref="testElement" class="element" style="border-top-style: solid;">
+      <view class="des">
+        <text>获取通过class覆盖style的样式</text>
+      </view>
+    </view>
+  
+  </scroll-view>
+  
+  </template>
+
+  
+
+  <style>
+  .element {
+    border-top-style: dotted !important;
+  }
+  .inf {
+    width: 100%;
+    height: 50px;
+    text-align: center;
+  }
+  .des {
+    width: 100px;
+    height: 100px;
+    background-color: aquamarine;
+    align-self: center;
+  }
+  </style>
+  ```
+
+- 组件通过 style 设置的 CSS 简写样式，App平台会拆解（Expansion）部分简写样式，拆解（Expansion）的样式通过 `getPropertyValue` 只能获取拆解后的样式，获取拆解前的简写样式返回空字符串。
+  拆解的简写样式包括：
+  + border
+  + border-bottom
+  + border-left
+  + border-right
+  + border-top
+  + border-color
+  + border-raidus
+  + border-style
+  + broder-width
+  + margin
+  + padding
+
+  如下示例，在style中设置简写样式border-color，App平台通过 getPropertyValue 获取拆解前样式 border-color 返回空字符串，获取拆解后样式 border-top-color 返回"#FFFF00"：
+  ```vue
+  <template>
+  
+  <scroll-view style="flex: 1;">
+  
+    <text class="inf">{{text}}</text>
+    <button @click="onClick">获取样式值</button>
+    <view ref="testElement" class="element" style="border-color: #FFFF00;">
+      <view class="des">
+        <text>获取通过style/class设置的简写样式</text>
+      </view>
+    </view>
+  
+  </scroll-view>
+  
+  </template>
+
+  
+
+  <style>
+  .element {
+    border-style: dotted;
+  }
+  .inf {
+    width: 100%;
+    height: 50px;
+    text-align: center;
+  }
+  .des {
+    width: 100px;
+    height: 100px;
+    background-color: aquamarine;
+    align-self: center;
+  }
+  </style>
+  ```
+  注意：通过 class 设置的 CSS 简写样式，App平台获取的也是拆解（Expansion）后的样式
+
+- 通过 `setProperty` 设置的 CSS 简写样式，App平台通过 `getPropertyValue` 只能获取简写样式，获取拆解（Expansion）后的样式返回空字符串。
+  如下示例，通过 setProperty 设置 border-style 简写样式为 "dotted"，App平台通过 getPropertyValue 获取 border-style 会返回设置的值"dotted"，获取 border-top-style 返回空字符串：
+  ```vue
+  
+    <text class="inf">{{text}}</text>
+    <button @click="onClick">获取样式值</button>
+    <view ref="testElement">
+      <view class="des">
+        <text>获取通过setProperty设置的样式</text>
+      </view>
+    </view>
+  
+  </scroll-view>
+  
+  </template>
+
+  
+
+  <style>
+  .inf {
+    width: 100%;
+    height: 50px;
+    text-align: center;
+  }
+  .des {
+    width: 100px;
+    height: 100px;
+    background-color: aquamarine;
+    align-self: center;
+  }
+  </style>
+  ```
+  注意：通过 `setProperty` 设置的 CSS 所有样式，App平台不会做转换处理，获取时原样返回
+
+**蒸汽模式（Vapor）**
+
+蒸汽模式（Vapor）为了提升 CSS 的性能，App平台将所有样式数据在编译器和运行期都做了类型化转换，丢失了原始字符串数据（即获取值与设置值不完全一致），与 VDOM 模式存在以下差异：
+- 没有设置的样式，App平台蒸汽模式（Vapor）下通过 `getPropertyValue` 获取将返回默认值，VDOM 模式返回空字符串。
+  如下示例，没有设置 flex-direction 样式，App平台在蒸汽模式（Vapor）下通过 getPropertyValue 获取 flex-direction 返回 "column"，非蒸汽模式下返回空字符串：
+  ```vue
+  <template>
+  
+  <scroll-view style="flex: 1;">
+  
+    <text class="inf">{{text}}</text>
+    <button @click="onClick">获取样式值</button>
+    <view ref="testElement">
+      <view class="des">
+        <text>获取没有设置过的样式</text>
+      </view>
+    </view>
+  
+  </scroll-view>
+  
+  </template>
+
+  
+
+  <style>
+  .inf {
+    width: 100%;
+    height: 50px;
+    text-align: center;
+  }
+  .des {
+    width: 100px;
+    height: 100px;
+    background-color: aquamarine;
+    align-self: center;
+  }
+  </style>
+  ```
+
+- CSS 简写样式，App平台蒸汽模式（Vapor）下通过 `getPropertyValue` 获取将返回完整的拆解值。
+  如下示例，设置 flex 为 "1"，getPropertyValue 获取 flex 返回 "1 1 0%"：
+  ```vue
+  <template>
+  
+  <scroll-view style="flex: 1;">
+  
+    <text class="inf">{{text}}</text>
+    <button @click="onClick">获取样式值</button>
+    <view ref="testElement" style="flex: 1;">
+      <view class="des">
+        <text>获取简写的样式</text>
+      </view>
+    </view>
+  
+  </scroll-view>
+  
+  </template>
+
+  
+
+  <style>
+  .inf {
+    width: 100%;
+    height: 50px;
+    text-align: center;
+  }
+  .des {
+    width: 100px;
+    height: 100px;
+    background-color: aquamarine;
+    align-self: center;
+  }
+  </style>
+  ```
+  注意：这里 flex 简写样式在 VDOM 模式不会拆解
+
+- 通过 `getPropertyValue` 获取的颜色值（如background-color、color、border-color、border-*-color）格式为十六进制颜色八值语法“#RRGGBBAA”，其中 RR、GG、BB、AA分别对应红色、绿色、蓝色、透明值，使用大写字符。
+  如下示例，设置 background-color 为 "blue"，App平台在蒸汽模式（Vapor）下通过getPropertyValue 获取 background-color 返回 "#0000FFFF"：
+  ```vue
+  <template>
+  
+  <scroll-view style="flex: 1;">
+  
+    <text class="inf">{{text}}</text>
+    <button @click="onClick">获取样式值</button>
+    <view ref="testElement" style="background-color: blue;">
+      <view class="des">
+        <text>获取background-color设置为blue时返回的样式值</text>
+      </view>
+    </view>
+  
+  </scroll-view>
+  
+  </template>
+
+  
+
+  <style>
+  .inf {
+    width: 100%;
+    height: 50px;
+    text-align: center;
+  }
+  .des {
+    width: 50%;
+    height: 100px;
+    background-color: aquamarine;
+    align-self: center;
+  }
+  </style>
+  ```
+
+  特殊值对应的颜色
+  + transparent: 对应十六进制颜色八值语法为 #00000000
+
+- 通过 `setProperty` 设置布局相关的 CSS 样式，不能立即通过 `getPropertyValue` 同步获取设置的样式，此时返回的是设置前的样式，需要在 `nextTick` 异步回调中通过 `getPropertyValue` 才能获取到设置的值
+  ```vue
+  <template>
+  
+  <scroll-view style="flex: 1;">
+  
+    <text class="inf">{{text}}</text>
+    <button @click="onClick">获取样式值</button>
+    <view ref="testElement">
+      <view class="des">
+        <text></text>
+      </view>
+    </view>
+  
+  </scroll-view>
+  
+  </template>
+
+  
+
+  <style>
+  .inf {
+    width: 100%;
+    height: 50px;
+    text-align: center;
+  }
+  .des {
+    width: 50%;
+    height: 100px;
+    background-color: aquamarine;
+    align-self: center;
+  }
+  </style>
+  ```
+  注意：与排版无关的CSS样式（如 background-color、color、font-size等）可通过 `getPropertyValue` 同步获取设置的样式值
+
+- 5.08之前版本蒸汽模式（Vapor）通过 `getPropertyValue` 不支持获取[自定义css变量](../../css/common/function.md)
+
+## 示例
+```html
+<template>
+	<button @click="showPop">显示弹层</button>
+	<view ref="pop" style="position: absolute; display: none;">
+		<text>123</text>
+	</view>
+</template>
+
+```

package/data/uniappx/api/dom/domrect.md

@@ -0,0 +1,30 @@
+## DOMRect
+
+一个 DOMRect 代表一个矩形。
+
+### DOMRect 兼容性  
+ | Web | 微信小程序 | Android | iOS | HarmonyOS |
+| :- | :- | :- | :- | :- |
+| 4.0 | 4.11 | 3.9 | 4.11 | 4.61 |
+
+`DOMRect`表示的盒子的类型由返回它的方法或属性指定。例如: [UniElement.getBoundingClientRect()](./unielement.md#getboundingclientrect)指定使用此类对象限制范围内容的矩形。
+
+### 构造函数
+| 名称 | 类型 | 必备 | 默认值 | 描述 |
+| :- | :- | :- | :- | :- |
+| x | number | 否 | 0 | 矩形原点的x坐标 |
+| y | number | 否 | 0 | 矩形原点的y坐标 |
+| width | number | 否 | 0 | 矩形的宽 |
+| height | number | 否 | 0 | 矩形的高 |
+
+### DOMRect 的属性值 @domrect-values
+| 名称 | 类型 | 必备 | 兼容性 | 描述 |
+| :- | :- | :- |  :-: | :- |
+| width | number | 是 | Web 4.0 / 微信小程序 4.11 / Android 3.9 / iOS 4.11 / HarmonyOS 4.61 | 矩形的宽 |
+| height | number | 是 | Web 4.0 / 微信小程序 4.11 / Android 3.9 / iOS 4.11 / HarmonyOS 4.61 | 矩形的高 |
+| x | number | 是 | Web 4.0 / 微信小程序 4.11 / Android 3.9 / iOS 4.11 / HarmonyOS 4.61 | 矩形原点的x坐标 |
+| y | number | 是 | Web 4.0 / 微信小程序 4.11 / Android 3.9 / iOS 4.11 / HarmonyOS 4.61 | 矩形原点的y坐标 |
+| left | number | 是 | Web 4.0 / 微信小程序 4.11 / Android 3.9 / iOS 4.11 / HarmonyOS 4.61 | 矩形的左坐标值 |
+| right | number | 是 | Web 4.0 / 微信小程序 4.11 / Android 3.9 / iOS 4.11 / HarmonyOS 4.61 | 矩形的右坐标值 |
+| top | number | 是 | Web 4.0 / 微信小程序 4.11 / Android 3.9 / iOS 4.11 / HarmonyOS 4.61 | 矩形的顶坐标值 |
+| bottom | number | 是 | Web 4.0 / 微信小程序 4.11 / Android 3.9 / iOS 4.11 / HarmonyOS 4.61 | 矩形的底坐标值 |