tmui-cli 2.0.1 → 2.0.3

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xFacerecU /347/246/273/347/272/277/344/272/272/350/204/270/350/257/206/345/210/253.md"

@@ -0,0 +1,164 @@
+# x-facerec-u 离线人脸识别
+
+离线人脸识别：检测、入录、图片 / 相机帧 1:N 匹配，并提供嵌入式实时识别 UI 组件。可选用内置模型，不必自备。
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 不支持 | 不支持 |
+
+### 组件（推荐）
+
+`<x-facerec-u>` 是标准 UI 组件，直接嵌入页面即可实时识别：相机采集、SCRFD 检测、ArcFace 1:N、跟踪、人脸框绘制全在原生层闭环，帧不跨插件搬运。命中底库绘绿框标「人名 可信度%」，未命中绘橙框标「未识别」。识别依赖 `loadModels` 先就绪（组件与 API 共享同一原生单例与底库）。
+
+```html
+<x-facerec-u ref="facerecRef" style="width:100%;height:320px"
+  :auto-open="true" camera-position="front" :detect-interval="120" :draw-box="true"
+  @ready="onReady" @recognize="onRecognize" @capture="onCapture" @error="onError"></x-facerec-u>
+```
+
+| 属性 | 说明 | 默认 |
+| --- | --- | --- |
+| camera-position | `front` / `back`，运行中改值热切换 | `front` |
+| torch | 闪光灯（前置通常不支持） | `false` |
+| detect-interval | 相邻两次识别最小间隔 ms，框由原生插值平滑跟随 | `120` |
+| draw-box | 是否绘制人脸框与人名标签 | `true` |
+| auto-open | 视图初始化后自动请求权限并开流 | `true` |
+
+| 事件 | 说明 |
+| --- | --- |
+| @ready | 相机开流成功（含切换镜头重开） |
+| @recognize | 识别结果（`faces`：`trackId`/`name`/`score`/`recognized`/`box`） |
+| @capture | `takePhoto()` 抓拍完成，含 `imagePath` 与最近识别结果 |
+| @error | 权限/相机/抓拍错误 |
+
+组件方法（`ref` 调用）：`open()` / `close()` / `takePhoto()` / `setTorch(on)` / `setDetecting(on)` / `isDetecting()` / `switchCamera()`。开相机即开始检测，`setDetecting(false)` / `close()` 都会关掉相机，不再保留「预览在、识别停」的中间态。
+
+### 调用
+
+```ts
+import { loadModels, enroll, recognizeImage, recognizeFrame } from "@/uni_modules/x-facerec-u"
+
+loadModels({
+  detModel: "det_500m",
+  recModel: "w600k_mbf",
+  similarityThresh: 0.4,
+  confidenceThresh: 0.5,
+  maxFaces: 1,
+  success: (res) => {
+    console.log(res.gallerySize)
+  }
+})
+
+enroll({
+  userId: "u1001",
+  name: "张三",
+  imagePath: facePath,
+  success: (res) => {
+    console.log(res.quality)
+  }
+})
+
+recognizeImage({
+  imagePath: probePath,
+  success: (res) => {
+    if (res.matches.length > 0) {
+      console.log(res.matches[0].userId, res.matches[0].score)
+    }
+  }
+})
+
+recognizeFrame({
+  width: 640,
+  height: 480,
+  format: "nv21",
+  frameBuffer: data,
+  rotation: 90,
+  success: (res) => {
+    console.log(res.matches)
+  }
+})
+```
+
+实时识别优先用上方 `<x-facerec-u>` 组件或 `openCamera` 弹层，二者均在原生层闭环，无需自己搬帧。
+
+### 方法
+
+| 名称 | 需要 | 说明 |
+| --- | --- | --- |
+| loadModels | `detModel?`、`recModel?`、`modelRoot?`、阈值等，见下方 | 加载模型，不传 `modelRoot` 用内置 |
+| unloadModels | 可选回调 | 卸载模型 |
+| detectFaces | `imagePath` | 只检测人脸框和关键点，不比对底库 |
+| enroll | `userId`、`imagePath`，可选 `name`、`replace` | 入录到底库；`replace=true` 覆盖该用户旧样本 |
+| recognizeImage | `imagePath` | 用图片做 1:N 识别，返回 `matches` / `unknownFaces` |
+| recognizeFrame | `width`、`height`、`format`、`frameBuffer` 或 `frameBase64`、`rotation?` | 用相机帧做 1:N 识别 |
+| listUsers | 可选回调 | 列出底库用户 |
+| removeUser | `userId` | 删除指定用户 |
+| clearGallery | 可选回调 | 清空底库 |
+| setOptions | `confidenceThresh?`、`similarityThresh?`、`livenessThresh?`、`maxFaces?` | 运行中改阈值 |
+| openCamera | `cameraPosition?`、`torch?`、`detectInterval?`、`drawBox?`、事件回调 | 打开原生全屏弹层实时识别（不想改页面布局时用） |
+| getRuntimeInfo | 无 | 同步返回运行时与是否已就绪 |
+| getState | 无 | 返回 `idle` / `loading` / `ready` / `error` |
+
+### 参数
+
+`loadModels`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| modelRoot | 自定义模型目录，空则用内置 | 内置 |
+| detModel | `det_500m` / `det_2.5g` / `det_10g` | `det_500m` |
+| recModel | `w600k_mbf`；`w600k_r50` 需自备 | `w600k_mbf` |
+| confidenceThresh | 检测阈值 | `0.5` |
+| similarityThresh | 识别阈值 | `0.4` |
+| livenessThresh | 活体阈值 | `0.5` |
+| enrollMinQuality | 入录最低质量 | `0.6` |
+| maxFaces | 每帧最多人脸 | `1` |
+| galleryDir | 底库目录 | 应用私有目录 |
+
+`recognizeFrame`：`width` / `height` / `format`（`nv21` / `bgra` / `rgba`）/ `frameBuffer` 或 `frameBase64` / `rotation` / `orientation`。
+
+### 平台差异
+
+1. 无 Web / 微信。
+2. 帧格式与 `x-camrea-u` 对齐：Android `nv21`，iOS `bgra`，鸿蒙 `rgba`。前置镜头注意 `mirrored` / `orientation`。
+
+### 版本
+
+版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+### 0.3.0（2026-08-20）
+
+- 模块更名 `x-facerec-s` → `x-facerec-u`：由 API 插件升级为「标准 UI 组件 + API」双形态
+- 新增 `<x-facerec-u>` 嵌入式组件：相机预览 + 人脸框 overlay 直接嵌页面，
+  采集/检测/识别/跟踪/绘框全在原生层闭环，不再依赖 `x-camrea-u` 跨插件搬帧
+- 组件属性 `camera-position` / `torch` / `detect-interval` / `draw-box` / `auto-open`，
+  事件 `@ready` / `@recognize` / `@capture` / `@error`，
+  方法 `open` / `close` / `takePhoto` / `setTorch` / `setDetecting` / `switchCamera`
+- 原有全部 API（loadModels / enroll / recognizeImage / recognizeFrame / openCamera 等）保留，组件与 API 共享同一原生单例与底库
+- 修复 Android 打开测试页闪退、鸿蒙实时识别延迟大且检不出人：
+  移除 ORT XNNPACK 执行提供器（Android 上建会话原生段错误、鸿蒙上反而更慢），回归纯 CPU EP（NEON），与 iOS 63ms 同款配置
+- 原生库更名 `libx_facerec_u.so`，JNI/NAPI 符号与 Kotlin 包名同步更新
+- 修复 Android / Harmony 实时检得出人脸却对不上底库、检测框反着跑：
+  前摄不再把镜像写进推理像素（与相册录入同朝向），只在 overlay 水平翻转框
+- Android 实时分析帧不再开 CameraX 输出旋转：该选项会裁掉 FOV 且打乱 YUV 平面，导致预览在、检不出人
+- 修复 Android 嵌入式检测框偏小（只框到眼嘴）：自行按预览尺寸建 ViewPort（native-view 里 getViewPort 常为空），
+  分析帧 16:9 + cropRect；嵌入式 TextureView；CSS 盒×像素比校正 overlay 尺度
+
+### 0.2.0（2026-08-08）
+
+- 接入 ONNX Runtime 真实推理（SCRFD 检测 + 5 点对齐 + ArcFace 特征）
+- 三端各自准备 ORT：Android Maven 1.28 / iOS xcframework 1.28 / Harmony OHOS 1.27
+- 构建脚本步骤 `[0]` 调用 `third_party/onnxruntime/prepare_*.sh`（不再从 sherpa 顺手抽库）
+- 内置模型：`det_500m` / `det_2.5g` / `det_10g` + `w600k_mbf`（约 35MB）
+- `loadModels()` 可不传 `modelRoot`，自动使用内置模型
+- Android aar / Harmony har / iOS Frameworks 均含对应平台 ORT + 模型
+
+### 0.1.0（2026-08-08）
+
+- 初版框架：Android / iOS / HarmonyOS 三端骨架
+- 共享 C++ 核心 + JSON Bridge；交叉编译脚本
+- API：loadModels / enroll / detectFaces / recognizeImage / recognizeFrame / 底库管理

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xFfmpegS /351/237/263/350/247/206/351/242/221/345/244/204/347/220/206.md"

@@ -0,0 +1,114 @@
+# x-ffmpeg-s 音视频处理
+
+App 三端音视频处理：剪辑、拼接、压缩、转码、抽帧、抽音、静音、合并、缩放、旋转、水印、滤镜。输出请写到 `getCacheDir()` 等可写目录，路径不要带 `file://`。
+
+**Web / 微信不能跑处理任务。** `getMediaInfo` 可用，其它任务返回不支持。
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 不支持 | 不支持 |
+
+### 调用
+
+```ts
+import { getCacheDir, getMediaInfo, cut, cancel } from "@/uni_modules/x-ffmpeg-s"
+
+getMediaInfo({
+  path: videoPath,
+  success: (res) => {
+    console.log(res.info)
+  }
+})
+
+cut({
+  input: videoPath,
+  output: getCacheDir() + "/cut-" + Date.now() + ".mp4",
+  startTime: 2,
+  duration: 4,
+  videoCodec: "copy",
+  audioCodec: "copy",
+  onProgress: (p) => {
+    console.log(p)
+  },
+  success: (res) => {
+    console.log(res.output, res.cancelled)
+  }
+})
+
+cancel()
+```
+
+### 方法
+
+| 名称 | 需要 | 说明 |
+| --- | --- | --- |
+| getCacheDir | 无 | 返回可写缓存目录，输出路径建议拼在这里 |
+| getRuntimeInfo | 无 | 返回当前平台与编码器信息 |
+| getMediaInfo | `path` | 读媒体信息，Web / 微信也可用 |
+| cut | `input`、`output`，可选 `startTime`、`duration`、编码器 | 按时间裁剪 |
+| concat | `inputs`（至少 2 个）、`output` | 拼接多个文件 |
+| extractFrame | `input`、`output`（.jpg/.png）、`frameTime` | 抽一帧封面 |
+| extractAudio | `input`、`output` | 抽出音轨 |
+| muteVideo | `input`、`output` | 去掉视频声音 |
+| mergeVideoAudio | `input`（视频）、`audio`、`output` | 把音频合进视频 |
+| mergeTimed | `input`、`audio`、`output`、`audioStart`，可选 `audioDuration` | 从指定秒开始贴一段音乐 |
+| scale | `input`、`output`、`width?`、`height?` | 缩放 |
+| rotateVideo | `input`、`output`、`rotate`（0/90/180/270） | 旋转 |
+| compress | `input`、`output`，可选码率 | 压缩 |
+| transcode | `input`、`output`，可选编码器 | 转码 |
+| watermark | `input`、`watermark`、`output`，可选 `position`、`margin`、`opacity` | 加图片水印，文字水印不可用 |
+| filterVideo | `input`、`output`，可选 `filter`、`audioFilter` | 自定义滤镜链 |
+| cancel | 无 | 取消当前任务，成功回调里 `cancelled=true` |
+
+多数任务共用字段：
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| input / output | 绝对路径 | 必填 |
+| startTime | 起始秒 | `0` |
+| duration | 时长秒，不传则到结尾 | 到结尾 |
+| width / height | 目标尺寸，0 为等比 | 原尺寸 |
+| rotate | 0 / 90 / 180 / 270 | `0` |
+| flip | `horizontal` / `vertical` | - |
+| fps | 帧率 | 原帧率 |
+| videoCodec / audioCodec | 编码器，`copy` 为流拷贝 | 按扩展名 |
+| videoBitrate / audioBitrate | 如 `2M` / `800k`，不要小数 | - |
+| onProgress / success / fail / complete | 回调 | - |
+
+`concat`：`inputs`（至少 2 个）、`output`。
+
+`extractFrame`：`input`、`output`（`.jpg` / `.png`）、`frameTime` 必填。
+
+`mergeVideoAudio`：`input`（视频）、`audio`、`output`。
+
+`mergeTimed`：`input`、`audio`、`output`、`audioStart` 必填，`audioDuration` 默认整段音乐。
+
+`watermark`：`input`、`watermark`（png/jpg）、`output`、`position`（默认 `bottom-right`）、`margin`（20）、`scale`（0 原尺寸）、`opacity`（1）、`startTime` / `duration`。
+
+`filterVideo`：`filter` 视频滤镜链，`audioFilter` 音频滤镜链。
+
+`XFfmpegTaskResult`：`output`、`size`、`durationMs`、`cancelled`。`cancel()` 后仍走 success，且 `cancelled=true`。
+
+文字水印不可用，请用 png + `watermark`。
+
+### 平台差异
+
+1. 仅 Android / iOS / 鸿蒙可执行处理任务。
+2. 输出必须是可写绝对路径。
+
+### 版本
+
+版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+### 1.0.0（2026-08-01）
+- 基于 FFmpeg 7.1 + x264 交叉编译三平台原生依赖包。
+- Android：NDK 30 编译 arm64-v8a，AAR 内置 8 个 .so（含 MediaCodec 硬解）。
+- HarmonyOS：OHOS NDK 编译 arm64-v8a，HAR 内置 8 个 .so，NAPI + Worker 架构。
+- iOS：Xcode 编译 arm64 静态框架 XFfmpegCore.framework，ObjC++ + Swift 边界。
+- 提供剪辑、拼接、压缩、转码、抽帧、抽音、静音、合并、缩放、旋转、翻转、媒体信息探测、取消等完整 API。
+- UTS 层统一 DCloud 三回调风格（success/fail/complete），耗时任务支持进度回调。
+- 编写交叉编译脚本与构建文档（native-src/*/BUILDING.md）。

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xHtmlU HTML/345/256/211/345/205/250/346/270/262/346/237/223.md"

@@ -0,0 +1,68 @@
+# x-html-u HTML安全渲染
+
+安全渲染 HTML。丢弃 script / iframe 等危险标签，支持标题、列表、表格、链接、图片，段落可系统选区复制。
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 支持 |
+
+### 调用
+
+```vue
+<x-html-u
+  ref="htmlRef"
+  :html="htmlContent"
+  :dark="false"
+  :font-size="17"
+  @linkclick="onLinkClick"
+  @imageclick="onImageClick"
+  @rendered="onRendered"
+></x-html-u>
+```
+
+只解析不渲染：
+
+```ts
+import { xHtmlParse } from "@/uni_modules/x-html-u"
+
+xHtmlParse(html, {
+  success: (res) => {
+    console.log(res.plainText, res.ir)
+  }
+})
+```
+
+### 参数
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| html | HTML 内容 | `""` |
+| dark | 深色 | `false` |
+| fontSize | 基础字号 px | `15` |
+| lineHeight | 行高倍数 | `1.4` |
+
+### 事件
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| sizechange | `{ width, height }` | 内容尺寸变化 |
+| linkclick | `{ href, text, title }` | 点击链接 |
+| imageclick | `{ src, alt, title }` | 点击图片 |
+| rendered | `{ blockCount, parseMs, droppedNodeCount, droppedAttributeCount }` | 渲染完成 |
+| error | `{ errSubject, errCode, errMsg }` | 解析或渲染失败 |
+
+### 方法
+
+| 名称 | 需要 | 说明 |
+| --- | --- | --- |
+| setContent | `html: string` | 全量更新 HTML |
+| getContent | 无 | 返回当前原始 HTML |
+| getPlainText | 无 | 返回解析后的纯文本 |
+| getIR | 无 | 返回渲染中间层 JSON |
+| xHtmlParse | `html`，可选 `success` / `fail` / `complete` | 只解析不渲染，独立函数 |
+
+### 版本
+
+版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xKeyboardS /350/275/257/351/224/256/347/233/230.md"

@@ -0,0 +1,101 @@
+# x-keyboard-s 软键盘
+
+软键盘高度监听、收起键盘、读取当前输入框光标/选区。函数与类型均加 `x` 前缀，避免与官方同名冲突。一次性 API 使用 DCloud `success / fail / complete`。
+
+### 兼容性
+
+| Harmony | iOS | Android | WEB | 微信小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 支持 |
+
+鸿蒙端 `xGetSelectedTextRange` 无法读取系统输入框选区，会走 `fail 1005`。
+
+### 调用
+
+```ts
+import {
+  xOnKeyboardHeightChange,
+  xOffKeyboardHeightChange,
+  xHideKeyboard,
+  xGetSelectedTextRange,
+  XHideKeyboardOptions,
+  XGetSelectedTextRangeOptions
+} from "@/uni_modules/x-keyboard-s"
+
+const listenId = xOnKeyboardHeightChange((res) => {
+  console.log(res.height)
+})
+
+xHideKeyboard({
+  success: (res) => {
+    console.log(res.errMsg)
+  }
+} as XHideKeyboardOptions)
+
+xGetSelectedTextRange({
+  success: (res) => {
+    console.log(res.start, res.end)
+  },
+  fail: (err) => {
+    console.log(err.errCode, err.errMsg)
+  }
+} as XGetSelectedTextRangeOptions)
+
+xOffKeyboardHeightChange(listenId)
+```
+
+### 方法
+
+| 名称 | 说明 |
+| --- | --- |
+| xOnKeyboardHeightChange | 监听键盘高度变化，返回监听 id |
+| xOffKeyboardHeightChange | 移除监听；不传 id 则移除本插件全部监听 |
+| xHideKeyboard | 收起软键盘 |
+| xGetSelectedTextRange | 读取当前获焦输入框的光标/选区，仅 focus 时有效 |
+
+### 结果
+
+`XKeyboardHeightChangeResult.height` 为逻辑像素，收起时为 `0`。
+
+`XGetSelectedTextRangeResult`：`start` / `end` 为字符下标。
+
+错误码：`1001` 系统错误，`1002` 参数错误，`1005` 当前没有获焦的输入框，`1008` 当前平台不支持。
+
+### 平台差异
+
+**Android**
+
+- 高度：根视图 `OnGlobalLayoutListener` + 可视区域差值，再除以 density。
+- 收起：`InputMethodManager.hideSoftInputFromWindow`。
+- 选区：当前 focus 的 `TextView` / `EditText`。
+
+**iOS**
+
+- 高度：`keyboardWillChangeFrame`。
+- 收起：`endEditing`。
+- 选区：当前 first responder 的 `UITextInput`。
+
+**HarmonyOS**
+
+- 高度：`window.on('keyboardHeightChange')`，px 转 vp。
+- 收起：`inputMethod.getController().hideSoftKeyboard` / `stopInputSession`。
+- 选区：无全局可读选区，`fail 1005`。
+
+**Web**
+
+- 高度：`visualViewport` 与 `window.innerHeight` 差值。
+- 收起：`document.activeElement.blur()`。
+- 选区：当前 `input` / `textarea` 的 `selectionStart` / `selectionEnd`。
+
+**微信小程序**
+
+- 直接转发 `wx.onKeyboardHeightChange` / `wx.offKeyboardHeightChange` / `wx.hideKeyboard` / `wx.getSelectedTextRange`。
+
+### 版本
+
+版权归 https://xui.tmui.design 你不得修改及二次开发，仅供 TMUI4 会员商用使用。不得转给非 VIP 会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+### 1.0.0（2026-08-16）
+* 新增 x-keyboard-s：xOnKeyboardHeightChange、xOffKeyboardHeightChange、xHideKeyboard、xGetSelectedTextRange。

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xLoadingS /345/205/250/345/261/217/345/212/240/350/275/275.md"

@@ -0,0 +1,97 @@
+# x-loading-s 全屏加载
+
+居中加载提示，用来替代 `uni.showLoading`。支持自定义文字、图标和颜色，需手动关闭。
+
+**微信内使用官方 `uni.showLoading`，图标、颜色、尺寸等样式字段不生效，仅保留签名。**
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 支持（官方 Loading） |
+
+### 调用
+
+```ts
+import { showLoading, hideLoading, XLOADINGS_TYPE } from "@/uni_modules/x-loading-s"
+
+showLoading({
+  title: "正在提交...",
+  success: () => {
+    console.log("已弹出")
+  }
+} as XLOADINGS_TYPE)
+
+// 或不传参
+showLoading()
+```
+
+主动关闭：
+
+```ts
+hideLoading()
+```
+
+### 方法
+
+| 名称 | 需要 | 说明 |
+| --- | --- | --- |
+| showLoading | 可选 `XLOADINGS_TYPE` | 弹出加载，不传参用默认样式 |
+| hideLoading | 无 | 关闭加载。页面卸载也会自动关 |
+| hideXloading | 无 | `hideLoading` 的兼容别名 |
+
+### 参数
+
+`XLOADINGS_TYPE`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| title | 提示文字 | `""` |
+| iconCode | Remix 图标 unicode，如 `EEC4`。微信不支持 | `EEC4` |
+| iconColor | 图标颜色 | `rgb(5,121,255)` |
+| iconSize | 图标大小 px | `36` |
+| titleSize | 文字字号 px | `12` |
+| titleColor | 文字色 | `#a0a1a7` |
+| contentBgColor | 内容底色 | `#ffffff` |
+| maskBgColor | 遮罩色 | `rgba(0,0,0,0.6)` |
+| size | 内容宽度 px，最小高 100 | `100` |
+| success | 弹出成功 | - |
+| fail | 弹出失败 | - |
+| complete | 调用结束 | - |
+
+没有 `close` 回调，关闭请调 `hideLoading()`。页面卸载时会自动隐藏。
+
+### 平台差异
+
+1. 微信小程序：`uni.showLoading`，仅 `title` 有效（空则 `"..."`），遮罩固定开启。
+
+### 版本
+
+版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+### 1.1.1（2026-08-14）
+* 配置新增 success / fail / complete 回调，对齐 DCloud 函数风格：弹出成功走 success，失败走 fail，两者之后都会走 complete
+### 1.1.0（2026-08-13）
+* 重构为与 x-modal-s 一致的 DCloud 函数风格：新增 hideLoading()（对齐 uni.hideLoading 命名），hideXloading 保留为兼容别名
+* showLoading(options?) 支持无参调用，五端签名统一
+* 性能优化：安卓端 remixicon 字体缓存、代次隔离防止重入竞态、Activity 销毁时自动释放弹层防泄漏
+* iOS 端 hide 后释放视图引用并增加代次守卫
+* web 端字体只加载一次，入场动画改用 requestAnimationFrame 触发
+### 1.0.8（2026-04-21）
+* 修复可能存在的内存泄露风险
+### 1.0.7（2026-01-30）
+* 使用了sdk4.65+推出的接口来避免与官方的弹层冲突导致无法显示。
+### 1.0.6（2025-08-17）
+* 兼容原生鸿蒙
+### 1.0.3（2025-04-13）
+* 安卓端修改了布局结构现会覆盖官方的dialog-page了并且会自动隐藏状态栏,并可以覆盖底部安全区域
+### 1.0.2（2025-02-23）
+* 安卓添加了显示背景遮罩动画,及关闭遮罩动画
+* ios添加了显示背景遮罩动画,及关闭遮罩动画
+* 上述添加后,不管是显示和关闭都更加的自然
+### 1.0.1（2024-09-06）
+* 更新支持Uniapp
+### 1.0.0（2024-08-06）
+安卓,ios,web可用。

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xLocationS /345/256/232/344/275/215.md"

@@ -0,0 +1,104 @@
+# x-location-s 定位
+
+一次性定位、持续定位，以及 WGS84 / GCJ02 / BD09 坐标互转。
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 支持 |
+
+### 调用
+
+```ts
+import { getLocation, startLocationUpdate, stopLocationUpdate, onLocationChange, offLocationChange, convertCoordinate } from "@/uni_modules/x-location-s"
+
+getLocation({
+  type: "wgs84",
+  isHighAccuracy: true,
+  success: (res) => {
+    console.log(res.latitude, res.longitude, res.accuracy)
+  }
+})
+
+const id = onLocationChange((res) => {
+  console.log(res.latitude, res.longitude)
+})
+startLocationUpdate({
+  background: true,
+  type: "wgs84",
+  minUpdateInterval: 5000
+})
+
+convertCoordinate({
+  from: "wgs84",
+  to: "gcj02",
+  latitude: 39.9,
+  longitude: 116.4,
+  success: (res) => {
+    console.log(res.latitude, res.longitude)
+  }
+})
+```
+
+### 方法
+
+| 名称 | 需要 | 说明 |
+| --- | --- | --- |
+| getLocation | `type?`、`altitude?`、`isHighAccuracy?`、`highAccuracyExpireTime?`、`success` | 一次性定位 |
+| startLocationUpdate | `background?`、`minUpdateInterval?`、`minUpdateDistance?`、`type?` 等 | 开始持续定位，结果走 `onLocationChange` |
+| stopLocationUpdate | 无 | 停止持续定位 |
+| onLocationChange | `(res) => void` | 订阅位置变化，返回监听 id |
+| offLocationChange | `id` | 取消对应订阅 |
+| convertCoordinate | `from`、`to`、`latitude`、`longitude`、`success` | WGS84 / GCJ02 / BD09 互转 |
+
+### 参数
+
+`getLocation`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| type | `wgs84` / `gcj02` / `bd09` | `wgs84` |
+| altitude | 是否要海拔 | `false` |
+| isHighAccuracy | 高精度 | `false` |
+| highAccuracyExpireTime | 高精度超时 ms | `8000` |
+| success / fail / complete | 回调 | - |
+
+`startLocationUpdate`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| background | 后台持续定位。Web / 微信忽略 | `false` |
+| minUpdateInterval | 最小间隔 ms | `5000` |
+| minUpdateDistance | 最小距离米，0 不限 | `0` |
+| type | 坐标系 | `wgs84` |
+| altitude | 是否要海拔 | `false` |
+| isHighAccuracy | 高精度 | `false` |
+| notificationTitle / notificationText | Android 前台服务通知 | - |
+
+`XLocationResult`：`latitude`、`longitude`、`accuracy`、`altitude`、`speed`、`direction`、`coordSystem`、`timestamp`。
+
+### 平台差异
+
+1. Web 需 HTTPS；`background: true` 会失败。
+2. Android 后台定位走前台服务；Android 11+ 后台权限需用户到设置里开。
+3. iOS 后台需「始终允许」。
+4. 微信须在 app.json 声明定位 scope 与 `requiredPrivateInfos`。
+5. 鸿蒙后台需配置 `backgroundModes`（可参考插件 `harmony-configs`）。
+
+### 版本
+
+版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+# x-location-s
+
+### 1.0.0（2026-07-31）
+
+- 首次发布
+- 提供 `getLocation` 获取当前位置
+- 提供 `startLocationUpdate` / `stopLocationUpdate` 前后台持续定位
+- 提供 `onLocationChange` / `offLocationChange` 位置变化监听
+- 提供 `convertCoordinate` WGS84 / GCJ02 / BD09 坐标互转
+- 兼容 Android / iOS / Web / 微信小程序 / 鸿蒙