tmui-cli 2.0.3 → 2.0.4

package/data/uni-app-x-docs/web/README.md

@@ -0,0 +1,279 @@
+# 编译到web端
+
+> 新增于4.0版本
+
+- 与App版相比，web版有几个较大的差别：
+1. web版是一个spa的单页应用，而app是多页的。
+2. pages.json配置的导航栏和tabbar，在web端并非原生的，而是网页的一部分。虽然uvue页面仍然是在导航栏和tabbar之间的，但在web平台，开发者可以直接操作导航栏和tabbar的dom。
+
+web版默认有页面滚动；app平台vdom模式时没有页面滚动，但蒸汽模式时已经支持页面滚动了。所以从蒸汽开始，这点平台差异不再存在。
+
+- 与老uni-app x相比，uni-app x 编译到web平台时，有几处不同：
+1. 如果使用uts代码，会走uts2js逻辑，会注入UTSJSONObject。如果使用ts/js则无法使用UTSJSONObject。
+2. 重置了css，拉齐App布局引擎，比如统一使用flex布局。详见[css重置](../css/README.md#css-reset)
+
+## web运行失败注意事项@faq
+
+- 在比较早的HBuilderX版本中创建的uni-app x项目，特征是项目根目录是app.vue而不是app.uvue。这样的项目运行web会失败。需替换index.html和app.uvue这2个文件，可以新建项目从中复制，也可以从hello uni-app x示例项目复制。
+
+## vue
+
+### 特性支持情况
+
+uni-app x编译到web端时遵循vue规范，目前有部分vue特性暂不支持。
+
+不支持的特性如下
+
+- 指令：`v-once`、`v-memo`
+
+### refs@refs
+
+使用ref获取内置组件实例时会获取到对应的Element，而不是vue组件实例。
+
+```vue
+<template>
+  <view ref="viewRef"></view>
+</template>
+<script setup>
+const viewRef = ref<UniElement | null>(null)
+onMounted(() => {
+  console.log(viewRef.value) // 此时获取到的是UniElement
+})
+</script>
+```
+
+### vue实例相关属性类型问题
+
+> 如下选项式示例仅为演示部分类型问题。组合式下通常不需要这样获取$props、$data、$refs等属性，直接使用defineProps、ref、reactive即可，无类型问题。
+
+为保证运行性能，app安卓端vdom模式部分属性（如：$data、$refs）被转为了Map类型（安卓端map支持使用下标访问），而web端仍是普通对象或proxy。为保证多端代码一致，在使用这些属性时可以统一为下标访问。
+
+```vue
+<template>
+  <view></view>
+</template>
+<script setup>
+const ins = getCurrentInstance()!.proxy
+const props = defineProps({
+	name: {
+		type: String,
+		default: 'default name'
+	}
+})
+onMounted(() => {
+	console.log(ins!.$props['name'])
+})
+</script>
+```
+
+### ComponentPublicInstance类型
+
+> 如下选项式示例仅为演示ComponentPublicInstance类型问题，组合式下通过getCurrentInstance()!.proxy获取的componentPublicInstance没有类型问题。
+
+目前已知组件使用emits会导致this不能直接传递给ComponentPublicInstance类型，需要as一下。
+
+```ts
+function log(ins: ComponentPublicInstance) {
+  console.log(ins);
+}
+
+export default {
+  emits: ['change', 'input'],
+  methods: {
+    buttonClick() {
+      log(this as ComponentPublicInstance)
+    }
+  }
+}
+```
+
+如下为进阶说明，可以不看
+
+我们在代码中用到的ComponentPublicInstance为省略泛型的写法，最终推导出的ComponentPublicInstance类型为：
+
+```ts
+// 此处为方便说明，省略了很多属性、简化了写法
+type ComponentPublicInstance = {
+  $emit: (event: string, ...args: any[]) => void
+}
+```
+
+对于使用了emits的组件，最终推导出来的this对应的类型为：
+
+```ts
+// 此处为方便说明，省略了很多属性、简化了写法
+type XxxComponentPublicInstance = {
+  $emit: (event: 'change' | 'input', ...args: any[]) => void
+}
+```
+
+在将XxxComponentPublicInstance类型的this值赋值给ComponentPublicInstance类型的参数时，由于$emit类型无法兼容导致编译报错。
+
+下面我们只看$emit的类型
+
+```ts
+type ComponentPublicInstanceEmit = (event: string, ...args: any[]) => void
+type XxxComponentPublicInstanceEmit = (event: 'change' | 'input', ...args: any[]) => void
+```
+
+对于ComponentPublicInstanceEmit类型的函数A来说，event参数可以接收任意字符串，如果将其赋值为只能接收'change' | 'input'作为event参数的函数B，这时候用户如果将event参数设为'click'则函数B无法处理，而函数A的类型定义又可以接收'click'，所以ts并不允许这种行为。
+
+但是反过来则是可以的XxxComponentPublicInstanceEmit类型的函数A可以被重新赋值为ComponentPublicInstanceEmit类型的函数。
+
+总结一下就是ts在比较函数参数是否兼容时使用逆变（contravariance）而非协变（covariance），这两个名词定义比较复杂，结合上述示例理解即可。
+
+### 注意事项
+
+- data内$开头的属性不可直接使用`this.$xxx`访问，需要使用`this.$data['$xxx']`，这是vue的规范。目前安卓端VDOM模式可以使用this.$xxx访问是Bug而非特性，请勿使用此特性。
+- 安卓端VDOM模式由于kotlin特性组件内部使用组件data内定义的属性时this可以省略，请勿在web端使用此特性。
+- web端由于是一个单页应用，使用`$root`会获取应用根组件，而不是页面根组件。而安卓端是多页应用，`$root`获取的是页面根组件。
+- web端使用`$parent`会获取父组件（含内置组件），安卓端只会获取父级非内置组件，web端后续会调整，请勿利用此特性。
+- web端切换页面后上一个页面的元素、组件会从dom树上移除，并触发组件及页面的`deactivate`生命周期，此时部分dom事件无法触发（如：transitionEnd）。可以视情况使用`activate`、`deactivate`生命周期重新触发dom相关操作。
+
+## uts
+
+参考：[类型兼容性](../uts/type-compatibility.md)
+
+## css
+
+### 默认样式
+
+为保证多端统一，uni-app-x编译到web端时，内置组件根元素带有一些默认样式，详情参考：[uvue css使用](../css/README.md)。如果是使用`document.createElement`等方式自行创建的html元素不会有这些默认样式。
+
+### 样式格式自动转化
+
+通过element.style.xxx设置样式时，web端会自动将样式进行转化，具体取决于浏览器。
+
+例如：
+
+```ts
+element.style.color = '##FF0000'
+element.style.color === 'rgb(255, 0, 0)' // true
+```
+
+### fixed定位
+
+position: fixed定位时，web端为相对于整个浏览器页面进行定位，app端为相对于页面（除导航栏、tabbar）定位。可以使用[css变量](../css/common/function.md)使两端表现一致
+
+```css
+.fixed {
+  position: fixed;
+  width: 100px;
+  height: 100px;
+  background-color: #FF0000;
+  left: 10px;
+  /* #ifdef WEB */
+  /*
+   * HBuilderX 4.52之前只能使用--window-top，不可使用--uni-safe-area-inset-top
+   */
+  top: calc(--uni-safe-area-inset-top + 10px);
+  /* #endif */
+  /* #ifdef APP */
+  top: 10px;  /* App端暂不支持calc */
+  /* #endif */
+}
+```
+
+## api
+
+uni相关的异步api在web端不传回调时会返回promise（详情参考：[API Promise 化](https://uniapp.dcloud.net.cn/api/#api-promise-%E5%8C%96)）。但是由于目前缺少此用法的类型定义，使用返回的Promise无法通过编译。另外安卓端暂未实现此功能，建议不要使用此特性。
+
+## 特性支持
+
+- [x] 宽屏适配
+- [x] 暗黑模式
+- [x] 国际化
+- [x] 地图
+- [x] uni-push2.0
+- [x] 服务端渲染 新增于HBuilderX 4.18
+- [ ] [接口Promise化](https://uniapp.dcloud.net.cn/api/#api-promise-%E5%8C%96)
+
+## 运行与发行@dev-and-build
+
+运行到web端时，uni-app-x编译器不会对语法进行转化来兼容低版本浏览器。发行时会对代码进行转化，以保证低版本浏览器能正常运行。
+
+发行时支持的最低浏览器版本为：`chrome 64`、`safari 11.1`、`firefox 62`、`edge 79`、`safari on iOS 12`。
+
+为优化开发体验减少运行时页面跳转等待时间，HBuilderX 4.28起，运行到web端浏览器打开后会自动触发剩余页面编译。
+
+## 配置devServer允许跨域请求服务器@dev-server
+
+开发web应用时，如果服务端未允许客户端请求的地址跨域，则客户端无法访问服务端接口。此时可以通过vite提供的代理功能实现正常访问服务器接口。详情参考：[vite server.proxy](https://cn.vitejs.dev/config/server-options#server-proxy)
+
+如下为配置示例：
+
+项目根目录下新增`vite.config.js`, 内容如下
+
+```js
+// vite.config.js
+import {
+  defineConfig
+} from 'vite';
+import uni from '@dcloudio/vite-plugin-uni';
+
+export default defineConfig({
+  plugins: [uni()],
+  server: {
+    proxy: {
+      // 如下写法转化请求地址
+      // http://localhost:5173/api/
+      // -> https://httpbin.org/
+      '/api': {
+        target: 'https://httpbin.org',
+        changeOrigin: true,
+        rewrite: (path) => path.replace(/^\/api/, ''),
+      }
+    },
+  }
+});
+```
+
+开发期间将请求地址修改为`/api/xxx`，示例如下
+
+```js
+let base = 'https://httpbin.org/'
+if(process.env.NODE_ENV === 'development') {
+  base = '/api/' // 开发期间请求/api/xxx为网页所在地址的同源地址，不存在跨域问题
+}
+uni.request({
+  method: 'POST',
+  url: base + 'post',
+  success(res) {
+    console.log(res)
+  },
+  fail(err) {
+    console.error(err)
+  }
+})
+```
+
+## 配置开发 HTTPS@https
+
+在 HBuilderX 中通过 `manifest.json` 启用 web 端 HTTPS 时，开发服务器使用的是仅用于调试的证书，浏览器通常不会将其识别为受信任证书，因此可能出现“连接不安全”之类的提示。该方式适合快速启动本地 HTTPS 调试，但不适用于需要指定证书文件、对接本地受信任证书链，或进行更严格联调验证的场景。
+
+如果需要使用开发者自行生成的证书，请不要继续在 `manifest.json` 中配置 HTTPS，而应改为在项目根目录新增 `vite.config.js`，通过 Vite 的 `server.https` 进行显式配置。同时，请删除 `manifest.json` 中与 web 端 HTTPS 相关的配置，避免与 `vite.config.js` 中的设置重复或产生冲突。
+
+示例配置如下：
+
+```js
+// vite.config.js
+import fs from 'fs'
+import { defineConfig } from 'vite'
+import uni from '@dcloudio/vite-plugin-uni'
+
+export default defineConfig({
+  plugins: [uni()],
+  server: {
+    https: {
+      key: fs.readFileSync('./cert/localhost-key.pem'),
+      cert: fs.readFileSync('./cert/localhost.pem'),
+    },
+  },
+})
+```
+
+证书文件路径请按项目实际情况调整。完成配置后，重新运行到 web 端即可使开发服务器使用指定证书。
+
+## 其他注意事项
+
+- 4.02之前的版本内置组件的tagName、nodeName与安卓端不同，web端和安卓端相比多了`UNI-`前缀，例如web端为`UNI-VIEW`、`UNI-IMAGE`，安卓端为`VIEW`、`IMAGE`。此问题已在HBuilderX 4.02版本修复，web端移除了UNI-前缀。

package/data/uni-app-x-docs/web/ssr.md

@@ -0,0 +1,290 @@
+## 使用ssr
+
+> 新增于 HBuilderX 4.18
+
+uni-app 默认情况下，是在客户端中输出 Vue 组件，进行生成 DOM 和操作 DOM。然而，也可以将同一个组件渲染为服务器端的 HTML 字符串，将它们直接发送到浏览器，最后将这些静态标记"激活"为客户端上完全可交互的应用程序。
+
+服务器渲染的 uni-app 应用程序也可以被认为是"同构"或"通用"，因为应用程序的大部分代码都可以在服务器和客户端上运行。
+
+uni-app以ssr模式编译项目最终会生成两部分产物，server部分和client部分。其中server部分可以部署在云函数或其他服务器上，这部分代码的作用是返回html内容，html内容会引用client部分的静态资源（css、js、字体、图片等）。
+
+### 配置
+
+项目根目录增加`vite.config.js`，内容如下
+
+```js
+import {
+	defineConfig
+} from 'vite'
+import uni from '@dcloudio/vite-plugin-uni'
+// https://vitejs.dev/config/
+export default defineConfig({
+	base: 'https://static-xxxx.bspapp.com/', // uniCloud 前端网页托管资源地址（主要是应用编译后的js，图片等静态资源，可以配置为二级目录），或其他最终部署静态资源的路径。server部分会依赖此配置引用静态资源
+	plugins: [
+		uni(),
+	]
+})
+```
+
+### 编写ssr相关代码
+
+在服务器端渲染(SSR)期间，我们本质上是在渲染我们应用程序的"快照"，所以如果应用程序依赖于一些异步数据，那么在开始渲染过程之前，需要先预取和解析好这些数据。
+
+另一个需要关注的问题是在客户端，在挂载 (mount) 到客户端应用程序之前，需要获取到与服务器端应用程序完全相同的数据 - 否则，客户端应用程序会因为使用与服务器端应用程序不同的状态，然后导致混合失败。
+
+为了解决这个问题，获取的数据需要位于视图组件之外，即放置在专门的数据预取存储容器(data store)或"状态容器(state container)"中。首先，在服务器端，我们可以在渲染之前预取数据，并将数据填充到 store 中。此外，我们将在 HTML 中序列化(serialize)和内联预置(inline)状态。这样，在挂载(mount)到客户端应用程序之前，可以直接从 store 获取到内联预置(inline)状态。
+
+
+#### serverPrefetch生命周期
+
+当组件实例在服务器上被渲染之前要完成的异步函数。如果这个钩子返回了一个 Promise，服务端渲染会在渲染该组件前等待该 Promise 完成。
+
+这个钩子仅会在服务端渲染中执行，可以用于执行一些仅在服务端才有的数据抓取过程。
+
+**示例**
+
+```ts
+<template>
+  <text v-if="item">{{ item.title }}</text>
+  <text v-else>...</text>
+</template>
+
+<script setup lang="uts">
+  import { useStore } from 'vuex'
+
+  const id = 1 // 模拟ID
+  const store = useStore()
+  const item = computed(() => store.state.items[id])
+
+  onMounted(() => { // 仅客户端执行的生命周期
+    if (!item.value) { // 判断服务端是否已正常获取，若未获取，重新调用加载数据
+      fetchItem()
+    }
+  })
+
+  onServerPrefetch(async () => { // 服务端预取数据的生命周期
+    await fetchItem()
+  })
+
+  function fetchItem() {
+    return store.dispatch('fetchItem', id)
+  }
+</script>
+```
+
+#### ssrRef、shallowSsrRef
+
+对于简单的需要云端客户端保持一致的数据可以使用uni-app提供的ssrRef及shallowSsrRef实现
+
+```ts
+const categories = ssrRef(['c1', 'c2'], 'categories');
+```
+
+#### vuex
+
+对于复杂的数据，如需保持云端客户端一致，建议使用vuex进行存储。下面是一个简单的示例：
+
+**main.uts**
+
+```ts
+import { createSSRApp } from 'vue'
+import App from './App.uvue'
+import createStore from './store'
+export function createApp() {
+  const app = createSSRApp(App)
+
+  const store = createStore() // 创建 store
+  app.use(store)
+
+  return {
+    app,
+    store,// 必须返回 store
+  }
+}
+```
+
+**store/index.uts**
+
+```ts
+import { createStore } from 'vuex'
+
+// 模拟接口获取数据
+function fetchItem(id) {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve({
+        id,
+        title: 'title' + id,
+      })
+    }, 300)
+  })
+}
+
+export default () => {
+  return createStore({
+    state() {
+      return {
+        items: {},
+      }
+    },
+    actions: {
+      fetchItem({ commit }, id) {
+        return fetchItem(id).then((item) => {
+          commit('setItem', { id, item })
+        })
+      },
+    },
+    mutations: {
+      setItem(state, { id, item }) {
+        state.items[id] = item
+      },
+    },
+  })
+}
+```
+
+**pages/index/index.uvue**
+
+```vue
+<template>
+  <text v-if="item">{{ item.title }}</text>
+  <text v-else>...</text>
+  <text>{{ JSON.stringify(categories) }}</text>
+</template>
+
+<script setup lang="uts">
+  import { ssrRef } from '@dcloudio/uni-app'
+  import { useStore } from 'vuex'
+
+  const categories = ssrRef(['c1', 'c2'], 'categories')
+  const id = 1 // 模拟ID
+  const store = useStore()
+  const item = computed(() => store.state.items[id])
+
+  onMounted(() => { // 仅客户端执行的生命周期
+    if (!item.value) { // 判断服务端是否已正常获取，若未获取，重新调用加载数据
+      fetchItem()
+    }
+  })
+
+  onServerPrefetch(async () => { // 服务端预取数据的生命周期
+    await fetchItem()
+  })
+
+  function fetchItem() {
+    return store.dispatch('fetchItem', id)
+  }
+</script>
+```
+
+#### page-meta
+
+uni-app-x内page-meta仅保留了存放head的功能，page-meta内的head节点在最终渲染时会传送到html的head内，可用于存放keyword、description等信息
+
+```vue
+<template>
+  <page-meta>
+    <head>
+      <meta name="keywords" content="uni-app ssr" />
+    </head>
+  </page-meta>
+</template>
+```
+
+**注意**
+
+使用此功能需要确保项目`index.html`内head下有head-meta注释。如下：
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <script>
+      var coverSupport = 'CSS' in window && typeof CSS.supports === 'function' && (CSS.supports('top: env(a)') ||
+        CSS.supports('top: constant(a)'))
+      document.write(
+        '<meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0' +
+        (coverSupport ? ', viewport-fit=cover' : '') + '" />')
+    </script>
+    <title></title>
+    <!--head-meta-->
+    <!--preload-links-->
+    <!--app-context-->
+  </head>
+  <body>
+    <div id="app"><!--app-html--></div>
+    <script type="module" src="/main"></script>
+  </body>
+</html>
+```
+
+
+### 部署
+
+上文讲到uni-app以ssr方式发行会生成server、client两部分资源。其中server部分需要部署在服务器或云函数内每次用户访问时返回html文件，client部分一般部署在对象存储+cdn内。
+
+需要注意的是服务端渲染的html引用js文件使用的是`type="module"`方式，需要配置在client部分部署位置允许server部分对应的域名进行跨域访问。
+
+#### 部署到uniCloud
+
+前置步骤
+
+1. 开通[uniCloud](https://unicloud.dcloud.net.cn)以及[前端网页托管](https://doc.dcloud.net.cn/uniCloud/hosting)
+2. 云函数绑定自定义url化域名，参考文档：[云函数Url化](https://doc.dcloud.net.cn/uniCloud/http)，阿里云未绑定自定义域名会直接下载云函数返回的html页面无法在浏览器中展示
+3. 前端网页托管绑定自定义域名，参考文档：[前端网页托管配置域名](https://doc.dcloud.net.cn/uniCloud/hosting?id=domain)
+4. 将前两步部署的域名都配置在跨域配置内，即允许云函数跨域访问前端网页托管内的资源，也允许前端网页托管跨域访问云函数。参考文档：[H5中使用uniCloud的跨域处理](https://doc.dcloud.net.cn/uniCloud/quickstart?id=useinh5)
+5. 从插件市场导入[uni-ssr](https://ext.dcloud.net.cn/plugin?id=5338)到项目内
+6. 修改`cloudfunctions/uni-ssr/package.json`内容
+
+    - 将_moduleAliases部分替换为如下内容
+    
+    ```json
+    "_moduleAliases": {
+      "vue": "node_modules/@dcloudio/uni-h5-vue/dist-x/vue.runtime.cjs.js",
+      "@dcloudio/uni-h5": "node_modules/@dcloudio/uni-h5/dist-x/uni-h5.cjs.js",
+      "vue/server-renderer": "node_modules/@vue/server-renderer"
+    },
+    ```
+    - 将uni-app相关依赖的版本调整为发行项目是的依赖版本
+
+##### 自动部署
+
+1. 通过`HBuilderX`的`发行菜单->网站 PC-Web或手机H5`、勾选`ssr`、勾选`将编译后的资源部署在uniCloud前端网页托管`
+
+	![自动部署](https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/ssr-img-02.png)
+
+2. 配置`uni-ssr`的云函数URL化路径，请参考文档：[云函数URL化](https://doc.dcloud.net.cn/uniCloud/http)
+
+##### 手动部署
+
+1. 编译：
+
+  cli工程：`npm run build:h5:ssr`或通过`HBuilderX 4.18及以上版本`的`发行菜单->网站 PC-Web或手机H5`、勾选`ssr`
+
+  非cli工程：通过`HBuilderX 4.18及以上版本`的`发行菜单->网站 PC-Web或手机H5`、勾选`ssr`
+
+  ![以ssr模式发行](https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/ssr-publish.jpg)
+
+2. 部署静态资源到[前端网页托管](https://doc.dcloud.net.cn/uniCloud/hosting)
+
+  将编译后的`dist/build/h5/client`中的资源上传至前端网页托管，推荐使用免费的阿里云服务空间
+
+3. 部署`uni-ssr`云函数
+
+  将编译后的`dist/build/h5/server`目录拷贝至`uni-ssr`云函数根目录，并上传。
+
+4. 配置`uni-ssr`的云函数URL化路径，请参考文档：[云函数URL化](https://doc.dcloud.net.cn/uniCloud/http)
+
+### 注意事项
+
+- 浏览器控制台提示如下警告，说明服务器和客户端渲染的结果不一致，检查模板绑定的属性是否使用了 `ssrRef`
+
+```
+[Vue warn]: Hydration node mismatch:
+- Client ***
+- Server ***
+```
+
+- 若路由模式配置为history之后，浏览器控制台显示如下报错，则需要根据文档检查有无准备好history相关配置。[配置文档](https://zh.uniapp.dcloud.io/quickstart-hx.html#%E5%8F%91%E5%B8%83%E4%B8%BAweb%E7%BD%91%E7%AB%99)
+  - `Hydration completed but contains mismatches`

package/data/uni-app-x-docs/worktile/NOTE.md

@@ -0,0 +1,7 @@
+---
+layout: SimpleLayout
+---
+
+该文档从公共文档自动同步生成，详细信息查看：[docs-sync.config.ts](../../docs-sync.config.ts)
+
+如需修改此文档，请前往 [docs-common 仓库](https://gitcode.com/dcloud/docs-common) 对应文件进行编辑

package/data/uniappx/404.md

@@ -0,0 +1,2 @@
+<p style="width: 100%;text-align: center;font-size: 60px;height: 40px;margin-top: 1.2em!important;">页面迷路了</p>
+<p style="width: 100%;text-align: center;font-size: 20px;line-height:30px;">1. 请确认访问地址是否有误<br/>2. 请检查网络环境是否通畅<br/>3. 关闭广告屏蔽插件后重试</p>