tmui-cli 2.0.1 → 2.0.3

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xPermissionS /346/235/203/351/231/220.md"

@@ -0,0 +1,93 @@
+# x-permission-s 权限
+
+跨端权限查询与申请。业务只用 `location`、`camera` 这类稳定字段，不要直接写各端原生权限名。
+
+`success` 只表示流程走完，不代表已全部授权。是否可用看 `result.granted`，逐项看 `result.permissions`。
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 支持 |
+
+### 调用
+
+```ts
+import { getPermissions, checkPermissions, requestPermissions, openPermissionSettings } from "@/uni_modules/x-permission-s"
+
+const xPermissions = getPermissions()
+const list = [
+  xPermissions.location,
+  xPermissions.camera,
+  xPermissions.microphone,
+  xPermissions.photos,
+  xPermissions.notification
+] as string[]
+
+checkPermissions({
+  permissions: list,
+  success: (result) => {
+    console.log(result.granted, result.permissions)
+  }
+})
+
+requestPermissions({
+  permissions: list,
+  autoOpenSettings: true,
+  continueAfterSettings: true,
+  success: (result) => {
+    console.log(result.granted)
+  }
+})
+
+openPermissionSettings({
+  permission: xPermissions.location
+})
+```
+
+### 方法
+
+| 名称 | 需要 | 说明 |
+| --- | --- | --- |
+| getPermissions | 无 | 返回稳定字段对象，如 `xPermissions.location` |
+| checkPermissions | `permissions: string[]`，可选回调 | 只查询，不弹授权框 |
+| requestPermissions | `permissions`，可选 `autoOpenSettings`、`continueAfterSettings` | 申请权限；`success` 只表示流程走完，是否授权看 `result.granted` |
+| openPermissionSettings | 可选 `permission` | 打开应用设置，或某项权限的系统入口 |
+
+### 参数
+
+稳定字段：`location`、`locationAlways`、`camera`、`microphone`、`photos`、`photosAddOnly`、`contacts`、`calendar`、`notification`、`bluetooth`、`motion`、`phone`、`sms`、`storage`。
+
+`checkPermissions` / `requestPermissions`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| permissions | 稳定字段数组 | 必填 |
+| autoOpenSettings | 仅申请：永久拒绝或服务关闭时是否打开设置 | `false` |
+| continueAfterSettings | 仅申请：从设置返回后是否再查一次 | `true` |
+| success | 流程结束 | - |
+| fail | 失败 | - |
+| complete | 结束 | - |
+
+`XPermissionResult`：`granted` / `allGranted`、`denied` / `hasDenied`、`permissions`、`deniedPermissions`、`grantedMap`、`deniedMap`。
+
+单项 `status`：`granted` / `denied` / `notDetermined` / `restricted` / `serviceDisabled` / `limited` / `unsupported`。当前端没有对应能力时是 `unsupported`，不会当成用户拒绝。
+
+错误码：`1001` 系统错误，`1002` 权限参数为空，`1003` 含不支持的标识，`1004` 打不开设置，`1005` 已有请求进行中。
+
+### 平台差异
+
+1. Web 仅 `location` / `camera` / `microphone` / `notification`，不能打开系统设置。
+2. 微信仅 `location` / `camera` / `microphone` / `photosAddOnly`，须在 manifest 声明对应 scope。
+3. 鸿蒙仅部分字段有等价能力，其余为 `unsupported`。
+4. Android 13+ 的 `storage` 为 `unsupported`。
+
+### 版本
+
+版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+### 1.0.0（2026-07-31）
+
+- 首次发布：多权限查询、请求、详细结果与设置页跳转。

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xPhonecontactS /351/200/232/350/256/257/345/275/225.md"

@@ -0,0 +1,91 @@
+# x-phonecontact-s 通讯录
+
+添加与选择手机通讯录联系人。参数对齐微信 `wx.addPhoneContact` / `wx.chooseContact`，回调使用 DCloud `success / fail / complete`。对外方法名为 `xAddPhoneContact`、`xChooseContact`，类型统一加 `X` 前缀，避免和官方同名冲突。
+
+App / 鸿蒙拉起系统联系人界面，由用户确认后写入或选择；不在后台静默改通讯录。
+
+### 兼容性
+
+| Harmony | iOS | Android | WEB | 微信小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 选择联系人（Chrome Contact Picker） | 支持 |
+
+### 调用
+
+```ts
+import {
+  xAddPhoneContact,
+  xChooseContact,
+  XAddPhoneContactOptions,
+  XChooseContactOptions,
+  XChooseContactResult,
+  XPhoneContactFailInfo
+} from "@/uni_modules/x-phonecontact-s"
+
+xAddPhoneContact({
+  firstName: "三",
+  lastName: "张",
+  mobilePhoneNumber: "13800138000",
+  organization: "示例公司",
+  success: (res) => {
+    console.log(res.errMsg)
+  },
+  fail: (err : XPhoneContactFailInfo) => {
+    console.log(err.errCode, err.errMsg)
+  }
+} as XAddPhoneContactOptions)
+
+xChooseContact({
+  success: (res : XChooseContactResult) => {
+    console.log(res.displayName, res.phoneNumber, res.phoneNumberList)
+  }
+} as XChooseContactOptions)
+```
+
+### 方法
+
+| 名称 | 说明 |
+| --- | --- |
+| xAddPhoneContact | 预填联系人并拉起系统新建/写入界面 |
+| xChooseContact | 拉起手机通讯录，选择联系人 |
+
+### 选择结果
+
+`XChooseContactResult`
+
+| 字段 | 说明 |
+| --- | --- |
+| displayName | 联系人姓名 |
+| phoneNumber | 当前选中的手机号 |
+| phoneNumberList | 该联系人的全部手机号 |
+| errMsg | `xChooseContact:ok` |
+
+### 错误码
+
+| 码 | 含义 |
+| --- | --- |
+| 1001 | 系统错误 |
+| 1002 | 参数错误（微信写入时 `firstName` 必填） |
+| 1004 | 权限被拒绝 |
+| 1005 | 正在进行其他通讯录操作 |
+| 1006 | 用户取消 |
+| 1008 | 当前平台不支持此功能 |
+
+### 平台差异
+
+1. 微信走官方 `wx.addPhoneContact` / `wx.chooseContact`。`phoneNumberList` 在部分安卓微信上可能是字符串，插件会归一成 `string[]`。
+2. Android 写入走系统 `ACTION_INSERT`（直接新建联系人页），选择走 `ACTION_PICK` 并优先绑定系统通讯录，不申请读写通讯录权限；查询全部号码失败时至少返回当前选中号。
+3. iOS 使用 `CNContactViewController` / `CNContactPickerViewController`。
+4. HarmonyOS 写入走系统通讯录 `startAbility`（`page_flag_save_contact`），选择走 `selectContacts`，不申请受限的读写通讯录权限。
+5. Web 的 `xAddPhoneContact` 返回 1008；`xChooseContact` 仅在支持 Contact Picker 的浏览器（多为 Android Chrome）可用。
+
+### 版本
+
+版权归 https://xui.tmui.design 你不得修改及二次开发，仅供 TMUI4 会员商用使用。不得转给非 VIP 会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+### 1.0.0（2026-08-16）
+
+- 新增 `xAddPhoneContact` / `xChooseContact`，对齐微信通讯录能力与 DCloud `success / fail / complete`
+- 支持 Android / iOS / HarmonyOS / Web / 微信小程序

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xPhotokitS /345/233/276/347/211/207/346/260/264/345/215/260.md"

@@ -0,0 +1,78 @@
+# x-photokit-s 图片水印
+
+给图片加多行文字水印，支持 5 个位置、压缩和安全边距。
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 支持 |
+
+### 调用
+
+```ts
+import { addWaterMark } from "@/uni_modules/x-photokit-s"
+
+addWaterMark({
+  path: imagePath,
+  opts: {
+    text: ["ID4656s5fsdf", "编号图片的位置xx", "广东省上海路699号江杨区域"],
+    color: "rgba(32, 36, 255, 1.0)",
+    fontSize: 12,
+    position: "center",
+    compress: 100,
+    prefix: "tmx-",
+    lineSpace: 3,
+    safeOffset: 10
+  },
+  success: (res) => {
+    uni.previewImage({ urls: [res.detail], current: res.detail })
+  }
+})
+```
+
+### 方法
+
+| 名称 | 需要 | 说明 |
+| --- | --- | --- |
+| addWaterMark | `path`、`opts`，可选 `success` | 给图片加水印，成功 `res.detail` 为输出路径 |
+
+### 参数
+
+`xPhotokitSOpts`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| path | 图片路径 | 必填 |
+| opts | 水印配置 | 必填 |
+| success | 成功，`res.detail` 为输出路径 | - |
+| fail | 失败 | - |
+| complete | 结束 | - |
+
+`XPHOTOKIT_ADDWATERMARK_OPTS`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| text | 多行文字 | `[]` |
+| fontSize | 字号，会按图片尺寸缩放 | `12` |
+| color | 颜色，支持 rgb / rgba / Hex / HSL | `#ffffff` |
+| position | `topLeft` / `topRight` / `bottomLeft` / `bottomRight` / `center` | `center` |
+| compress | 压缩 0~100，100 不压缩 | `100` |
+| prefix | 输出文件名前缀 | 时间戳 |
+| lineSpace | 行间距 | `0` |
+| safeOffset | 距边安全距离 | `0` |
+| webOutFileType | Web 输出：`base64` 或 `Blob` | `base64` |
+
+### 平台差异
+
+1. Web 可用 `webOutFileType` 控制返回 base64 或 Blob。
+
+### 版本
+
+版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+### 1.0.0（2025-10-15）
+* 针对鸿蒙的兼容,优化web和微信。
+* 针对不同图片大小，智能缩放字号大小让字号不过大也不过小。

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xPreviewMediaS /345/233/276/347/211/207/350/247/206/351/242/221/346/267/267/345/220/210/351/242/204/350/247/210.md"

@@ -0,0 +1,160 @@
+# x-previewMedia-s 图片视频混合预览
+
+全屏预览图片与视频的混合列表，对齐微信 `wx.previewMedia`。横滑翻页、双击与双指缩放、下拉关闭、视频播放、长按菜单。
+
+微信小程序直通 `wx.previewMedia`，其余四端全部原生自绘，不依赖 `uni.previewImage`（它只吃图片）。
+
+
+### 兼容性
+
+| Harmony | iOS | Android | Web | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 支持（微信） |
+
+### 调用
+
+```ts
+import { previewMedia, closePreviewMedia, XPreviewMediaOptions } from "@/uni_modules/x-previewMedia-s"
+
+previewMedia({
+  sources: [
+    { url: "https://example.com/a.jpg" },
+    { url: "https://example.com/b.mp4", type: "video", poster: "https://example.com/b.jpg" },
+    { url: "/static/local.png" }
+  ],
+  current: 1,
+  showmenu: true,
+  onChange: (res) => {
+    console.log("切到", res.index, res.type, res.url)
+  },
+  onLongPress: (res) => {
+    console.log("长按", res.url)
+  }
+} as XPreviewMediaOptions)
+```
+
+### 方法
+
+| 名称 | 说明 |
+| --- | --- |
+| previewMedia | 打开全屏预览 |
+| closePreviewMedia | 主动关闭当前预览，微信端不支持 |
+
+`previewMedia` 的 `success` 表示预览层已打开，不是关闭时机；要拿关闭时机用 `onClose`。同一时刻只允许一个预览，重复调用返回 `1005`。
+
+### 参数
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| sources | 必填 | 资源列表，`url` 为空的项直接丢弃 |
+| current | 0 | 打开时停留的序号，越界会夹到合法区间 |
+| showmenu | true | 长按时是否弹菜单。关掉后 `onLongPress` 照常触发，只是不弹层 |
+| referrerPolicy | no-referrer | 拉远程资源时是否带 `Referer`，`origin` 时带资源自身 origin |
+| indicator | default | `default` 圆点 / `number` 数字 / `none` 不显示，微信端不支持 |
+| loop | false | 首尾循环滑动，微信端不支持 |
+| autoplay | false | 视频切到当前页自动起播，默认与微信一致靠点击起播 |
+| muted | false | 视频静音起播 |
+| menuItems | 空 | 长按菜单文案与顺序，为空则长按只抛事件不弹层，微信端不支持 |
+| menuItemColor | #000000 | 菜单文字颜色，iOS / Android / 鸿蒙 / Web 生效 |
+
+`sources[]` 的字段：
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| url | 必填 | 图片或视频地址，支持 `http(s)`、`file://`、本地静态资源 |
+| type | image | `image` / `video`，缺省按扩展名兜底 |
+| poster | 空 | 视频封面，仅 `type` 为 video 时生效，留空用首帧 |
+| liveVideo | 空 | 实况照片配对的 MOV 地址，仅 `type` 为 image 时生效，只有 iOS 渲染 |
+
+`type` 缺省时按扩展名兜底（`mp4 mov m4v 3gp mkv webm avi flv ts m3u8` 判为视频），判不出当图片。
+
+### 实况照片
+
+只有 iOS 支持，走系统原生 `PHLivePhotoView`。`url` 传静图，`liveVideo` 传配对的 MOV：
+
+```ts
+previewMedia({
+  sources: [
+    { url: "/static/live/IMG_0001.HEIC", liveVideo: "/static/live/IMG_0001.MOV" }
+  ]
+} as XPreviewMediaOptions)
+```
+
+交互是**点右上角的 LIVE 徽标播放**，徽标用的是系统 `livePhotoBadgeImage`。系统自带的「按住播放」手势被插件主动关掉了，否则会和长按菜单抢同一个手势；长按行为保持不变，仍然是抛 `onLongPress` 加弹菜单。图片放大或菜单弹着时不响应播放，切页会停掉上一页的播放。
+
+
+### 事件
+
+| 名称 | 触发时机 |
+| --- | --- |
+| onChange | 滑动切换资源后 |
+| onLongPress | 长按发生时，早于菜单弹出 |
+| onMenuTap | 菜单项被点击 |
+| onLoadError | 单项资源加载失败，预览不关闭 |
+| onClose | 预览关闭 |
+
+这些事件在微信端都不触发，微信的预览界面由系统接管，拿不到内部状态。
+
+### 长按菜单
+
+菜单是纯壳子：插件负责弹出、命中、收起，不执行任何动作。文案完全由 `menuItems` 决定，识别码、分享、存相册各接自己已有的插件：
+
+```ts
+previewMedia({
+  sources: [{ url: "https://example.com/qrcode.png" }],
+  menuItems: ["分享", "识别", "保存"],
+  onMenuTap: (res) => {
+    // res.tapIndex 与 menuItems 下标一致，res.itemText 是命中的文案
+    if (res.itemText == "分享") shareByMyPlugin(res.url)
+    if (res.itemText == "识别") scanByMyPlugin(res.url)
+    if (res.itemText == "保存") saveByMyPlugin(res.url)
+  }
+} as XPreviewMediaOptions)
+```
+
+不传 `menuItems` 就只有 `onLongPress`，适合自绘菜单；`showmenu: false` 也是同样效果。菜单弹着时按返回键先收菜单，再按一次才关预览。
+
+### 交互
+
+| 手势 | 行为 |
+| --- | --- |
+| 横滑 | 翻页，非循环时越界有阻尼；距离不够但甩得快也翻页 |
+| 双击 | 图片在 1x 与 2x 之间切换，按落点锚定，视频不响应 |
+| 双指 | 图片缩放，上限 4x，按双指中心锚定；超出 1x～4x 可跟手拉出一段，松手弹回 |
+| 单指拖动 | 放大后平移画面，松手带惯性滑行；拖出边界有阻尼，松手弹回；未放大时下拉关闭 |
+| 单击 | 图片关闭预览；放大状态先复位；视频切换播放 |
+| 长按 | 恒抛 `onLongPress`，`showmenu` 且 `menuItems` 非空时弹菜单 |
+| 返回 | Android 返回键、鸿蒙返回手势、Web 浏览器返回都只关预览这一层 |
+
+### 错误码
+
+| errCode | 说明 |
+| --- | --- |
+| 1001 | 系统错误，预览层创建失败 |
+| 1002 | 参数错误 |
+| 1003 | 资源列表为空 |
+| 1005 | 正在预览中 |
+| 1007 | 当前没有预览，`closePreviewMedia` 专用 |
+| 1008 | 当前平台不支持此功能 |
+| 1009 | 资源加载失败 |
+| 1010 | 实况照片加载失败，已降级为静态图，仅 iOS |
+
+## 更新日志
+
+### 1.0.0（2026-08-27）
+* 新增 previewMedia / closePreviewMedia，五端对齐微信 wx.previewMedia
+* 微信小程序直通 wx.previewMedia，Android / iOS / 鸿蒙 / Web 全原生自绘
+* 图片双击与双指缩放、横滑翻页、下拉关闭、视频播放
+* 预览层四端都用独立窗口层：Android Dialog、iOS 独立 UIWindow、鸿蒙 openCustomDialog、Web 压 history 记录，返回只关预览不退页面
+* 长按恒抛 onLongPress，菜单文案由 menuItems 传入，命中项经 onMenuTap 抛出，保存 / 分享 / 识别码全部由页面实现
+* 插件不落库不分享，不申请相册、存储与分享相关权限
+* Android / iOS 播控条图标用插件内独立 remixicon 副本，鸿蒙与 Web 用系统自带控制条
+* sources[] 新增 liveVideo，iOS 走系统 PHLivePhotoView 渲染实况照片，点右上角 LIVE 徽标播放
+* iOS 关掉系统自带的按住播放手势，避免和长按菜单抢手势；放大或菜单弹出时不响应播放
+* 实况照片配对失败或下载失败退回静态图并抛 1010，其余四端忽略 liveVideo 按静图渲染
+* 新增 onLoadError 事件，接出原生层的单项加载失败（含 1009 与 1010），预览不会因此关闭
+* 放大后拖动松手带惯性滑行，拖出边界跟手变重、松手弹回；双指拉出 1x～4x 区间后松手同样弹回
+* 横滑翻页补速度判定，距离不够但甩得快也翻页
+* 四端惯性跑同一套逐帧衰减公式且参数一致，各端驱动器分别是 CADisplayLink / Choreographer / setInterval / requestAnimationFrame，滑行途中可被新触摸立即接手
+* 修复鸿蒙缩放限位按页面尺寸计算的问题，改用 Image onComplete 回填的实际显示尺寸，竖屏看横图不再能把画面拖进黑边
+* 修复 Web 双指缩放每帧都挂 200ms transition 导致缩放滞后手指的问题

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xPrintS /347/263/273/347/273/237/346/211/223/345/215/260.md"

@@ -0,0 +1,105 @@
+# x-print-s 系统打印
+
+调用系统打印预览，支持 PDF、文本、图片。
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 不支持 |
+
+### 调用
+
+```ts
+import { printPdf, printTxt, printImage } from "@/uni_modules/x-print-s"
+
+printPdf({
+  filename: "测试pdf.pdf",
+  filepath: tempFilePath,
+  success: (res) => {
+    console.log(res.errCode)
+  }
+})
+
+printTxt({
+  filename: "测试文本.txt",
+  content: "第一行\n第二行",
+  margin: 20,
+  fontSize: 32,
+  lineSpacing: 1.5,
+  paperSize: "A4"
+})
+
+printImage({
+  filename: "测试图片.jpg",
+  filepath: imagePath
+})
+```
+
+选图后立刻打印时，iOS 需等选择器关闭后再调，可用短延迟。
+
+### 方法
+
+| 名称 | 需要 | 说明 |
+| --- | --- | --- |
+| printPdf | `filepath`，可选 `filename`、`paperSize`、`copies`、`margin` | 打印 PDF，远程地址会先下载 |
+| printTxt | `content`，可选 `filename`、`margin`、`fontSize`、`lineSpacing`、`paperSize` | 打印文本 |
+| printImage | `filepath`，可选 `filename`、`margin`、`paperSize` | 打印图片，等比居中 |
+
+### 参数
+
+公共字段：`filename`、`paperSize`（`A4` / `A5` / `A6` / `B5` / `B6` / `letter`）、`copies`、`success` / `fail` / `complete`。成功时 `errCode` 为 0。
+
+`printPdf`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| filepath | 本地或远程 PDF | 必填 |
+| margin | 页边距 pt，PDF 暂不生效 | - |
+
+`printTxt`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| content | 文本，支持 `\n` | 必填 |
+| margin | 页边距 pt | `20` |
+| fontSize | 字号 pt，`0` 或不传则自适应 | 自适应 |
+| lineSpacing | 行距倍数 | `1.4` |
+
+`printImage`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| filepath | 本地或远程图片 | 必填 |
+| margin | 四周留边 pt，等比居中 | `10` |
+
+远程地址会先下载再打印。
+
+### 平台差异
+
+1. `paperSize` / `copies`：Android / Web 部分生效；iOS 由系统打印面板控制。
+2. PDF 的 `margin` 暂不生效；iOS 图片 `margin` 暂不生效。
+3. 鸿蒙需打印权限（插件已声明）。
+
+### 版本
+
+版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+### 1.2.0（2026-08-01）
+- 新增鸿蒙（HarmonyOS NEXT）平台支持：PDF/文本/图片打印，基于系统 print 能力，自动申请 PRINT 权限
+- 新增排版参数：页边距 margin、字号 fontSize、行距 lineSpacing（文本）
+- 新增纸张类型参数 paperSize（A4/A5/A6/B5/B6/letter，Android/Web 生效）
+- 新增份数参数 copies（三端由系统打印面板控制，预留）
+
+### 1.1.0（2026-08-01）
+- 改造成 DCloud 函数式风格 API，统一 `success` / `fail` / `complete` 回调
+- 新增文本（txt）打印，支持自动分页排版
+- 新增图片打印（jpg/png）
+- 新增 Web（H5）端打印支持
+- 新增远程地址自动下载后再打印
+- 新增统一错误码规范（unierror.uts）
+
+### 1.0.0（2024-06-01）
+发布第一版本，双端支持打印 pdf 文件。