tmui-cli 2.0.3 → 2.0.4

package/data/uni-app-x-docs/tutorial/debug/devtools.md

@@ -0,0 +1,137 @@
+# uni-app x DevTools
+
+> `HBuilderX 5.25+` 支持。
+
+> uni-app x DevTools 目前支持 App 平台的蒸汽模式项目。
+
+uni-app x DevTools 是 HBuilderX 内置的 uni-app x 蒸汽模式运行时检查工具，界面和使用习惯与 Chrome DevTools 相近。它用于检查运行中 App 的元素、网络请求和存储。
+
+目前提供以下功能：
+
+1. 在 Elements 中查看页面、Element 和自定义组件组成的节点树，以及属性、组件 props、计算样式和盒模型。
+2. 在 Network 中查看通过 `uni.request`、`uni.uploadFile` 和 `uni.downloadFile` 发起的请求。
+3. 在 Storage 中查看和维护应用通过 uni Storage API 保存的数据。
+
+## 打开 DevTools
+
+使用 HBuilderX 将蒸汽模式项目运行到 Android、iOS 或鸿蒙设备。在运行控制台的右上角，点击 uni-app x DevTools 按钮。
+
+![](https://web-ext-storage.dcloud.net.cn/uni-app-x/devtools/devtools-control-panel-icon.png)
+
+HBuilderX 会打开独立的 DevTools 窗口。应用尚未连接时，窗口会显示等待连接状态；应用启动并建立连接后，窗口会自动进入检查界面。DevTools 窗口和应用没有固定的启动先后顺序。
+
+![](https://web-ext-storage.dcloud.net.cn/uni-app-x/devtools/devtools-waiting-connect.png)
+
+![](https://web-ext-storage.dcloud.net.cn/uni-app-x/devtools/devtools-connected.png)
+
+关闭 DevTools 窗口会同时结束本次检查会话。需要继续检查时，再次点击运行控制台中的 DevTools 按钮即可。
+
+## 查看页面和组件
+
+打开 **Elements** 标签，可以查看应用中当前可见页面的节点树。普通页面和用户打开的 `dialogPage` 都可以被检查；切换页面或打开、关闭 `dialogPage` 后，DevTools 会切换到当前可见页面。
+
+节点树会同时显示：
+
+- `<page>` 页面根节点。
+- `view`、`text`、`image` 等 Element。
+- 自定义组件。
+
+选择 Element 后，可以在右侧查看 Element 属性、计算样式和盒模型。选择自定义组件后，可以查看组件接收到的 props。`<page>` 节点的路由和页面配置也会显示在属性中。
+
+![](https://web-ext-storage.dcloud.net.cn/uni-app-x/devtools/devtools-elements.png)
+
+![](https://web-ext-storage.dcloud.net.cn/uni-app-x/devtools/devtools-component-props.png)
+
+右键点击节点可以使用以下操作：
+
+- **展开所有子节点**：递归展开该节点下的所有内容。
+- **收起子级**：收起该节点下已经展开的内容。
+- **在 HBuilderX 中打开**：打开页面或自定义组件对应的源码文件。该菜单只在能定位源码的页面和自定义组件节点上显示。
+
+![](https://web-ext-storage.dcloud.net.cn/uni-app-x/devtools/devtools-elements-context-menu.png)
+
+::: warning 当前限制
+Elements 当前使用页面快照，页面内新增、删除或修改节点后不会自动同步。请点击窗口左上角的刷新按钮查看最新内容。切换页面不需要手动刷新。
+
+Android、iOS 平台的 `view`、`text`、`image` 和 `scroll-view`，目前仅显示已设置的 `id` 和 `class` 属性，其他属性将在后续版本中完善。
+:::
+
+刷新后 DevTools 会按照节点路径恢复此前展开的内容。节点结构发生较大变化时，无法匹配的节点需要重新展开。
+
+Elements 当前仅用于查看，不支持修改 Element 属性、样式、文字或组件 props。
+
+## 查看网络请求
+
+打开 **Network** 标签后，在应用中执行网络请求，请求会出现在列表中。选择一条请求，可以查看 Headers、Payload、Preview、Response 和 Timing 等信息。
+
+![](https://web-ext-storage.dcloud.net.cn/uni-app-x/devtools/devtools-network.jpg)
+
+当前 Network 记录以下公开 uni API 发起的请求：
+
+- `uni.request`
+- `uni.uploadFile`
+- `uni.downloadFile`
+
+Network 展示的是调用公开 uni API 时可见的参数和结果，不是平台网络栈最终发出的完整报文。例如，GET 请求的 `data` 会显示在 Payload 中，不会由 DevTools 模拟平台规则拼接到 URL；平台自动补充的 Header、Cookie、重定向等信息也可能不在当前数据中。
+
+请求和响应正文仅在 Runtime 可以读取且未超过缓存限制时显示。二进制请求体、流式内容、超限内容或已经被释放的内容可能无法查看，但请求 URL、状态和基础耗时仍会保留。
+
+::: warning 当前限制
+Network 暂不支持 UTS 插件内部或平台原生代码绕过公开 uni API 发起的请求，也不会补录 DevTools 建立连接前已经完成的请求。
+:::
+
+## 查看和修改 Storage
+
+打开 **Storage** 标签，可以查看应用通过 uni Storage API 保存的数据。列表会显示 Key、Value 和 Type，其中 Type 可能为：
+
+- `string`
+- `number`
+- `boolean`
+- `null`
+- `array`
+- `object`
+
+![](https://web-ext-storage.dcloud.net.cn/uni-app-x/devtools/devtools-storage.jpg)
+
+通过公开 uni Storage API 新增、修改、删除或清空数据后，列表会自动更新。也可以点击窗口左上角的刷新按钮，重新读取完整 Storage 数据。
+
+Storage 支持以下操作：
+
+- 修改已有 Key 的 Value，数据类型保持不变。
+- 删除选中的数据。
+- 清空全部数据。
+
+编辑 `number`、`boolean`、`null`、`array` 或 `object` 时，输入内容必须符合原数据类型。输入无效时不会写入 Storage，界面会恢复平台实际保存的值。
+
+::: warning 当前限制
+Storage 暂不支持新建数据或修改 Key。UTS 插件内调用存储 API 后，列表不会实时更新，请点击左上角的刷新按钮手动刷新。插件使用的原生私有存储不属于 uni Storage，无法在此查看。
+:::
+
+## 常见问题
+
+### DevTools 一直显示等待应用连接
+
+请依次确认：
+
+1. 当前项目使用蒸汽模式，并运行到 Android、iOS 或鸿蒙 App。
+2. 使用标准基座或自定义调试基座运行应用，发行包不支持。
+3. 当前运行任务没有被停止，设备上的应用已经启动。
+4. HBuilderX 和设备连接正常。
+
+应用重新启动、热重载或从后台恢复后，DevTools 会自动重新连接。若仍未连接，可以关闭 DevTools 窗口后重新点击运行控制台中的 DevTools 按钮。
+
+### 页面内容变化后 Elements 没有更新
+
+页面内的 Element 变化目前不会自动同步，请切换到 Elements 标签，然后点击左上角的刷新按钮。页面路由切换和 `dialogPage` 显隐会自动更新，不需要手动刷新。
+
+### Network 中没有请求
+
+Network 只记录 DevTools 建立连接后，通过 `uni.request`、`uni.uploadFile` 或 `uni.downloadFile` 发起的请求。UTS 插件和原生代码发起的请求当前不会显示。
+
+### Storage 中没有最新数据
+
+公开 uni Storage API 产生的变化会自动同步。UTS 插件绕过公开 API 包装器写入数据时，请切换到 Storage 标签并点击左上角的刷新按钮。
+
+### 节点右键菜单中没有“在 HBuilderX 中打开”
+
+该菜单只对能够定位源码的页面和自定义组件显示，Element 不显示此菜单。

package/data/uni-app-x-docs/tutorial/idref.md

@@ -0,0 +1,126 @@
+# 组件标志
+
+开发者会遇到很多与组件标志有关的概念：id、ref、Element、NodeRef、context、ComponentPublicInstance...
+
+上述概念，其实都是为了给组件一个标记，通过标记拿到组件的上下文对象，然后操作这个对象的方法。
+
+但因为平台不同，制造了不同的概念。id在web和小程序中存在，NodeRef是小程序的概念、ref和ComponentPublicInstance是vue的概念。uni-app中这些皆而有之。
+
+我们以video为例，解释这些概念的相同和差别之处。
+
+## web开发中
+### 内置html标签
+html内置标签有id属性，通过document.getElmenetById("")可以返回一个Element。可以进一步调用Element的方法
+```html
+<video id="vid" src="uni.mp4"></video>
+<script>
+    document.getElementById("vid").play() //js写法
+	(document.getElementById("vid") as HTMLVideoElement).play(); //ts写法。只有HTMLVideoElement才有play方法
+</script>
+```
+
+### vue自定义组件@vuecomponent
+vue框架中组件有ref属性，选项式中通过this.refs可以返回一个组件实例ComponentPublicInstance，组合式则是定义一个同名的ref()变量。得到组件实例可以进一步调用组件的属性和方法。
+
+对于html内置元素，在web中一般不通过ref获取。ref更多是服务于自定义的vue组件。
+
+但在uni-app x中，ref获取内置组件时，App和Web平台得到的是UniElement。获取非内置组件才是vue组件实例。
+
+假使有一个vue组件，其有一个方法getSome()，那么用法是：\
+template区：
+```html
+<component1 ref="c1"></component1>
+```
+script区：
+```js
+this.$refs.c1.getSome() //js写法
+this.$refs["c1"].getSome() //与上一行等价
+(this.$refs["c1"] as ComponentPublicInstance).getSome() //ts或uts写法，必须明确类型才能调用其方法和属性
+```
+
+## 小程序中
+### 小程序内置组件
+小程序的内置组件有id属性，有多种方式获取组件上下文对象：
+1. 通过uni.createXXXContext来获取，比如uni.createVideoContext()
+template区：
+```html
+<video id="vid" src="uni.mp4"></video>
+```
+
+script区：
+```js
+uni.createVideoContext('vid').play()
+```
+
+2. 通过uni.createSelectorQuery()，传入选择器，拿到返回的NodesRef，然后再.context，异步获取到组件的上下文对象
+```js
+  uni.createSelectorQuery().select('.the-video-class').context(function(res){
+    console.log(res.context) // 节点对应的 Context 对象。如：选中的节点是 <video> 组件，那么此处即返回 VideoContext 对象
+  }).exec()
+```
+
+一般推荐使用第1种方法，也就是createXXContext方式。这种方式简洁并且可以跨平台。
+
+### vue自定义组件
+uni-app编译到小程序时，vue组件的用法与web相同，具体[见上](#vuecomponent)。
+
+## uni-app x中
+
+uni-app x中，web、小程序、vue这3类概念都支持，所以id、ref、Element、NodeRef、context、ComponentPublicInstance这些概念都存在。
+
+分为如下几类：
+
+### 内置组件
+内置组件都支持Element。
+
+为了与小程序api拉齐，也有部分组件同时支持context，如video。
+
+不涉及小程序api拉齐的一些组件未提供context，比如`<unicloud-db>`组件只有Element。
+
+#### Element方式
+
+uni-app x提供了[uni.getElementById](../api/get-element.md)等多种方法获取[Element](../dom/unielement.md)类型。
+
+通用的元素操作方法，比如getAttribute、setStyle，在Element上就可以操作。
+
+获取Element有很多方法，
+1. [uni.getElementById](../api/get-element.md)获取栈顶页面的元素（注意无法获取dialogPage页面的元素）
+2. [UniPage的getElementById](../api/get-current-pages.md#getelementbyid)获取指定页面的元素。通过`this.$page.getElementById`可以获取当前页面的元素。
+3. 还可以通过this.refs获取到vue实例然后as为Element。[见下](#ref方式)
+
+UniVideoElement 继承自 UniElement，拥有video专用的一批方法。
+
+template区：
+```html
+<video id="vid" src="uni.mp4"></video>
+```
+script区：
+```uts
+(uni.getElementById("vid") as UniVideoElement).play() //注意没有document对象，getElementById方法在uni下。务必确保vid存在，否则as会崩溃
+uni.getElementById<UniVideoElement>("vid")!.play() //泛型写法
+```
+
+#### context方式
+script区：
+```uts
+uni.createVideoContext("vid")!.play()
+```
+
+#### NodeRef方式
+uni-app x 虽然支持 `uni.createSelectorQuery()` API，传入选择器，可以拿到返回的NodesRef。但无法继续获取.context子对象。无法通过这种方式拿到context。
+
+#### ref方式
+
+其实`this.$refs`获取到的内置组件，通过as也可以转换为Element。
+
+与`uni.getElementById`相比，`this.$refs`方式与调用页面绑定。
+
+script区：
+```js
+(this.$refs['vid'] as UniVideoElement).play(); //但一般ref用于vue自定义组件
+```
+
+
+### vue自定义组件
+
+uni-app x中vue组件的用法与web相同，具体[见上](#vuecomponent)。

package/data/uni-app-x-docs/tutorial/ls-plugin.md

@@ -0,0 +1,186 @@
+# uni-app x语言服务插件
+
+`uni-app x语言服务`是为`uni-app x`项目提供的语言服务插件。
+
+[点击加入im官方交流群](https://im.dcloud.net.cn/#/?joinGroup=682c303383abe400024d38ba)
+
+适用于 cursor/vscode 等兼容vscode插件规范的IDE。
+
+开发者使用其他 AI IDE 时，也可以获得 uni-app x 的良好的语言服务支持。如需要AI Rules，另见[文档](./rules_mcp.md)
+
+## 如何安装插件@install
+插件目前在两个平台发布，vscode官方市场和open-vsx市场。
+* [vscode官方市场插件下载](https://marketplace.visualstudio.com/items?itemName=dcloud-ide.hbuilderx-language-services)。
+* [open-vsx市场插件下载](https://open-vsx.org/extension/dcloud-ide/hbuilderx-language-services)。
+
+你可以在vscode/cursor/Antigravity等IDE的插件搜索界面直接搜索“uni-app x语言服务”，找到圆形绿色U图标，且发布方为DCloud，直接安装。
+
+注意: `插件安装完成后，会提示重启编辑器，如果没有提示，需要手动重启编辑器`
+<br/> ![statusbar](https://web-ext-storage.dcloud.net.cn/doc/tutorial/lsp-plugin/install.png)
+
+## 插件功能范围@ability
+* 插件只支持`uni-app x`项目。
+* 插件仅支持语言服务，即代码高亮、代码提示、校验、格式化、转到定义。不支持运行、Debug、发行等功能，需要同时打开HBuilderX，协同工作。
+	因为vscode类插件API，无法定制运行控制台，所以uni-app x的运行仍然在HBuilderX中。
+	
+	从HBuilderX 4.71+，运行控制台的编译报错，尤其是uts类型报错，都可以在HBuilderX的运行控制台点击AI修复，[详见](./bug_repair.md)
+	
+	如果不想使用HBuilderX的AI修复，也可以对HBuilderX的控制台日志选择后点右键，生成AI提示词，此时会给选中的日志补充适合uni-app x的prompt，然后粘贴到cursor等工具中来修复。[详见](./bug_repair.md#获取提示词)
+
+
+### 关联文件类型和高亮支持@language
+支持uvue和uts文件的高亮
+* 打开uni-app x项目，打开一个.uvue/.uts文件，会自动关联对应的语言。
+* 如果第一次没有自动关联，请手动关联文件为uvue/uts。
+
+### 平台设置说明@targets
+uni-app x 项目有很多平台，每个平台都有大量的语法和API。尤其是Android、iOS、鸿蒙的系统API非常多。如果开启太多平台，会导致代码提示和校验变慢。
+
+所以uni-app x提供了平台语言服务配置。在底部状态栏可以选择使用的平台（默认是APP-ANDROID）。
+
+#### 平台信息注意事项特别说明
+* 平台设置一般和条件编译共同使用
+  * [条件编译详情](https://uniapp.dcloud.net.cn/tutorial/platform.html#preprocessor)
+  * [pages.json的条件编译支持](https://uniapp.dcloud.net.cn/tutorial/platform.html#pages-json-%E7%9A%84%E6%9D%A1%E4%BB%B6%E7%BC%96%E8%AF%91)
+  * 支持非选中平台的条件编译块置灰功能
+
+*注意：选择多个平台，会导致加载多套语言服务，影响内存占用和运行速度。如果只开发一个平台，推荐去掉其他平台的设置。*
+
+#### 语言服务平台设置@setting
+* 在uni-app x项目中，打开任意文件，即可在`状态栏`看到**语言服务平台信息**
+* **点击状态栏**可打开对应项目的**平台信息配置文件**，可进行修改
+<br/> ![statusbar](https://web-ext-storage.dcloud.net.cn/doc/tutorial/lsp-plugin/statusbar.png)
+* 目前只支持手动修改Target配置信息
+```json
+{
+    "targets": [
+        "APP-ANDROID",
+        "APP-IOS",
+        "APP-HARMONY",
+        "WEB",
+        "MP-WEIXIN"
+    ]
+}
+```
+
+
+### 语言服务功能说明
+* 注意: 语言服务的功能时刻与`条件编译`和`平台设置`相关
+#### 语言服务生效范围的规则
+##### 条件编译代码区域
+```js
+// #ifdef APP-ANDROID
+...
+// #endif
+```
+
+```js
+// #ifdef WEB
+...
+// #endif
+```
+
+在上述各条件编译的作用域中，各区域内只能提示各条件编译对应平台的专有提示项和各平台通用的提示项
+
+*例如：*
+在 `APP-ANDROID` 条件编译中可以提示`Android系统API`和`UNI API`。
+在 `WEB` 条件编译中可以提示`DOM API`和`UNI API`。
+*注意：如果取消了某平台的勾选，在此平台对应的条件编译代码区域中将没有任何代码提示*
+
+##### 非条件编译代码区域
+在非条件编译代码区域里，代码提示、语法校验则会以选择的平台为准（默认选择：APP-ANDROID）。
+
+#### 代码提示
+* 目前暂不支持`条件编译`的相关代码提示。
+* 可以提示uni相关的API和组件，并有详细的参数提示。
+<br/> ![completion](https://web-ext-storage.dcloud.net.cn/doc/tutorial/lsp-plugin/completion.png)
+
+
+#### 悬浮
+* 悬浮到uni相关的API和组件时，显示详细信息。
+<br/> ![hover](https://web-ext-storage.dcloud.net.cn/doc/tutorial/lsp-plugin/hover.png)
+
+
+#### 转到定义
+* 可以跳转到uni相关的API和组件的定义位置。
+
+#### 查找引用
+* 可以查找uni相关的API和组件的引用位置。
+<br/> ![ref](https://web-ext-storage.dcloud.net.cn/doc/tutorial/lsp-plugin/ref.png)
+
+#### 大纲
+* 可以在大纲中查看uni相关的API和组件的定义位置。
+<br/> ![outline](https://web-ext-storage.dcloud.net.cn/doc/tutorial/lsp-plugin/outline.png)
+
+#### 校验
+* 实时校验错误，在多平台设置的场景下效果较为明显。
+<br/> ![validation](https://web-ext-storage.dcloud.net.cn/doc/tutorial/lsp-plugin/validation.png)
+
+
+### 代码格式化
+目前语言服务插件没有内置格式化功能，推荐使用`prettier`进行代码格式化。具体如下
+
+#### 使用方法说明
+##### 必要条件
+* 安装`Prettier`插件
+  * 打开扩展管理界面。
+  * 搜索`Prettier - Code formatter`安装。
+
+* 在项目中安装`prettier`第三方库
+  * **由于vscode插件库中的`prettier`插件版本较低，无法使用`plugin`能力，所以还需要自行手动在项目中安装。**
+  * 进入项目根目录，运行`npm i prettier --save-dev`安装至开发环境中。
+
+##### 配置格式化设置项
+* 使用快捷键 Ctrl + Shift + P（Windows/Linux）或 Cmd + Shift + P（macOS）打开命令面板。
+* 输入 `Preferences: Open Settings (JSON)` 或 打开设置（JSON），然后回车。
+* 在打开的`settings.json`中，加入如下配置：
+```json
+{
+  "[uvue]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "prettier.documentSelectors": ["**/*.uvue", "**/*.uts"],
+  "prettier.requireConfig": true
+}
+```
+
+##### 添加prettier配置文件
+* 在项目根目录下新建`prettier-plugin-uts.js`文件，添加如下代码：
+```javascript
+const languages = [
+  {
+    name: "uts",
+    parsers: ["typescript"],
+    vscodeLanguageIds: ["uts"],
+  }
+];
+module.exports = { languages};
+
+```
+
+* 新建`.prettierrc`文件，添加如下配置：
+```json
+{
+  "plugins": [
+    "./prettier-plugin-uts.js"
+  ],
+  "overrides": [
+    {
+      "files": "*.uvue",
+      "options": {
+        "parser": "vue"
+      }
+    },
+    {
+      "files": "*.uts",
+      "options": {
+        "parser": "typescript"
+      }
+    }
+  ]
+}
+```
+保存后即可使用格式化功能。
+
+## 问题反馈
+* [点击加入im官方交流群](https://im.dcloud.net.cn/#/?joinGroup=682c303383abe400024d38ba)