tmui-cli 2.0.1 → 2.0.2

package/data/tmui4x/70./346/267/267/345/220/210/345/274/200/345/217/221/03./347/273/204/344/273/266/344/273/213/347/273/215.md

@@ -0,0 +1,367 @@
+# 混合开发 - 组件介绍
+
+
+## 介绍
+
+xWebviewU，原生组件插件，定制化，非官方的webview，而是原生重写，权限控制等非常细致。
+
+## 平台兼容
+
+| Harmony | andriod | IOS | UTS | UNIAPP-X SDK | version |
+| --- | --- | --- | --- | --- | --- |
+| ☑ | ☑️ | ☑ | ☑️ | 4.86+ | 1.1.20 |
+
+
+
+## 文件路径
+
+``` ts
+
+@/uni_modules/tmx-ui/x-webview-u/
+```
+
+```mermaid
+
+    flowchart LR
+    uni_modules --> x-webview-u
+```
+
+## 使用
+
+``` ts
+
+<x-webview-u></x-webview-u>
+```
+
+## Props 属性
+
+| 名称 | 说明 | 类型 | 默认值 |
+| ------ | ---- | ---- | ---- |
+| height | `容器高,px,%，rpx` | `string` | `100%` |
+| width | `容器宽,px,%，rpx` | `string` | `100%` |
+| schema | `app唤起协议白名单，在此协议内允许跳转并拉起app,tel:,mailto:,sms:等协议拉起拨号盘，发邮件，发短信` | `string[]` | `[]` |
+| allowLoadUrlWhite | `app在跳链接时的白名单，如果域名不在此内无法跳转，如果为空则放行所有` | `string[]` | `[]` |
+| allowLoadUrl | `[仅安卓支持]url连接跳转时是否允许访问返回false禁止，true放行` | `(url : string \| null) => boolean` | `(url : string \| null) => true` |
+| addInterceptor | `执行宿主的任何方法都会先经过本函数验证返回true放行，false禁止执行` | `(url : string \| null,name:string) => boolean` | `(url : string \| null,name:string) => true` |
+| progressChanged | `页面加载时，进度百分比回调函数` | `(current:number) => void` | `(current:number) => void` |
+| showLoadProgress | `是否显示加载进度条` | `boolean` | `true` |
+| loadProgressColor | `加载进度条颜色` | `string` | `#00ca6c` |
+| src | `加载的url` | `string` | `https://x-ui.design` |
+| webConfig | `用于在所有打开的页面中注入的一个数据，任何页面可以在web中执行：tmuiApp.getConfig()得到这个数据，用于在web通过数据校验等是否允许访问或者你的其它场景所使用。` | `UTSJSONObject` | `{}` |
+| callMethod | `说明见下` | `(message:xWebviewUCallMethodType)=>void` | `(message:xWebviewUCallMethodType)=>{}` |
+
+### callMethod属性说明
+
+这是一个双向通信的属性方法。
+
+ * web执行tmuijJssdk.js中的特定方法tmuijJssdk.callMethod,会触发此方法，
+ * 本函数中得到的参数：message
+ * message.data js向宿主发送的数据
+ * message.success(返回值数据)，在web端可以收到此方法返回的结果，tmuijJssdk.callMethod是一个异步函数会等待本方法返回结果。
+ * message.fail(出错信息字符串)
+ * 其中usccess,fail函数必须执行一个，在收到本消息后。
+
+## Events 事件
+
+| 名称 | 参数 | 说明 |
+| ------ | ---- | ---- |
+| init | `-` | webview创建初始成功 |
+| pageStart | `(url:string\|null)` | 页面加载时触发 |
+| pageFinish | `(url:string\|null)` | 页面加载错误时触发 |
+| pageError | `(url:string\|null)` | 页面加载错误时触发 |
+| contentheightchange | `(url:number)` | body高变化时触发 |
+| download | `(event:{url:string , userAgent:string , contentDisposition:string , mimeType:string , contentLength:number})` | 页面发起下载链接时触发 |
+| postMessage | `(event:{detail:string})` | web通过tmuiJssdk.postMessage向宿主app发消息时触发 |
+
+## Slots 插槽
+
+| 名称 | 说明 | 数据 |
+| ------ | ---- | ---- |
+| - | - | - |
+
+
+## Ref 方法
+
+| 名称 | 参数 | 返回值 | 说明 |
+| ------ | ---- | ---- | ---- |
+| navback | - | - | 后退 |
+| refresh | - | - | 刷新 |
+| forward | - | - | 前进 |
+| clearCache | `-` | `-` | 强制清缓存并刷新页面 |
+| setUserAgent | `agent ?: string` | - | 设置webview用户代理字符串 |
+| getUserAgent | - | `Promise<string>` | 返回webview用户代理字符串 |
+| loadUrl | `url : string` | - | 加载远程 url（在线模式） |
+| evaJs | `jsCode : string` | `Promise<string \| null>` | 宿主执行 web 全局函数或代码片段；web 调宿主见 `callMethod` |
+| getManager | - | `xMiniPrograms` | 获取离线小程序管理器，见下方「离线网页（小程序模式）」 |
+
+### Ref 基础调用示例
+
+```ts
+const webu = ref<ComponentPublicInstance | null>(null)
+
+function goBack() {
+  webu.value?.$callMethod('navback')
+}
+function openRemote(url: string) {
+  webu.value?.$callMethod('loadUrl', url)
+}
+async function runJs() {
+  const result = await webu.value?.$callMethod('evaJs', `document.title`) as string | null
+  console.log(result)
+}
+```
+
+## 离线网页（小程序模式）
+
+`x-webview-u` 内置了一套「下载 zip → 本地安装 → 离线打开」的机制，用法接近小程序：首次下载安装包，之后可断网打开本地 `index.html`。
+
+适用场景：活动页、H5 业务包、需要版本热更新的混合页面等。
+
+### 原理
+
+```mermaid
+flowchart LR
+  A[远程 zip 包] --> B[installApp 下载并解压]
+  B --> C[本地沙箱目录]
+  C --> D[openMiniProgramHostUrl]
+  D --> E[loadUrlmini 离线加载]
+```
+
+1. 通过 ref 拿到管理器：`getManager()`
+2. `installApp`：按配置下载 zip，解压到本地沙箱，并写入配置文件
+3. `checkAppInstall`：检查某个 `appid` 是否已安装及版本信息
+4. `openMiniProgramHostUrl`：加载该 `appid` 目录下的 `index.html`（内部走 `loadUrlmini`）
+
+本地根目录（插件内部）：
+
+| 平台 | 目录 |
+| --- | --- |
+| iOS / 通用 | `USER_DATA_PATH/tmuiAppMiniProgram/{appid}/` |
+| Android | `ANDROID_INTERNAL_SANDBOX_PATH/tmuiAppMiniProgram/{appid}/` |
+
+每个应用目录内会写入 `tmuiMiniPrograms.json`（安装配置），并要求根目录存在 `index.html`。
+
+### 离线包（zip）规范
+
+打包时请注意：
+
+1. **内容必须在 zip 根目录**，不要再套一层文件夹
+2. 根目录必须有 `index.html`（入口）
+3. 相对资源路径按根目录组织，例如 `./js/app.js`、`./css/app.css`
+4. 可正常引入 `tmuiJssdk.js`，与在线模式一样和宿主通信
+
+错误示例：
+
+```
+my-app.zip
+ └── my-app/
+      ├── index.html
+      └── js/...
+```
+
+正确示例：
+
+```
+my-app.zip
+ ├── index.html
+ ├── js/...
+ └── css/...
+```
+
+### 获取管理器
+
+```ts
+import type { xMiniPrograms } from '@/uni_modules/x-webview-u/components/x-webview-u/miniProgram.uts'
+import type { xMiniProgramsInstallType } from '@/uni_modules/x-webview-u/interface.uts'
+
+const webu = ref<ComponentPublicInstance | null>(null)
+
+function getMiniManager(): xMiniPrograms | null {
+  // #ifdef APP
+  return webu.value?.$callMethod('getManager') as xMiniPrograms
+  // #endif
+  // #ifndef APP
+  return null
+  // #endif
+}
+```
+
+> `getManager()` 依赖已初始化的 webview 实例，请在 `@init` 之后再调用。Web 端 `loadUrlmini` 为空实现，离线模式请在 **App（Android / iOS / 鸿蒙）** 上使用。
+
+### 管理器方法
+
+通过 `getManager()` 得到的 `xMiniPrograms` 对象，提供以下方法：
+
+| 方法 | 参数 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| `checkAppInstall` | `id: string` | `Promise<xMiniProgramsInstallType \| null>` | 检查是否已安装；未安装返回 `null`，已安装返回配置信息 |
+| `installApp` | `ini: xMiniProgramsInstallType`<br>`header: UTSJSONObject \| null` | `Promise<boolean>` | 下载并安装/更新。若已存在同 `appid`，会先删除再安装 |
+| `openMiniProgramHostUrl` | `id: string` | `Promise<any \| null>` | 打开已安装的离线包。成功返回 `true`，失败返回 `false` |
+
+### 安装配置类型 `xMiniProgramsInstallType`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `appid` | `string` | 应用唯一 id，自行定义，不重复即可 |
+| `versionName` | `string` | 版本名，如 `1.1.0` |
+| `versionNumber` | `number` | 版本号数字，如 `1100`，便于比较更新 |
+| `installUrl` | `string` | zip 包远程下载地址 |
+
+```ts
+const ini: xMiniProgramsInstallType = {
+  appid: 'activity-2026',
+  versionName: '1.0.0',
+  versionNumber: 1000,
+  installUrl: 'https://cdn.example.com/offline/activity-2026.zip'
+}
+```
+
+### 完整使用示例
+
+```vue
+<template>
+  <view class="flex-1 flex flex-col">
+    <view class="flex flex-row flex-row-center-between pa-12">
+      <x-button size="small" @click="installOrUpdate">安装/更新</x-button>
+      <x-button size="small" @click="openOffline">打开离线包</x-button>
+      <x-button size="small" @click="checkInstall">检查安装</x-button>
+    </view>
+    <x-webview-u
+      ref="webu"
+      src=""
+      width="100%"
+      height="100%"
+      @init="onWebInit"
+    />
+  </view>
+</template>
+
+<script setup lang="uts">
+import type { xMiniPrograms } from '@/uni_modules/x-webview-u/components/x-webview-u/miniProgram.uts'
+import type { xMiniProgramsInstallType } from '@/uni_modules/x-webview-u/interface.uts'
+
+const webu = ref<ComponentPublicInstance | null>(null)
+const ready = ref(false)
+
+const packageInfo: xMiniProgramsInstallType = {
+  appid: 'activity-2026',
+  versionName: '1.0.0',
+  versionNumber: 1000,
+  installUrl: 'https://cdn.example.com/offline/activity-2026.zip'
+}
+
+function onWebInit() {
+  ready.value = true
+}
+
+function getMiniManager(): xMiniPrograms | null {
+  if (!ready.value || webu.value == null) return null
+  return webu.value!.$callMethod('getManager') as xMiniPrograms
+}
+
+/** 安装或强制更新（同 appid 会先删后装） */
+async function installOrUpdate() {
+  const mgr = getMiniManager()
+  if (mgr == null) return
+  // 第二个参数可传下载 header，例如鉴权 token；无则传 null
+  const ok = await mgr.installApp(packageInfo, null)
+  uni.showToast({ title: ok ? '安装成功' : '安装失败', icon: 'none' })
+}
+
+/** 打开已安装离线包 */
+async function openOffline() {
+  const mgr = getMiniManager()
+  if (mgr == null) return
+  const ok = await mgr.openMiniProgramHostUrl(packageInfo.appid)
+  if (ok != true) {
+    uni.showToast({ title: '未安装或缺少 index.html', icon: 'none' })
+  }
+}
+
+/** 检查是否已安装，并可按版本决定是否更新 */
+async function checkInstall() {
+  const mgr = getMiniManager()
+  if (mgr == null) return
+  const info = await mgr.checkAppInstall(packageInfo.appid)
+  if (info == null) {
+    uni.showToast({ title: '未安装', icon: 'none' })
+    return
+  }
+  // 本地版本低于目标版本时再 installApp
+  if (info.versionNumber < packageInfo.versionNumber) {
+    await installOrUpdate()
+  } else {
+    await openOffline()
+  }
+}
+</script>
+```
+
+### 推荐流程：检查 → 安装/更新 → 打开
+
+```ts
+async function launchOfflineApp(ini: xMiniProgramsInstallType) {
+  const mgr = getMiniManager()
+  if (mgr == null) return
+
+  const local = await mgr.checkAppInstall(ini.appid)
+  const needInstall =
+    local == null || local.versionNumber < ini.versionNumber
+
+  if (needInstall) {
+    const ok = await mgr.installApp(ini, null)
+    if (!ok) {
+      console.error('离线包安装失败')
+      return
+    }
+  }
+
+  const opened = await mgr.openMiniProgramHostUrl(ini.appid)
+  if (opened != true) {
+    console.error('打开失败：确认 zip 根目录含 index.html')
+  }
+}
+```
+
+### 注意事项
+
+1. **仅 App 端有效**：Android / iOS / 鸿蒙支持；Web 端离线加载为空实现。
+2. **先 `@init` 再 `getManager`**：webview 未就绪时不要调用。
+3. **`installApp` 会覆盖同 `appid`**：更新即重装，请保证 zip 完整可解压。
+4. **入口文件固定为 `index.html`**：缺失会打开失败并在控制台提示路径。
+5. **与 `loadUrl` 的区别**：`loadUrl` 走在线远程地址；离线打开走 `openMiniProgramHostUrl` → 内部 `loadUrlmini`。
+6. **鉴权下载**：`installApp(ini, header)` 的 `header` 会传给 `uni.downloadFile`，可带 token 等请求头。
+7. 离线页同样可使用 `tmuiJssdk.js` 与宿主双向通信（`postMessage` / `callMethod` 等）。
+
+## 示例文件路径
+
+见代码仓库混合开发中的 demo，apk 示例：
+
+## 示例源码
+
+::: details uvue
+
+
+```vue
+<template>
+	<view class="flex-1 ">
+		<x-webview-u  ref="webu" src=""></x-webview-u>
+	</view>
+</template>
+
+<script setup>
+	import { useStore } from "../store"
+	const hostUrl = useStore.hostUrl;
+	const webu = ref<ComponentPublicInstance|null>(null)
+	const url = ref(hostUrl+'cssvar')
+	
+</script>
+
+<style>
+
+</style>
+```
+
+
+:::
+

package/data/tmui4x/70./346/267/267/345/220/210/345/274/200/345/217/221/04.WEB/345/274/200/345/217/221.md

@@ -0,0 +1,126 @@
+# 混合开发 - WEB全局方法
+
+## 前提
+
+在阅读本文前，你要先把你的网页应用嵌套在uniappx中的x-webview-u组件内浏览器应用，
+并在你的应用中引入好```tmuiJssdk.js```，才能继续往下看。
+
+## 宿主的方法
+
+下面的方法是宿主原生方法，并且可全局使用，如果你是ts开发，预览类型提示错误，
+你可查看下一章jssdkApi介绍。
+
+| 名称 | 参数 | 返回值 | 说明 |
+| ------ | ---- | ---- | ---- |
+| tmuiApp.toast | `(message : string)` | - | 系统提示 |
+| tmuiApp.refresh | `-` | - | 刷新网页 |
+| tmuiApp.clearCache | `-` | - | 清除缓存并强制刷新，对于需要更新页面内容时非常有用 |
+| tmuiApp.navback | `-` | - | 回退网页 |
+| tmuiApp.forward | `-` | - | 前进网页 |
+| tmuiApp.postMessage | `(arg:string)` | - | 向宿主app发送消息 |
+
+
+## web全局方法
+
+下面的方法
+
+| 名称 | 参数 | 返回值 | 说明 |
+| ------ | ---- | ---- | ---- |
+| tmuiJssdk | `-` | - | jssdk方法合集见jssdk介绍，引入sdk后即可调用，有类型提示。 |
+| uni | `-` | - | 只有在tmui3.2 web vue组件被引入才可使用。 |
+| tmuiAppTheme | `-` | - | 宿主的CSS变量js对象见栏目：css变量，是宿主在你网页载入前主动注入一段js到你的页面中的方法。 |
+
+## web与宿主通信
+
+### web向宿主发送消息
+
+使用前面介绍的宿主方法在js中：```tmuiApp.postMessage(发送的消息)```；
+
+这是单向通信，无回调。
+
+宿主组件中：
+
+```vue
+<x-webview-u @postMessage="postMessage" ></x-webview-u>
+
+// 收到web的消息。
+const postMessage = (arg:uniAppPostmessageType) =>{
+	console.log(arg.detail)
+}
+
+```
+
+### 宿主向web发送消息
+
+这是单向通信，无回调。
+
+```vue
+<x-webview-u ref="webu"></x-webview-u>
+
+const webu = ref<ComponentPublicInstance|null>(null)
+// 向web发消息
+const postMessage = (arg:uniAppPostmessageType) =>{
+	//这里执行web中的一个全局方法
+	webu.value?.$callMethod('evaJs',`uni.showToast(${JSON.stringify({title:'Hi喽',icon:'none'})})`)
+}
+
+```
+
+### web执行宿主方法并获取返回值
+
+这是双向通信，web执行宿主方法后，得到宿主的执行结果；
+
+通过这个方法，你可以向宿主发消息，并在宿主执行任何函数，以此来拓展web执行宿主方法的事件机制
+
+因为你执行后可以得到结果。
+
+在web中如下执行方法 ：
+
+```ts
+
+const callMethod = async ()=>{
+	const result = await tmuiJssdk.callMethod('任意数据');
+	//失败还是成功，返回什么数据由宿主决定。
+	console.log(result)
+}
+
+```
+
+宿主响应```tmuiJssdk.callMethod```方法并返回结果。
+
+```vue
+<x-webview-u :callMethod="callMethod"></x-webview-u>
+
+import { uniAppPostmessageType,xWebviewUCallMethodType } from "@/uni_modules/x-webview-u";
+
+const callMethod = (message:xWebviewUCallMethodType)=>{
+	// 这里可以得到上步web的值
+	message.data //就是上步tmuiJssdk.callMethod方法中的参数，这里可以取到。
+	//你可以通过自定义的这个消息体来执行你的任何业务逻辑
+	// 执行后把结果返回给web
+	// 下面的两个方法只要执行其中一个就行，收到消息后一定要执行其中的一个。不然可能会内存泄露。
+	message.success('结果返回给web')
+	message.fail('错误返回给web')
+}
+
+```
+
+
+
+## WEB拦截
+
+```<input type="file" />```如果在混合中使用它,会自动调用宿主应用的选择器。它是按照w3c规范，可以使用相机或者相册
+得到媒体文件，也可以选择仅相机或者仅相册获取媒体文件。已经被`x-webview-u`组件拦截替换为系统自带的选择器。
+
+其它拦截：
+
+拨号 tel://协议
+
+发送邮件 mailto://协议
+
+sms发短信 sms://协议
+
+应用schem唤起 应用://协议 （如微信小程序拉起 weixin://dl/business/?appid=*你的appid* ）
+
+其它权限控制见x-webview-u组件。
+