tmui-cli 2.0.1 → 2.0.2

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xOcrS /347/246/273/347/272/277/346/226/207/346/241/243/350/257/206/345/210/253.md"

@@ -0,0 +1,115 @@
+# x-ocr-s 离线文档识别
+
+离线 OCR。通用文本识别中文 / 日文，另有身份证结构化识别与号码校验。
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 支持 |
+
+### 调用
+
+```ts
+import { xOcrPare, xOcrIdCard } from "@/uni_modules/x-ocr-s"
+
+xOcrPare({
+  path: imgPath,
+  langs: "zh",
+  success: (res) => {
+    console.log(res.text)
+  }
+})
+
+xOcrIdCard({
+  path: imgPath,
+  success: (res) => {
+    if (res.idInfo.valid) {
+      console.log(res.fields.name, res.idInfo.number)
+    }
+  }
+})
+```
+
+### 方法
+
+| 名称 | 需要 | 说明 |
+| --- | --- | --- |
+| xOcrPare | `path`、`langs`（`zh` / `ja`），可选 `zhixingdu` | 通用文本识别，返回 `text` / `textBlock` |
+| xOcrIdCard | `path`，可选 `zhixingdu` | 身份证结构化识别，返回正反面、字段和号码校验 |
+
+### 参数
+
+`xOcrPare` / `XOcrOpts`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| path | 图片路径 | 必填 |
+| langs | `zh` / `ja` | 必填 |
+| zhixingdu | 置信度 0~1，仅 Android | `0.5` |
+| success / fail / complete | 回调 | - |
+
+`XOcrResult`：`text` 纯文本行，`textBlock` 带定位的文本块。
+
+`xOcrIdCard`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| path | 图片路径 | 必填 |
+| zhixingdu | 仅 Android | `0.5` |
+| success / fail / complete | 回调 | - |
+
+`XOcrIdCardResult`：`side`（`front` / `back` / `unknown`）、`fields`（姓名、民族、住址、号码等）、`idInfo`（号码校验与派生生日/性别/年龄）、`warnings`、`lines`。
+
+错误码见插件内说明，常见 `1001`–`1006`。
+
+### 平台差异
+
+1. `zhixingdu` 仅 Android。
+2. 微信仅支持中文，日文返回 `1006`。
+
+### 版本
+
+版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+### 1.1.0（2026-08-05）
+* 新增身份证识别 `xOcrIdCard()`，五端行为一致：各端跑自己的通用中文 OCR，再由共享层
+  `utssdk/libs/idcard.uts` 做关键字锚点解析与号码校验。只负责识别与校验，取图仍由调用方
+  （相机插件、相册等）提供路径，不做卡面检测与透视矫正。
+* 结构化输出姓名、性别、民族、出生、住址、公民身份号码（人像面）与签发机关、有效期限
+  （国徽面），并自动判定证件面。
+* 号码校验实现 GB 11643：加权校验码、15 位一代证补世纪升位、出生日期合法性（含闰年）、
+  省级行政区划码。生日 / 性别 / 年龄一律从号码派生，OCR 直读值只用于交叉比对，
+  不一致时写入 `warnings`。号码校验失败不算失败，仍回调 `success` 并附带原因。
+* 容错：合并行版式（如「性别男民族汉」）、住址跨行合并、号码带空格、形近字回救
+  （O→0、I→1、S→5 等，由校验码兜底防误判）、号码锚点被糊掉时退化为全文扫描。
+* 新增微信小程序端支持，OCR 走微信内置 VisionKit（基础库 2.27.0+），零模型零包体。
+  该端 `langs` 仅支持 `zh`，且需用「预览」运行——真机调试模式下 VisionKit 会启动失败。
+* 新增错误码 1005（未识别到身份证信息）、1006（小程序端仅支持中文）。
+
+### 1.0.9（2025-10-15）
+* 安卓，ios,鸿蒙，web 4平台删除了下载，选择识别，统一由外部自行提供图片路径识别，并且采用dcloud api调用风格，已使用的用户请务必阅读使用文档后再升级使用。切不可直接替换升级。
+* 升级后，事件处理，错误机制显示更清晰。
+* 同时安卓和ios升级了插件版本，有效提升了识别率，同时安卓仅支持6.0+，Ios仅15.5+，鸿蒙21+
+### 1.0.8（2025-08-17）
+* 兼容鸿蒙原生
+### 1.0.7（2025-02-14）
+* 增加对web的支持，web使用时需要网络加载模型数据
+### 1.0.6（2024-12-18）
+* ios,安卓添加本地路径识别函数localFilePathImageBuilder,可自己循环批量处理.
+### 1.0.5（2024-11-01）
+* 修复ios可能的兼容问题
+### 1.0.4（2024-10-31）
+* ios没对齐安卓,失败不会返回回调.
+### 1.0.3（2024-10-27）
+升级了调用方式,使得安卓,ios用同样的方式调用,不再区别,统一使用callback,并且在回调中携带回了坐标,以便让大家通过坐标计算识别比例或者绘制位置
+.并且文本块统一为行返回(之前是文本块返回,但在源始数据中还是块和坐标)
+### 1.0.2（2024-09-24）
+* 各个函数追回了个参数language：string|null,可以是zh,ja，两种语言中文和日文识别。
+### 1.0.1（2024-05-04）
+* 更新支持IOS端，需要IOS12.0(含)+
+### 1.0.0（2024-04-10）
+* ocr文本识别，ai模型识别，离线识别。
+* tmui4.0种子用户，可免费赠送源码，无需购买

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xOnnxkitS /347/246/273/347/272/277/350/257/255/351/237/263/350/257/206/345/210/253/344/270/216/345/220/210/346/210/220.md"

@@ -0,0 +1,99 @@
+# x-onnxkit-s 离线语音识别与合成
+
+离线 ASR / TTS / 流式 ASR。模型不内置，用 ZIP 解压后把目录传给 `modelRoot`。
+
+模型下载见 [sherpa-onnx](https://k2-fsa.github.io/sherpa/intro.html)。
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 不支持 |
+
+### 调用
+
+```ts
+import { prepareModel, loadAsrModel, recognizeWav, startStreamingAsr, loadTtsModel, synthesize } from "@/uni_modules/x-onnxkit-s"
+
+prepareModel({
+  archivePath: zipPath,
+  modelId: "asr",
+  success: (r) => {
+    loadAsrModel({
+      modelType: "sense-voice",
+      modelRoot: r.modelRoot,
+      files: { model: "model.int8.onnx", tokens: "tokens.txt" },
+      language: "zh",
+      success: () => {
+        recognizeWav({
+          wavUri: wavPath,
+          success: (res) => {
+            console.log(res.text)
+          }
+        })
+      }
+    })
+  }
+})
+```
+
+TTS：
+
+```ts
+loadTtsModel({
+  modelType: "vits",
+  modelRoot: ttsRoot,
+  files: { model: "model.onnx", tokens: "tokens.txt", lexicon: "lexicon.txt" },
+  success: () => {
+    synthesize({
+      text: "你好，这是离线语音合成。",
+      sid: 0,
+      speed: 1,
+      success: (res) => {
+        console.log(res.audioUri)
+      }
+    })
+  }
+})
+```
+
+### 方法
+
+| 名称 | 需要 | 说明 |
+| --- | --- | --- |
+| prepareModel | `archivePath`、`modelId`，可选回调 | 解压 ZIP，成功返回 `modelRoot` |
+| loadAsrModel | `modelType`、`modelRoot`、`files`，可选 `language`、`task`、`numThreads` | 加载离线识别模型。`modelType`：`sense-voice` / `whisper` / `paraformer` / `transducer` / `qwen3-asr` |
+| recognizeWav | `wavUri` | 识别一段 wav，成功返回 `text` |
+| unloadAsr | 无 | 卸载识别模型 |
+| loadTtsModel | `modelType`、`modelRoot`、`files`，可选 `numThreads` | 加载合成模型。`modelType`：`vits` / `matcha` / `kokoro` / `kitten` |
+| synthesize | `text`，可选 `sid`（默认 0）、`speed`（默认 1） | 合成语音，成功返回 `audioUri` |
+| unloadTts | 无 | 卸载合成模型 |
+| startStreamingAsr | `modelRoot`、`files`、`onEvent` | 开始流式识别，`onEvent` 收 partial / final |
+| stopStreamingAsr | 无 | 结束流式识别 |
+| getRuntimeInfo | 无 | 同步返回运行时信息 |
+| getAsrState / getTtsState / getStreamingState | 无 | 查询对应模块状态 |
+| releaseAudioUri | Web 上的音频地址 | 释放 Web Blob URL，其它端可忽略 |
+
+`files` 里的路径相对 `modelRoot`。移动端 ZIP 不需要 manifest。
+
+### 平台差异
+
+1. 微信不支持。
+2. Web 的 `modelRoot` 必须是带 CORS 的 HTTP(S) 目录，且要有 `x-onnxkit-manifest.json`。
+3. 鸿蒙需在 `harmony-configs` 里配置 Worker，否则加载失败。
+4. `releaseAudioUri` 仅 Web 有效。
+
+### 版本
+
+版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+### 1.0.0（2026-07-31）
+
+- Android/iOS 离线 WAV 语音识别。
+- 支持 SenseVoice、Whisper、Paraformer、Transducer 模型配置。
+- tts语音合成支持通过参数配置调试音色，语速等各种配置
+- 模型文件比较大，请通过作者提前编译好的模型离线下载共模型加载使用。
+- ASR ，语音转文字 
+- TTS ，文字转语音

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xPdfS PDF/345/220/210/346/210/220.md"

@@ -0,0 +1,130 @@
+# x-pdf-s PDF合成
+
+把图片组、文本或图文叠字合成 PDF。可选图片水印，以及删页、调序、合并。
+
+识别文字请在业务页调用 `x-ocr-s`，再把结果交给 `textToPdf`，插件不依赖 OCR。
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 空实现 | 空实现 |
+
+### 调用
+
+```ts
+import { imagesToPdf, textToPdf, imageTextToPdf } from "@/uni_modules/x-pdf-s"
+
+imagesToPdf({
+  paths: imagePaths,
+  watermark: {
+    path: watermarkPath,
+    size: 96,
+    position: "bottomRight",
+    opacity: 0.35
+  },
+  success: (res) => {
+    console.log(res.path, res.pageCount)
+  }
+})
+```
+
+图文叠字（底图淡化，文字盖在上面）：
+
+```ts
+imageTextToPdf({
+  pages: [
+    { path: imgPath, text: pageText, texts: pageTexts, lines: pageLines }
+  ],
+  imageOpacity: 0.35,
+  success: (res) => {
+    console.log(res.path, res.pageCount)
+  }
+})
+```
+
+### 方法
+
+| 名称 | 说明 |
+| --- | --- |
+| imagesToPdf | 一图一页合成 PDF（纸质归档） |
+| textToPdf | 文本分页合成 PDF（纯文本另页） |
+| imageTextToPdf | 一图一页：淡化底图 + 叠字，`imageOpacity` 控制底图透明度 |
+| removePdfPages | 按 0 起始页码删页 |
+| reorderPdfPages | 按新页序重排 |
+| mergePdfs | 按顺序合并多个 PDF |
+
+`imageTextToPdf` 的 `pages[]`：`path` 必填；`text` / `texts` / `lines` 任选。`lines.box` 有八点坐标时按原图位置叠字（字号跟框高走，上限 28 点），否则按页排 `text`。`imageOpacity` 0–1，默认 0.35。鸿蒙叠字底图不竖直翻转。叠字 PDF 底图会按长边缩小后再淡化，存档原图不变。iOS 上 `pages` / `lines` 先序列化成 JSON 再读字段，不要把 Options 强转成 `UTSJSONObject`。业务页可以直接传 OCR 行对象。
+
+### 水印
+
+`watermark.path` 为图片。`size` 是宽度 pt，默认 96。`position`：`topLeft` / `topRight` / `bottomLeft` / `bottomRight`。`opacity` 0–1，默认 0.35。
+
+### 平台差异
+
+1. Web、微信仅空签名，回调 `1005`。
+2. 安卓删页/调序/合并会栅格化原页后再写，复杂矢量可能变图片。
+3. 鸿蒙按页拷贝。iOS 文本 / 叠字走 `UIGraphicsPDFRenderer` 写入沙盒 Caches（叠字在后台线程）；删页 / 调序 / 合并按页拷贝。
+
+## 更新日志
+
+### 0.1.19（2026-08-20）
+- iOS 图文叠字不再把 `options` 强转成 `UTSJSONObject`。Options 是 Swift 类型，`as!` 会闪退。页面数组改为 `JSON.stringify` 后再按 JSON 读字段。
+### 0.1.18（2026-08-20）
+- iOS 图文叠字按 OCR 写法处理页面数组：先 `item = pages[i]`，再用 `UTSJSONObject` 读 `path` / `text` / `lines`。不再写 `options.pages[i].path`，避免页面对象实际是字典时闪退。
+### 0.1.17（2026-08-20）
+- iOS 图文叠字不再把 `pages[].lines` 当成 `XPdfTextLine[]` 下标读取。对象字面量在 iOS 上是字典，强制转换会闪退（Expected XPdfTextLine but found __NSDictionaryM）。
+### 0.1.16（2026-08-20）
+- 安卓图文叠字按 OCR 框高写字（0.85，上限 28 点），不再被默认 12 点正文卡住，对齐 iOS/鸿蒙观感。
+### 0.1.15（2026-08-20）
+- iOS 文本 PDF 不再把 `draw(with:options:)` 栅格化进页。改为 `UIGraphicsPDFRenderer` 按行写入真实文字，避免页里出现 `options(...)` 和乱码符号。
+- iOS 叠字 PDF 改到后台线程，底图长边缩到 1600，不再主线程 scale=2 双份位图，避免高清图闪退。
+### 0.1.14（2026-08-20）
+- 鸿蒙叠字 PDF 不再在主线程手写 4K PNG。底图先缩到 2048 再用 ImageKit 出 JPEG，避免 THREAD_BLOCK_6S 闪退。叠字坐标仍按原图。
+- 安卓 / iOS 叠字底图同样按长边缩小后再画，存档原图不变。
+### 0.1.13（2026-08-20）
+- 鸿蒙图文叠字不再竖直翻转整页底图。水印仍翻正；底图再翻一次会倒过来，文字和水印却是正的。
+### 0.1.12（2026-08-20）
+- 新增 `imageTextToPdf`：底图降低透明度，文字叠在图上；`imageOpacity` 0–1 可调。有 OCR 框按原位置写，没有则按页排字。
+
+### 0.1.11（2026-08-18）
+- iOS 图片 / 文本合成去掉 `drawPdfPages` 里多余的 Y 轴翻转，图片、文本、水印不再整页倒置。
+- 鸿蒙文本改用有效字体路径（`font.getFontByName('HarmonyOS Sans')`，兜底 `/system/fonts/HarmonyOS_Sans.ttf`），修复文本写入 PDF 后空白。
+- 鸿蒙按 PdfPage 左下原点重排：文本首行置顶逐行向下，水印四角定位修正（默认底右）。
+- 鸿蒙水印自绘 PNG 落图前竖直翻正，修复水印上下颠倒。
+
+### 0.1.10（2026-08-18）
+- 鸿蒙 PDF 固定写到应用 `cacheDir/x-pdf-s/`，`file://` 先转沙箱路径，避免 1004 写入失败。
+
+### 0.1.9（2026-08-18）
+- iOS 合并 / 删页 / 调序改为 `CGContext.drawPDFPage` 原页拷贝，不再栅格化翻转，避免图倒过来。
+
+### 0.1.8（2026-08-18）
+- 鸿蒙数组元素补显式类型；水印解码改用 `DecodingOptions.desiredPixelFormat`。
+
+### 0.1.7（2026-08-18）
+- iOS 合并先把 `thumbnail` 竖直翻正再按合成同一套写入，对消 PDF 页图和 CGPDFContext 的 Y 轴差。
+
+### 0.1.6（2026-08-18）
+- iOS 删页 / 调序 / 合并改为 `CGContext.drawPDFPage` 按页拷贝，不再把页栅格化后再翻转写入。
+
+### 0.1.5（2026-08-18）
+- iOS 删页 / 调序 / 合并改为 `PDFPage.thumbnail` 取正立页图再写入，避免手写 Y 翻转把文字和水印倒过来。
+
+### 0.1.4（2026-08-18）
+- iOS 合成改为 Core Graphics `CGPDFContext` 写入沙盒 Caches，不再走 PDFKit write / dataRepresentation。
+
+### 0.1.3（2026-08-18）
+- 合成输出路径先转成绝对路径，iOS 改为 dataRepresentation 落盘，避免 1004 写入失败。
+
+### 0.1.2（2026-08-18）
+- iOS 合成、删页、调序、合并不再走 UIGraphics PDF 上下文，改为位图页 + PDFPage(image:) 写入，避免 Could not create CGContextRef。
+
+### 0.1.1（2026-08-18）
+- iOS 删页、调序、合并改为按页绘制写入，避免 UIGraphics 生成的 PDF 再 copy 时出现 Could not create CGContextRef。
+
+### 0.1.0（2026-08-18）
+- 新增图片组合成 PDF、文本合成 PDF。
+- 合成时可配图片水印：大小、四角位置、透明度。
+- 支持删页、调序、合并；Web / 微信先返回平台不支持。
+- OCR 不内置，由页面调用 x-ocr-s 后再走 textToPdf。

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xPdfU PDF/351/242/204/350/247/210.md"

@@ -0,0 +1,88 @@
+# x-pdf-u PDF预览
+
+PDF 预览组件。分页渲染、页码事件、跳页和系统打印。
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 不支持 |
+
+### 调用
+
+```vue
+<x-pdf-u ref="pdf" :url="url" style="width:100%;height:450px;" @onInit="onPdfInit" @pageChange="onPageChange"></x-pdf-u>
+```
+
+```ts
+uni.downloadFile({
+  url: "https://example.com/a.pdf",
+  success: (evt) => {
+    url.value = evt.tempFilePath
+  }
+})
+
+function onPdfInit(event : Map<string, number>) : void {
+  console.log(event)
+}
+
+pdf.value?.jumpTo(2)
+pdf.value?.print()
+```
+
+App 端远程 http/https/ftp 会先下载再渲染；本地路径直接打开。
+
+### 参数
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| url | PDF 地址 | `""` |
+
+### 事件
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| onInit | `{ page, pageCount }` | PDF 加载完成，`page` 从 0 开始 |
+| pageChange | `{ page, pageCount }` | 当前页变化 |
+
+### 方法
+
+| 名称 | 需要 | 说明 |
+| --- | --- | --- |
+| render | `url: string` | 手动加载并渲染 PDF |
+| getCurrent | 无 | 返回当前页，从 0 开始 |
+| getPageCount | 无 | 返回总页数 |
+| jumpTo | `page: number` | 跳到指定页 |
+| print | 无 | 打开系统打印 |
+
+### 平台差异
+
+1. 无微信实现。
+2. Web 跨域 PDF 需要 CORS；`print()` 可能被浏览器拦截弹窗。
+3. Android 含本地 AAR，需自定义基座。预览在 `scroll-view` 内会拦住触摸，翻页/缩放不穿透到页面。
+4. 鸿蒙使用系统 PDFKit 预览，打印需要 `ohos.permission.PRINT`。
+
+### 版本
+
+版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+### 1.0.6（2026-08-18）
+* Android 预览在 scroll-view 内禁止父级拦截触摸，翻页/缩放只留在 PDF 内，不再穿透到页面。
+
+### 1.0.5（2026-08-18）
+* Android/iOS 的 onInit 改为 keepAlive setter 注册，不再放进构造参数对象，避免回调释放后无法再次执行。
+
+### 1.0.4（2026-08-15）
+* 新增 HarmonyOS 预览、跳页、页码事件与系统打印，与 Android/iOS/Web API 对齐。
+### 1.0.0（2026-07-31）
+* 破坏式更新以支持蒸汽模式
+### 1.0.3（2025-10-09）
+* 修复新的sdk兼容问题，安卓依赖版本切换，以兼容4.76 sdk的版本打包匹配。
+### 1.0.2（2024-09-18）
+* 修复本地路径可能的错误.
+### 1.0.1（2024-09-18）
+* 修复本地路径可能的错误.
+### 1.0.0（2024-09-14）
+发布第一版本，双端支持打印pdf文件及预览操作pdf文件，嵌入视频预览pdf，方便定义界面。

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 / 微信小程序