tmui-cli 2.0.3 → 2.0.4

package/data/uni-app-x-docs/component/button.md

@@ -0,0 +1,105 @@
+<!-- ## button -->
+
+<!-- UTSCOMJSON.button.name -->
+
+<!-- UTSCOMJSON.button.description -->
+
+<!-- UTSCOMJSON.button.compatibility -->
+
+<!-- UTSCOMJSON.button.attribute -->
+
+<!-- UTSCOMJSON.button.event -->
+
+<!-- UTSCOMJSON.button.component_type-->
+
+<!-- UTSCOMJSON.button.children -->
+
+<!-- UTSCOMJSON.button.example -->
+
+<!-- UTSCOMJSON.button.reference -->
+
+## 样式修改 @style
+
+button 的 size、type 属性是预置样式，适合快速使用；如需修改文字、背景、边框、尺寸等样式，可直接在 button 组件上使用 style 或 class 覆盖。如需保持样式一致，建议不要依赖 type 的默认颜色。
+
+APP 蒸汽模式不支持属性选择器，建议使用 class 或 style 自定义样式。
+
+APP蒸汽模式、WEB 和微信小程序平台的 button 组件在 `plain` 为 `true` 时，通过 class 配置的 `background-color` 样式不生效，只能通过 style 设置。
+
+```html
+<template>
+	<button class="custom-button" hover-class="custom-button-hover">按钮</button>
+</template>
+
+<style>
+.custom-button {
+	color: #ffffff;
+	background-color: #1AAD19;
+	border-color: #1AAD19;
+}
+
+.custom-button-hover {
+	color: rgba(255, 255, 255, 0.6);
+	background-color: #179b16;
+	border-color: #179b16;
+}
+</style>
+```
+
+## 暗黑模式
+
+App平台蒸汽模式从 5.25+ 起内置适配 button 默认样式的暗黑模式。暗黑模式下，默认按钮背景色为 `#343434`，文字色为 `#d6d6d6`；按下时背景色为 `rgba(255, 255, 255, 0.1)`；禁用时背景色为 `rgba(255, 255, 255, 0.08)`，文字色为 `rgba(255, 255, 255, 0.2)`。
+
+暗黑模式下，默认镂空按钮背景色为 `transparent`，边框色和文字色为 `#353535`；镂空按钮按下时背景色为 `rgba(50, 50, 50, 0.2)`，边框色和文字色为 `rgba(150, 150, 150, 0.6)`；镂空按钮禁用时背景色为 `transparent`，边框色和文字色为 `rgba(255, 255, 255, 0.2)`。
+
+## hover-class 属性值
+
+button 按下后触发 hover-class 效果。点击态取消后的触发规则如下：
+
+- Android 平台：手指不松开并持续在屏幕上移动，离开 button 组件范围后，hover-class 效果消失。
+- iOS 平台：手指按下后，hover-class 效果会保持到手指抬起时消失。
+- 鸿蒙平台、Web 平台：手指移动一点后，即便未离开 button 范围，hover-class 效果也会消失。
+
+button 设置 hover-class 属性规则如下：
+
+- 如果 hover-class 属性值设置为 button-hover 或者不设置 hover-class 属性值，在 style 样式里面设置了同名的 button-hover 样式，点击效果将使用 button-hover 样式。
+- 如果 hover-class 属性值设置为无效值（或非法值），没有点击态效果。
+
+## 点击跳转
+
+button 组件没有 url 属性，点击后需要跳转页面时，可在 @click 中调用路由 API，也可以使用 [navigator](./navigator.md) 组件实现声明式跳转。
+
+```html
+<template>
+	<view>
+		<button @click="gotoAbout">跳转到 about 页面</button>
+		<navigator url="/pages/about/about" open-type="navigate">
+			<button>使用 navigator 跳转到 about 页面</button>
+		</navigator>
+	</view>
+</template>
+
+<script setup lang="uts">
+	function gotoAbout() {
+		uni.navigateTo({
+			url: '/pages/about/about'
+		})
+	}
+</script>
+```
+
+## 隐私协议授权
+
+`open-type="agreePrivacyAuthorization"` 用于开发者在让用户同意隐私协议时，放置“同意”按钮。它不是强制拦截能力，只是开发者和插件作者之间的一种通信方式；未点击该按钮，并不代表技术上会拦截涉及隐私的 API 调用。[详见](../api/privacy.md)
+
+## 文本显示
+
+- 如果 button 组件的文本内容包含 `\n`，VDOM 模式 APP 和 web 会被渲染为字符，不会换行，微信小程序会移除换行符号。蒸汽模式 APP 会移除 `\n` 旁的文字。
+- VDOM 模式 button 默认文字大小为 18px，文字行高为 2.5。自定义高度时，需要同步调整 line-height。
+- APP 蒸汽模式下，button 的文字居中依赖 padding。调整 height 和 line-height 时，建议同时将 padding-top、padding-bottom 设置为 0。
+
+```html
+<template>
+	<button style="height: 50px; line-height: 50px; padding-top: 0; padding-bottom: 0;">按钮</button>
+</template>
+```

package/data/uni-app-x-docs/component/camera.md

@@ -0,0 +1,54 @@
+<!-- ## camera -->
+
+<!-- UTSCOMJSON.camera.name -->
+
+<!-- UTSCOMJSON.camera.description -->
+
+<!-- UTSCOMJSON.camera.compatibility -->
+
+<!-- UTSCOMJSON.camera.attribute -->
+
+<!-- UTSCOMJSON.camera.event -->
+
+<!-- UTSCOMJSON.camera.component_type -->
+
+<!-- UTSCOMJSON.camera.children -->
+
+### 上下文对象API
+
+camera组件的操作api为[uni.createCameraContext()](../api/create-camera-context.md)。
+
+给camera组件设一个id属性，将id的值传入uni.createCameraContext()，即可得到camera组件的上下文对象，进一步可使用`.takePhoto()`、`.startRecord()`等方法。
+
+<!-- UTSCOMJSON.camera.example -->
+
+### 依赖库版本
+
+Android端实现相机组件所使用的依赖库
+
+```
+"androidx.camera:camera-core:1.4.1",
+"androidx.camera:camera-camera2:1.4.1",
+"androidx.camera:camera-lifecycle:1.4.1",
+"androidx.camera:camera-view:1.4.1",
+"androidx.appcompat:appcompat:1.7.0"
+```
+
+### 关于相机组件扫码能力的注意事项
+
+- Android/iOS平台 camera 组件仅在 uni-app x 项目中支持，扫码功能需更新到 HBuilderX4.71 及以上版本。
+- Android/iOS平台扫码功能是独立功能模块，需在 `manifest.json` 中勾选 “uni-barcode-scanning（相机组件扫码）”模块才能使用。
+  + [Android平台配置“uni-barcode-scanning（相机组件扫码）”](../collocation/manifest-android.md#modulesscan)
+  + [iOS平台配置“uni-barcode-scanning（相机组件扫码）”](../collocation/manifest-ios.md#modulesscan)
+
+
+### 关于预览画面与拍照尺寸的注意事项
+
+- camera 预览画面采用 FILL_CENTER（aspectFill）方式显示，会保持宽高比填满组件区域，超出部分居中裁剪。
+- `resolution`（预览）和 `photo-resolution`（拍照）是两个独立配置，系统分别协商实际分辨率，最终宽高比可能不同。
+- `takePhoto` 返回的是完整拍照画面，不会按预览可见区域裁剪，照片中可能包含预览中看不到的内容。
+- 不同设备支持的分辨率列表不同，预览与拍照的差异程度因设备而异。
+- 实现取景框裁剪时，需先根据 camera 组件显示宽高与照片实际宽高，按 FILL_CENTER 逻辑计算预览可见区域在照片中的对应范围，裁剪一致后再进行取景框二次裁剪。
+
+
+<!-- UTSCOMJSON.camera.reference -->

package/data/uni-app-x-docs/component/canvas.md

@@ -0,0 +1,163 @@
+<!-- ## canvas -->
+
+<!-- UTSCOMJSON.canvas.name -->
+
+<!-- UTSCOMJSON.canvas.description -->
+
+<!-- UTSCOMJSON.canvas.compatibility -->
+
+* 截图或海报需求，无需像webview那样通过canvas中转，app平台view直接提供截图API，[takesnapshot](../dom/unielement.html#takesnapshot)。
+
+在绘制形状、文字、图片方面，uni-app x有2种解决方案：`canvas组件`和 [DOM的DrawableContext API](../dom/drawablecontext.md)
+
+它们的区别是：
+1. canvas组件的语法是W3C标准语法；DrawableContext是对原生view的绘制API的封装，语法尽可能靠齐W3C规范，但不相同。
+2. canvas组件全平台支持，而DrawableContext仅app支持
+3. canvas组件是一个独立组件，而DrawableContext是对现有的view组件进行绘制
+4. DrawableContext在iOS上绘制文字的性能略低，其原生系统如此
+5. 对于复杂绘制场景，比如游戏，canvas组件的绘制速度优于DrawableContext；对于简单场景，canvas组件的内存占用高于普通view。
+6. canvas是一个独立模块，在Android和iOS平台占用几百K体积，鸿蒙平台封装自鸿蒙自身的canvas。canvas模块不使用时会被摇树摇掉
+
+<!-- UTSCOMJSON.canvas.attribute -->
+
+注意：Android平台默认会开启硬件加速无需额外设置
+
+<!-- UTSCOMJSON.canvas.event -->
+
+<!-- UTSCOMJSON.canvas.component_type-->
+
+<!-- UTSCOMJSON.canvas.children -->
+
+## API
+
+老版 uni-app 的 canvas 使用了微信小程序的旧版规范，和 W3C 规范有差异。微信小程序新版的 canvas 规范已经与 W3C 规范拉齐。
+
+uni-app x 中废弃了老版方案，使用了 W3C 规范和微信小程序的新版规范。
+
+注意：在uni-app x 4.21版以前，Web平台开发者写的老版canvas是可以运行的。但从 4.21+ 支持新版规范起，不再支持老版规范。开发者需调整代码。
+
+注意：新版规范需要开发者根据自己的场景手动处理高清屏问题。
+
+canvas相关的API较多，参考如下：
+
+- [W3C 规范](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/canvas)
+- canvas.toDataURL()  [W3C](https://developer.mozilla.org/zh-CN/docs/Web/API/HTMLCanvasElement/toDataURL)
+- uni.createCanvasContextAsync 获取[CanvasContext对象](../api/create-canvas-context-async.md)
+- [CanvasRenderingContext2D对象](../api/canvasrenderingcontext2d.md)
+- [动画帧](../api/animation-frame.md)
+
+## 获取组件上下文对象CanvasContext@CanvasContext
+
+1. 异步方式获取CanvasContext
+
+这种方式跨平台，一般推荐这种写法。需HBuilderX 4.25+支持。
+
+组合式
+
+```html
+<template>
+  <canvas id="canvas"></canvas>
+</template>
+<script setup>
+  onReady(() => {
+    // HBuilderX 4.25+
+    // 异步调用方式, 跨平台写法
+    uni.createCanvasContextAsync({
+      id: 'canvas',
+      component: getCurrentInstance().proxy,
+      success: (context : CanvasContext) => {
+        const canvasContext = context.getContext('2d')!;
+        const canvas = canvasContext.canvas;
+
+        // 处理高清屏逻辑
+        const dpr = uni.getDeviceInfo().devicePixelRatio ?? 1;
+        canvas.width = canvas.offsetWidth * dpr;
+        canvas.height = canvas.offsetHeight * dpr;
+        canvasContext.scale(dpr, dpr); // 仅需调用一次，当调用 reset 方法后需要再次 scale
+      }
+    })
+  })
+</script>
+```
+
+选项式
+
+```html
+<template>
+  <view>
+    <canvas id="canvas"></canvas>
+  </view>
+</template>
+
+<script>
+  export default {
+    name: 'canvas',
+    data() {
+      return {
+      }
+    },
+    onReady() {
+      uni.createCanvasContextAsync({
+        id: 'canvas',
+        component: this,
+        success: (context : CanvasContext) => {
+          const canvasContext = context.getContext('2d')!;
+          const canvas = canvasContext.canvas;
+
+          // 处理高清屏逻辑
+          const dpr = uni.getDeviceInfo().devicePixelRatio ?? 1;
+          canvas.width = canvas.offsetWidth * dpr;
+          canvas.height = canvas.offsetHeight * dpr;
+          canvasContext.scale(dpr, dpr); // 仅需调用一次，当调用 reset 方法后需要再次 scale
+        }
+      })
+    }
+  }
+</script>
+```
+
+文档[详见](../api/create-canvas-context-async.md)
+
+2. 同步方式CanvasContext
+
+需HBuilderX 4.21+支持。
+
+同步方式不支持小程序。仅App和web可以使用。
+
+```html
+<template>
+  <canvas id="canvas"></canvas>
+</template>
+<script setup>
+  onReady(() => {
+    // 同步调用方式，仅支持 app/web
+    const canvas = uni.getElementById("canvas") as UniCanvasElement
+    const context = canvas.getContext("2d")!;
+
+    // 处理高清屏逻辑
+    const dpr = uni.getDeviceInfo().devicePixelRatio ?? 1;
+    canvas.width = canvas.offsetWidth * dpr;
+    canvas.height = canvas.offsetHeight * dpr;
+    context.scale(dpr, dpr); // 仅需调用一次，当调用 reset 方法后需要再次 scale
+    // 省略绘制代码，和 w3c 规范保持一致
+  })
+</script>
+```
+
+<!-- UTSCOMJSON.canvas.example -->
+
+## 场景
+
+canvas有很多应用场景，插件市场有很多封装好的插件：
+
+* 图表需求：
+	在蒸汽模式下，npm上的echart for小程序等图表组件可以直接使用。\
+	插件市场也有uts版本：[echart](https://ext.dcloud.net.cn/search?q=chart&orderBy=Relevance&uni-appx=1)、[F2](https://ext.dcloud.net.cn/search?q=f2&orderBy=Relevance&uni-appx=1)
+* 二维码展示：[见插件市场](https://ext.dcloud.net.cn/search?q=%E4%BA%8C%E7%BB%B4%E7%A0%81&uni-appx=1)
+* 手写签名：[见插件市场](https://ext.dcloud.net.cn/search?q=%E7%AD%BE%E5%90%8D&orderBy=Relevance&uni-appx=1)
+* 抽奖转盘：[见插件市场](https://ext.dcloud.net.cn/search?q=%E8%BD%AC%E7%9B%98&orderBy=Relevance&uni-appx=1)
+* 刮刮卡：[见插件市场](https://ext.dcloud.net.cn/search?q=%E5%88%AE%E5%88%AE%E5%8D%A1&orderBy=Relevance&uni-appx=1)
+
+一些web平台的canvas插件，并没有适配uts。此时使用web-view中的canvas也是一种方案，uvue页面里的[web-view组件](./web-view.md)可以和uvue页面里的uts代码双向通信。
+
+<!-- UTSCOMJSON.canvas.reference -->

package/data/uni-app-x-docs/component/channel-live.md

@@ -0,0 +1,19 @@
+<!-- ## channel-live -->
+
+<!-- UTSCOMJSON.channel-live.name -->
+
+<!-- UTSCOMJSON.channel-live.description -->
+
+<!-- UTSCOMJSON.channel-live.compatibility -->
+
+<!-- UTSCOMJSON.channel-live.attribute -->
+
+<!-- UTSCOMJSON.channel-live.event -->
+
+<!-- UTSCOMJSON.channel-live.component_type -->
+
+<!-- UTSCOMJSON.channel-live.children -->
+
+<!-- UTSCOMJSON.channel-live.example -->
+
+<!-- UTSCOMJSON.channel-live.reference -->

package/data/uni-app-x-docs/component/channel-video.md

@@ -0,0 +1,19 @@
+<!-- ## channel-video -->
+
+<!-- UTSCOMJSON.channel-video.name -->
+
+<!-- UTSCOMJSON.channel-video.description -->
+
+<!-- UTSCOMJSON.channel-video.compatibility -->
+
+<!-- UTSCOMJSON.channel-video.attribute -->
+
+<!-- UTSCOMJSON.channel-video.event -->
+
+<!-- UTSCOMJSON.channel-video.component_type -->
+
+<!-- UTSCOMJSON.channel-video.children -->
+
+<!-- UTSCOMJSON.channel-video.example -->
+
+<!-- UTSCOMJSON.channel-video.reference -->

package/data/uni-app-x-docs/component/checkbox-group.md

@@ -0,0 +1,21 @@
+<!-- ## checkbox-group -->
+
+<!-- UTSCOMJSON.checkbox-group.name -->
+
+<!-- UTSCOMJSON.checkbox-group.description -->
+
+给checkbox-group设置name属性后，内部包含的多个checkbox将以数组的方式统一提交表单。详见[form](./form.md)
+
+<!-- UTSCOMJSON.checkbox-group.compatibility -->
+
+<!-- UTSCOMJSON.checkbox-group.attribute -->
+
+<!-- UTSCOMJSON.checkbox-group.event -->
+
+<!-- UTSCOMJSON.checkbox-group.component_type-->
+
+<!-- UTSCOMJSON.checkbox-group.children -->
+
+<!-- UTSCOMJSON.checkbox-group.example -->
+
+<!-- UTSCOMJSON.checkbox-group.reference -->

package/data/uni-app-x-docs/component/checkbox.md

@@ -0,0 +1,27 @@
+<!-- ## checkbox -->
+
+<!-- UTSCOMJSON.checkbox.name -->
+
+<!-- UTSCOMJSON.checkbox.description -->
+
+<!-- UTSCOMJSON.checkbox.compatibility -->
+
+<!-- UTSCOMJSON.checkbox.attribute -->
+
+<!-- UTSCOMJSON.checkbox.event -->
+
+<!-- UTSCOMJSON.checkbox.component_type -->
+
+<!-- UTSCOMJSON.checkbox.children -->
+
+### 支付宝小程序注意事项
+
+支付宝小程序不支持将文本或 `text` 组件放在 `checkbox` 组件内部。选项文本应与 `checkbox` 作为同级节点放置，通常可使用 `label` 包裹同级的 `checkbox` 和文本。
+
+### 暗黑模式
+
+App平台蒸汽模式从 5.25+ 起内置适配 checkbox 默认样式的暗黑模式。暗黑模式下，checkbox 背景色为 `#2c2c2c`，边框色为 `#656565`；选中时图标颜色为 `#007aff`；禁用时边框色为 `#373737`，图标颜色为 `#656565`。
+
+<!-- UTSCOMJSON.checkbox.example -->
+
+<!-- UTSCOMJSON.checkbox.reference -->