tmui-cli 2.0.3 → 2.0.5

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

@@ -0,0 +1,321 @@
+# Android VDOM模式下的联网教程
+
+注意：在DCloud主推蒸汽模式后，页面中联网已经不再要求强类型了。本文仅适用于uts插件中通过uni.request联网，或在Android VDOM模式的页面中使用。不再适用于蒸汽模式的页面中的联网。
+
+在js环境中，服务器下发的字符串，通过uni.request获取后，会默认转成json对象，开发者可以通过`.操作符`获取对象的属性，绑定到界面上。
+
+```js
+// js写法
+// 假使服务器返回的json数据是：{code:0,data:[{"plugin_name":"插件名称A"}]}
+// 这是一个对象，拥有code、data这2个子属性，data属性的值是一个数组，该数组内又有若干子对象，子对象有属性`plugin_name`。
+uni.request({
+	url: "https://ext.dcloud.net.cn/plugin/uniappx-plugin-list",
+	success: (res) => {
+		let resData = res.data.data
+		console.log(resData[0].plugin_name) // resData是一个js对象数组，通过下标拿到第一个对象，然后通过.来访问对象的plugin_name属性
+	}
+})
+```
+
+但在uts等强类型语言中无法这样，会报resData[0]无法安全访问、没有plugin_name属性，因为resData是个可为空的any类型，你确实没有为它定义过任何属性。
+
+在uts中，提供了2种方案：
+1. 使用[UTSJSONObject](../uts/data-type.md#utsjsonobject)，不需要提前为json数据定义类型，运行时动态as转换类型
+2. 使用[type](../uts/data-type.md#type)，提前定义json数据类型，在request时通过泛型传入类型，拿到的就是一个有类型的对象，之后的用法和js一样
+
+其实在原生或标准的ts里，都是type（ts也有用interface的）。强类型里不能存在json对象这种可以用`.操作符`操作但又不提前定义属性的行为。
+
+UTSJSONObject 是 uni-app x 给原生生态引入了 js生态的一种 json数据处理方案。
+
+## 方式1：UTSJSONObject
+UTSJSONObject是uts的内置对象，可以用`.操作符`、下标和keypath来访问json数据。
+
+由于未提前定义类型，使用.或下标，都需要通过as来声明具体的类型，才能进一步使用。
+uni-app x 4.41起也支持`.操作符`，其实是把`.操作符`转成了下标。返回值类型为any。再次使用时需 as 为具体的类型。
+### UTSJSONObject下标方式
+```ts
+// uts写法
+// 假使服务器返回的json数据是：{code:0,data:[{"plugin_name":"插件名称A"}]}
+uni.request({
+	url: "https://ext.dcloud.net.cn/plugin/uniappx-plugin-list",
+	success: (res) => {
+		console.log(res.data) // 这是一个any类型，不能直接使用
+		console.log(res.data as UTSJSONObject) // 需要把这个any类型，as成UTSJSONObject类型
+		console.log(res.data as UTSJSONObject["data"]) //UTSJSONObject支持通过下标访问属性data，但返回的仍然是any类型
+		let resData = (res.data as UTSJSONObject)["data"] as UTSJSONObject[] // as成UTSJSONObject数组
+		if (resData!=null) {
+			console.log(resData[0]) // 访问数组的第一个数组项目，仍然是any类型，仍然需要转换
+			console.log((resData[0] as UTSJSONObject)["plugin_name"]) // 转为UTSJSONObject后通过下标访问plugin_name属性
+		}
+	}
+})
+```
+
+上面代码中打印日志部分是为了方便初学者理解，实际开发时代码行数不会多几行，主要是多几次as做类型转换。
+
+### UTSJSONObject keypath方式
+上面的写法是每层数据都as，通过下标来访问。UTSJSONObject还支持keypath，这是一种可穿透多层数据访问的写法，传入一个path字符串，返回相应数据。
+```ts
+// uts写法
+// 假使服务器返回的json数据是：{code:0,data:[{"plugin_name":"插件名称A"}]}
+uni.request({
+	url: "https://ext.dcloud.net.cn/plugin/uniappx-plugin-list",
+	success: (res) => {
+		let resData = res.data as UTSJSONObject
+		if (resData!=null) {
+			console.log(resData.getString("data[0].plugin_name")) //直接访问data属性的第一个数组项目里的plugin_name属性
+		}
+	}
+})
+```
+
+除了getString，还有getNumber、getBoolean、getJSON、getArray、getAny。只要keypath的路径输入正确、类型正确，就可以取得值。当然path没有代码提示。
+
+更多详见[UTSJSONObject](../uts/data-type.md#utsjsonobject)
+
+## 方式2：type和泛型
+
+为json数据定义一个type的自定义类型，明确好对象的属性名称及类型，然后把这个type通过泛型传给request方法，res拿出来的就是转换好的类型，就可以直接`.操作符`获取属性了。
+
+- 第一步：用HBuilderX自带的工具，给服务器数据定义类型
+把服务器端返回的data里的json数据，复制黏贴到HBuilderX的json编辑器里，点右键，转type。
+![](../static/json2type.png)
+
+> 转换功能需要HBuilderX 3.9+、安装了uni-app x真机运行插件、且打开的标签卡是json编辑器。（在ctrl+t新建空白md标签卡，粘贴json数据，会自动切换成json编辑器）
+
+上面的截图是复用了其他图片，如果我们使用`https://ext.dcloud.net.cn/plugin/uniappx-plugin-list`这个服务器接口，服务器返回的数据内容，也就是`res.data`的数据是这样：
+```json
+{code:200,desc:"",data:[{"plugin_name":"插件名称A","plugin_id":123}]}
+```
+
+**注意：** 不要把res和res.data搞错了，要看`res.data`的数据格式，而不是`res`的格式。`res`的格式是不变的。
+
+观察返回的数据，`res.data`返回一个对象，拥有code、desc、data这3个子属性，code是number类型，desc是string类型，而data的类型又是一个数组。
+该数组内又是若干子对象，子对象有属性`plugin_id`和`plugin_name`等。
+
+那么使用转换工具，生成的类型定义是这样：
+```ts
+type Data = {
+	plugin_id: number;
+	plugin_name: string;
+}
+type IRootType = {
+	code: number;
+	desc: string;
+	data: Data[];
+}
+```
+
+因type不可嵌套，生成了2个type。注意顺序，Data这个type需写在前面，因为后面要引用它。引用代码执行时如未定义该类型，会报错。
+
+- 第二步：把这段类型定义放在`<script setup>`根下，并确保定义在使用它的代码之前。然后给uni.request传入泛型参数`<IRootType>`，返回的res.data自动转换好了类型，可以直接`.`属性了。
+
+**注意：** 因为`res.data`是对象，所以泛型那里直接使用`<IRootType>`。有的服务器接口返回的`res.data`是数组，就需要在泛型那里写成`<IRootType[]>`
+
+```vue
+<script setup lang="uts">
+	type Data = {
+		plugin_id : number;
+		plugin_name : string;
+	}
+	type IRootType = {
+		code : number;
+		desc : string;
+		data : Data[];
+	}
+
+	onLoad(() => {
+		uni.request<IRootType>({ // 通过<IRootType>要求request方法的返回值转为IRootType类型
+			url: "https://ext.dcloud.net.cn/plugin/uniappx-plugin-list",
+			success: (res) => {
+				console.log(res.data)
+				console.log(res.data instanceof IRootType) //true res.data已经被转换为type了
+				console.log(res.data?.data) //因为联网数据不可控，转换可能失败，所以这里需要用?.的方式做安全访问
+				let resData = res.data?.data
+				if(resData!=null && resData.length>0){ //判断一下数组不为空
+					console.log(resData[0])
+					console.log(resData[0].plugin_name)
+				}
+		}})
+	})
+</script>
+```
+
+与UTSJSONObject方式相比，type方式在使用数据时可以使用`.操作符`，有代码提示。虽然需要定义type，但也有工具可以自动生成type。
+
+type+泛型这个方式，也是ts开发者惯用的方式。
+
+但不熟悉ts的开发者，可能不了解type和泛型。下面讲解下。
+
+### type和泛型详解
+
+- 什么是type和泛型？
+
+type就是自定义一个类型。下面定义了一个数据类型DataType，该类型有2个属性，`plugin_id`和`plugin_name`，这2个属性的类型分别是number和string。
+```ts
+type DataType = {
+	plugin_id : number,
+	plugin_name : string
+}
+```
+
+有了这个类型，再给它json数据进行实例化，就达到了给json数据定义类型的目标。给json数据定义好类型，就可以自由的使用`.操作符`获取属性了。
+
+详见[type](../uts/data-type.md#type)
+
+而泛型，是一个对方法参数进行通用的类型描述。它告诉一个支持泛型的方法，给方法传入什么类型，方法就会返回什么类型。
+
+不过uts的泛型支持还没有达到ts的泛型完善度，详见[泛型](../uts/generics.md)
+
+uni.request方法是支持泛型的，这意味着返回结果可以有很多种类型。
+
+所以可以把你定义的DataType类型通过`<T>`的方式传给uni.request方法，尖括号要写在方法名和左圆括号中间。
+这个方法就会把返回的`res.data`转换为你传入的DataType类型。
+
+- 为何type要定义在使用位置之前？
+
+UTS不存在声明提升，type需要先声明、后使用。实际开发中，type常用于响应式数据的类型定义，因此应写在创建`ref`等状态的代码之前。
+
+- 网络数据缺少一些属性怎么办？
+
+网络返回的数据，有可能缺少某些属性，导致报错。测试需要把可为空的属性类型声明为"或null"，或者使用`?:`
+```ts
+type DataType = {
+	plugin_id : number,
+	plugin_name : string,
+	age : number | null, //属性可为null
+}
+```
+
+如您不了解null的安全使用，[详见](../uts/data-type.md#null)
+
+- 务必注意res.data返回的是对象还是数组
+
+如果res.data返回的是对象，那么泛型调用时直接`uni.request<IRootType>(`
+
+如果res.data返回的是数组，那么传泛型时必须传入数组格式`uni.request<IRootType[]>(`，注意多了一个`[]`
+
+- type的敏感词转义
+
+服务器返回的json数据，其属性键名有可能存在一些type不支持的字符。
+
+比如`{"a:b":"123","a-b":"456"}`，这些键名对于type来讲都是非法的。转换type就会失败。
+
+HBuilderX的json转type工具，会对一些敏感符合和关键字自动转义。但也有无法转移的符号和词，详见：[type](../uts/data-type.md#json-field)
+
+如果你的服务器数据涉及这类问题且数据格式不可改，那只能改用UTSJSONObject方式。
+
+### 完整实例
+
+再举一个实际中更常见的例子。联网获取插件市场的插件列表数据，并绑定在模板上，还可以翻页。
+
+翻页需要用到[...展开操作符](../uts/operator.md#展开语法)
+
+```vue
+<template>
+	<list-view style="flex: 1;background-color: #ffffff;" @scrolltolower="loadData">
+		<template v-for="(item, index) in dataList" :key="index">
+			<list-item style="flex-direction: row; margin-top: 10px; padding: 10px; height: 100px;">
+				<image :src="item.plugin_img_link" style="width: 120px;"></image>
+				<text style="flex: 1;">{{item.plugin_name}}</text>
+			</list-item>
+			<list-item key="loading" v-if="index==dataList.length-1">
+				<text style="padding: 10px; text-align: center; background-color: #f8f8f8; margin-bottom: 1px;">{{loadingText}}</text>
+			</list-item>
+		</template>
+	</list-view>
+</template>
+
+<script setup lang="uts">
+	type Data = {
+		plugin_id : number;
+		plugin_name : string;
+		plugin_img_link : string;
+		plugin_intro : string;
+		is_paid : number;
+		collection_count : number;
+		support_count : number;
+		buy_count : number;
+		download_count : number;
+		score : number;
+		rater_count : number;
+		tags : string[];
+		category_level1_name : string;
+		category_level2_name : string;
+		update_date : string;
+		author_avatar_link : string;
+		author_name : string;
+	}
+
+	type IRootType = {
+		code : number;
+		desc : string;
+		data : Data[];
+	}
+
+	const dataList = ref<Data[]>([])
+	const loading = ref(false)
+	const isEnded = ref(false)
+	const loadingError = ref('')
+	let currentPage = 1
+
+	const loadingText = computed(() : string => {
+		if (loading.value) {
+			return "加载中..."
+		} else if (isEnded.value) {
+			return "没有更多了"
+		} else if (loadingError.value.length > 0) {
+			return loadingError.value
+		} else {
+			return ""
+		}
+	})
+
+	const loadData = () => {
+		if (loading.value || isEnded.value) {
+			return
+		}
+		loading.value = true
+
+		uni.request<IRootType>({
+			url: "https://ext.dcloud.net.cn/plugin/uniappx-plugin-list",
+			data: {
+				page: currentPage, //当前页码
+				page_size: 10 //每页列表项目数量
+			},
+			success: (res) => {
+				const responseData = res.data
+				if (responseData == null) {
+					return
+				}
+
+				//...是展开运算符，本句用于把联网获取的数组合并到data数组里。当第一次执行时，dataList为空，push进去了第一页的数据，后续页面也同理
+				dataList.value.push(...responseData.data)
+
+				if (responseData.data.length == 0) {
+					isEnded.value = true
+				} else {
+					currentPage++
+				}
+			},
+			fail: (err) => {
+				loadingError.value = err.errMsg
+			},
+			complete: () => {
+				loading.value = false
+			}
+		})
+	}
+
+	onLoad(() => {
+		loadData()
+	})
+</script>
+
+```
+
+## 注意事项
+
+* request 接口内部通过[特殊方式读取了泛型类型](../uts/generics.md#使用限制)，不支持传入动态的泛型：比如将外层方法的普通泛型参数传入 request。所以目前尽量直接使用uni.request而不是封装。如确需封装，可不使用type，改用UTSJSONObject。
+* 4.01及之后版本web端request接口在dataType为`json`时返回UTSJSONObject，此前为普通js对象。
+* web端request接口目前不支持创建传入的泛型的实例，即泛型仅作为类型校验使用。

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

@@ -0,0 +1,123 @@
+# AI Rules 和 MCP
+
+AI工具大都支持自定义规则来让AI更好的理解项目背景、编码风格、语言和框架的规范要求，从而生成更符合预期的代码。
+
+uni-app x使用的uts语言、ucsss样式，和ts、css有差异。我们已经将这些差异和使用注意事项列在AI Rules中，让AI工具可以更好的生成uni-app x代码。
+
+打开[Git地址](https://gitcode.com/dcloud/uni-app-x-ai-rules)，其中有各种AI工具的配置。
+
+## Cursor
+复制上述项目中的[.cursor](https://gitcode.com/dcloud/uni-app-x-ai-rules)目录到uni-app-x项目根目录下。则cursor在该项目下生成代码时会遵守这些规则。
+
+这些规范在若干mdc文件中，里面描述了uni-app x的各种使用规则。开发者也可以自定义调整规则。
+
+## Vscode-Copilot
+复制[.github](https://gitcode.com/dcloud/uni-app-x-ai-rules)目录到uni-app-x项目根目录下[参考](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot?tool=vscode)
+
+## Trae
+复制[.trae](https://gitcode.com/dcloud/uni-app-x-ai-rules)目录到uni-app-x项目根目录下
+
+## Google Antigravity
+复制[.agent](https://gitcode.com/dcloud/uni-app-x-ai-rules)目录到uni-app-x项目根目录下
+
+## Claude Code
+复制[.claude](https://gitcode.com/dcloud/uni-app-x-ai-rules)目录到uni-app-x项目根目录下
+复制[.mcp.json](https://gitcode.com/dcloud/uni-app-x-ai-rules)文件到uni-app-x项目根目录下
+
+## Codex
+复制[AGENTS.md](https://gitcode.com/dcloud/uni-app-x-ai-rules/blob/main/AGENTS.md)文件到uni-app-x项目根目录下，Codex会默认读取该文件作为项目规则。
+
+复制[.codex](https://gitcode.com/dcloud/uni-app-x-ai-rules/tree/main/.codex)目录到uni-app-x项目根目录下。其中`.codex/config.toml`已经包含项目级配置和MCP配置。
+
+## 使用mcp
+
+> uni-app-x-mcp兼容uni-app项目，在uni-app项目中同样可以使用
+
+uni-app-x-mcp可以让你和AI交互的过程中自动把项目中的组件信息提供给AI，从而让AI在生成代码、修复bug时更加准确。
+
+目前MCP的功能是告知 AI，当前项目下有哪些easycom组件。当开发者需要让AI按照项目下已经可用的组件来生成代码时，AI需要知道项目下有哪些可用组件，本MCP就会告诉AI可用组件清单。
+
+#### 1、下载mcp包
+```bash
+$ npm i @dcloudio/uni-app-x-mcp -g
+```
+
+#### 2、使用MCP
+
+- 在Cursor中使用
+
+在项目根路径创建.cursor/mcp.json文件，文件内容如下
+```json
+{
+    "mcpServers": {
+        "uni-app-x": {
+            "command": "npx",
+            "args": [
+                "@dcloudio/uni-app-x-mcp"
+            ]
+        }
+    }
+}
+```
+
+- 在Vscode中使用[参考](https://docs.github.com/en/copilot/customizing-copilot/extending-copilot-chat-with-mcp)
+
+
+在项目根路径创建.vscode/mcp.json文件，文件内容如下
+
+```json
+{
+    "inputs": [
+        {
+            "type": "promptString",
+            "id": "mcp:projectPath",
+            "description": "Enter the projectPath",
+        }
+    ],
+    "servers": {
+        "uni-app-x": {
+            "command": "npx",
+            "args": [
+                "@dcloudio/uni-app-x-mcp"
+            ]
+        }
+    }
+}
+```
+
+- 在Trae中使用
+
+目前trae官方并没有支持在.trae目录中配置mcp.json，官方提供了手动配置方式，是配置在全局的， 但[mcp.json](https://gitcode.com/dcloud/uni-app-x-ai-rules/blob/main/.trae/mcp.json)的内容是一样的，可以直接使用。[trae中如何使用mcp](https://docs.trae.com.cn/ide/model-context-protocol)
+
+- 在Claude Code中使用
+
+```sh
+claude mcp add --transport stdio uni-app-x-mcp --scope project  -- npx -y @dcloudio/uni-app-x-mcp
+```
+
+- 在Codex中使用
+
+复制[.codex](https://gitcode.com/dcloud/uni-app-x-ai-rules/tree/main/.codex)目录到uni-app-x项目根目录下后，Codex会读取`.codex/config.toml`中的MCP配置：
+
+```toml
+[mcp_servers.uni-app-x]
+command = "npx"
+args = ["-y", "@dcloudio/uni-app-x-mcp"]
+```
+
+然后在项目根目录启动Codex即可。
+
+
+#### 3、Cursor默认启动MCP服务
+- 点击cursor setting -> 点击MCP
+- 会出现一个MCP列表，选择自己需要启动MCP就行(默认是关闭状态)
+![](https://web-ext-storage.dcloud.net.cn/hx/doc/D52E7A18-70BA-4C0F-A8AC-24AE8B8AB5DB.png)
+- vscode的设置可以[参考](https://docs.github.com/en/copilot/customizing-copilot/extending-copilot-chat-with-mcp)
+
+ps: 默认需要自己点击是否使用MCP服务，也可以设置为自动代理的方式[文档](https://docs.cursor.com/chat/agent#yolo-mode)
+
+#### 4、使用方式
+
+话术: 帮我使用项目中的组件来完善当前页面/帮我使用项目中的组件完善当前xxx
+
+![](https://web-ext-storage.dcloud.net.cn/hx/doc/A5961A5A-1A66-4943-A222-C5A936A5561B.png)

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

@@ -0,0 +1,68 @@
+# 复杂列表开发指南
+
+常见app有很多复杂列表交互效果。本文由浅入深的进行讲解。
+
+## 长列表需要使用recycle机制
+
+uni-app x的滚动视图组件有scroll-view和list-view。scroll-view比较灵活，但没有自带recycle复用机制。
+
+它们的区别详见[长列表性能](../performance.md#长列表)
+
+## 列表的左右滑动swiper@swiper
+Android App常见的一种列表效果，是顶部有一个tab，可以左右滑动切换不同的列表。也就是swiper-list。
+
+此时页面结构如下：顶部一个tab组件，下面是一个swiper组件，每个swiper-item中放入一个list-view。
+
+这个效果，在hello uni-app x有几个例子：
+- [tab为下划线方式的swiper](https://gitcode.com/dcloud/hello-uni-app-x/blob/master/pages/template/swipe-tabs-underline/swipe-tabs-underline.uvue)
+- [tab为字体放大方式的swiper](https://gitcode.com/dcloud/hello-uni-app-x/blob/master/pages/template/swipe-tabs-scale-highlight/swipe-tabs-scale-highlight.uvue)
+上面2个是比较简单的样例，没有实际放入数据的列表。
+
+下面的例子是实际放入数据的swiper-list，但这2个列表除了所有滑动，还加入了吸顶和nested嵌套。这些后面章节会详细讲述。
+- [表头吸顶的可左右滑动长列表](https://gitcode.com/dcloud/hello-uni-app-x/blob/master/pages/template/banner-tabs-long-list-nested-scroll/banner-tabs-long-list-nested-scroll.uvue)
+
+## 吸顶sticky@sticky
+吸顶，在web里是一个css属性，但相比原生不太灵活。
+
+在uni-app x中吸顶有3种做法。
+
+### 1. 监听滚动事件，调用element的transform，设置一个view的top始终固定在一个位置，不跟随滚动。从而实现吸顶效果。
+
+得益于uni-app x的没有通信性能问题，上述做法也可以流畅实现。
+
+源码见：[scroll-view吸顶](https://gitcode.com/dcloud/hello-uni-app-x/blob/master/pages/template/scroll-view-sticky-section/scroll-view-sticky-section.uvue)
+
+### 2. 使用sticky-header组件
+
+上面那种始终固定top的做法，在scroll-view里可以实现，但在list-view里有问题。因为list-view底层是有复用，有一些特殊限制。
+
+在list-view中，吸顶需要使用[sticky-header组件](../component/sticky.md)。
+
+sticky-header组件是list-view的一级子组件，在这个吸顶组件中放入内容，该组件滚动到列表顶部时将不再继续向上滚动、固定在列表顶端；但向下滚动时可以自由滚动，甚至滚动出屏幕之外。
+
+源码见：[列表到详情](https://gitcode.com/dcloud/hello-uni-app-x/blob/master/pages/template/news-feed-list/news-feed-list.uvue)
+
+上述页面中，整个页面就是一个list-view，包括顶部的banner、中间的表头和下面的list-item。中间的表头放在sticky-header组件中以实现吸顶效果。
+
+sticky-header还有一个配套组件sticky-section，组合它们可以实现分段吸顶，比如通讯录的字母分段吸顶或多店铺购物车的分段吸顶。
+
+### 3. 吸顶的第三种方式：嵌套滚动
+
+scroll-view作为父容器时，可以和子滚动容器（子scroll-view或子list-view）进行嵌套，并且可以协商嵌套滚动的逻辑。
+
+这种方式，当子容器滚动时，可以通知父容器：现在要滚动了，你打算怎么处理，是跟着一起滚、还是滚动一点、还是不动。
+
+如果父的逻辑是滚动到一定条件后就不再滚动了，那么感受上达到了吸顶的效果。但其实代码逻辑并不是吸顶。
+
+本章节主要是讲述吸顶的做法，具体的嵌套滚动详述见下一章节。
+
+## 嵌套滚动nested@nested
+
+嵌套滚动，nested，是手机os原生提供的一种强大能力。在较小的屏幕空间里，可以充分编程实现某些内容的显示和滚出屏幕外。
+
+scroll-view作为父容器时，可以和子滚动容器（子scroll-view或子list-view）进行嵌套，并且可以协商嵌套滚动的逻辑。
+
+这块有详情教程，本文就不再重复。[详见](../component/scroll-view.md#nested)
+
+以下2个都是嵌套滚动的示例。在可左右滑动的列表中，由于list-view被嵌入swiper中，想在父容器实现复杂效果，大多要使用嵌套滚动。
+- [表头吸顶的可左右滑动长列表](https://gitcode.com/dcloud/hello-uni-app-x/blob/master/pages/template/banner-tabs-long-list-nested-scroll/banner-tabs-long-list-nested-scroll.uvue)

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

@@ -0,0 +1,161 @@
+# 全局变量与状态管理
+
+全局变量，如果不需要绑定在界面上，可以使用 [globalData](../collocation/app.md#globaldata)
+
+如果需要绑定在界面上，也就是需要响应式，就涉及状态管理。
+
+uni-app x下可选方案有：
+
+1. 在独立的uts文件中定义一个全局的reactive变量，各处引用它。
+2. 引入pinia。蒸汽模式下可直接使用pinia官方库。Android vdom模式下需使用三方插件 [Pinia by uts](https://ext.dcloud.net.cn/plugin?name=x-pinia-s)
+
+从 HBuilderX 5.25 起，uni-app x 项目的 `pinia` 升级到了 `3.0.4` 版本。如希望使用其他版本，可在项目根目录自行安装指定版本。
+
+APP 蒸汽模式、鸿蒙和 iOS VDOM 模式、Web平台、小程序平台可以直接使用 `pinia` 官方库。
+
+## Pinia
+
+在 `main.uts` 中引入并挂载 Pinia：
+
+```ts
+import App from './App.uvue'
+import { createSSRApp } from 'vue'
+import { createPinia } from 'pinia'
+
+export function createApp() {
+  const app = createSSRApp(App)
+  app.use(createPinia())
+
+  return {
+    app
+  }
+}
+```
+
+定义一个 Store，比如 `store/counter.uts`：
+
+```ts
+import { computed, ref } from 'vue'
+import { defineStore } from 'pinia'
+
+export const useCounterStore = defineStore('counter', () => {
+  const name = ref('Pinia')
+  const count = ref(0)
+
+  const doubleCount = computed(() : number => {
+    return count.value * 2
+  })
+
+  const countText = computed(() : string => {
+    return `${name.value}: ${count.value}`
+  })
+
+  const increment = () => {
+    count.value++
+  }
+
+  const decrement = () => {
+    count.value--
+  }
+
+  const rename = () => {
+    name.value = name.value == 'Pinia' ? 'Pinia Store' : 'Pinia'
+  }
+
+  const reset = () => {
+    name.value = 'Pinia'
+    count.value = 0
+  }
+
+  return {
+    name,
+    count,
+    doubleCount,
+    countText,
+    increment,
+    decrement,
+    rename,
+    reset
+  }
+})
+```
+
+页面中使用 Store：
+
+```vue
+<template>
+  <view>
+    <text>name: {{ name }}</text>
+    <text>count: {{ count }}</text>
+    <text>double count: {{ doubleCount }}</text>
+    <text>count text: {{ countText }}</text>
+
+    <button @click="increment">increment</button>
+    <button @click="decrement">decrement</button>
+    <button @click="rename">rename</button>
+    <button @click="reset">reset</button>
+  </view>
+</template>
+
+<script setup lang="uts">
+import { storeToRefs } from 'pinia'
+import { useCounterStore } from '@/store/counter.uts'
+
+const counterStore = useCounterStore()
+const { name, count, doubleCount, countText } = storeToRefs(counterStore)
+
+const increment = () => {
+  counterStore.increment()
+}
+
+const decrement = () => {
+  counterStore.decrement()
+}
+
+const rename = () => {
+  counterStore.rename()
+}
+
+const reset = () => {
+  counterStore.reset()
+}
+</script>
+```
+
+## 全局reactive变量
+定义一个模块，编写一个单独的uts文件，比如 /store/index.uts，在里面设一个全局变量，比如globalNum。
+
+```ts
+//定义一个大写的State类型
+export type State = {
+  globalNum: number
+  // 如有需要，可增加更多属性
+}
+// 实例化为state
+export const state = reactive({ globalNum: 0 } as State)
+// 定义修改属性值的方法
+export const setGlobalNum = (num: number) => {
+  state.globalNum = num
+}
+```
+
+在需要的页面和uts文件里，import上面的/store/index.uts，通过如下方式读和写globalNum。
+
+```vue
+<template>
+	<text @click="plus">{{ globalNum }}</text>
+</template>
+
+// 组合式 API
+<script setup lang="uts">
+	import { state, setGlobalNum } from '@/store/index.uts'
+
+	const globalNum = computed(() => state.globalNum)
+
+	const plus = () => {
+		setGlobalNum(state.globalNum + 1)
+	}
+</script>
+```
+
+不管在哪里修改了globalNum的值，界面上都会自动更新。