tmui-cli 2.0.1 → 2.0.3

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xModalS /345/257/271/350/257/235/346/241/206.md"

@@ -0,0 +1,124 @@
+# x-modal-s 对话框
+
+居中对话框，用来替代 `uni.showModal`。支持自定义按钮、图标、对齐和遮罩，连续调用会自动关掉上一条。
+
+**微信内使用官方 `uni.showModal`，样式字段不生效，仅保留签名。**
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 支持（官方 Modal） |
+
+### 调用
+
+```ts
+import { showModal, X_MODAL_TYPE } from "@/uni_modules/x-modal-s"
+
+showModal({
+  title: "提醒",
+  content: "这是一条测试消息对话框，默认按钮分离。",
+  confirmText: "确定",
+  cancelText: "取消",
+  isSplitBtn: true,
+  clickMaskClose: true,
+  confirm: () => {
+    console.log("确认")
+  },
+  cancel: () => {
+    console.log("取消")
+  },
+  close: () => {
+    console.log("已关闭")
+  }
+} as X_MODAL_TYPE)
+
+showModal({
+  title: "协议",
+  isHtml: true,
+  content: "<p>请阅读<a href=\"https://xui.tmui.design\">服务协议</a>后继续。</p>",
+  clickLink: (href) => {
+    console.log(href)
+  }
+} as X_MODAL_TYPE)
+```
+
+### 方法
+
+| 名称 | 需要 | 说明 |
+| --- | --- | --- |
+| showModal | `X_MODAL_TYPE` | 弹出对话框，连续调用会关掉上一条 |
+
+### 参数
+
+`X_MODAL_TYPE`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| title | 标题 | `提醒` |
+| content | 内容。`isHtml` 为 true 时按 HTML 解析清洗 | `""` |
+| isHtml | 启用 HTML 渲染与链接回调。App 用内置 Lexbor 清洗，Web 用 UTS 解析器。微信忽略 | `false` |
+| contentAlign | `center` 居中 / `left` 顶左 | `center` |
+| titleColor | 标题色 | `#000000` |
+| contentColor | 内容色 | `#333333` |
+| linkFontColor | 内容链接色 | `rgb(5,121,255)` |
+| confirmText | 确认文字 | `确认` |
+| confirmColor | 确认文字色 | `#FFF` |
+| confirmBgColor | 确认底色 | `#0579FF` |
+| confirmIcon | 确认 Remix 图标 unicode。微信不支持 | `""` |
+| cancelText | 取消文字 | `取消` |
+| cancelColor | 取消文字色 | `#333` |
+| cancelBgColor | 取消底色 | `#f5f5f5` |
+| cancelIcon | 取消 Remix 图标 unicode。微信不支持 | `""` |
+| showCancel | 是否显示取消 | `true` |
+| isSplitBtn | 按钮是否分离 | `true` |
+| lineColor | 不分离时的分割线色 | 透明 |
+| contentBgColor | 面板底色 | `#fff` |
+| maskBgColor | 遮罩色 | `rgba(0,0,0,0.6)` |
+| radius | 圆角 px | `16` |
+| width | 宽度 px | `320` |
+| height | 高度 px | `80` |
+| clickMaskClose | 点击遮罩关闭 | `true` |
+| isBlurMask | 遮罩模糊，目前仅 Web 生效 | `true` |
+| confirm | 点确认 | - |
+| cancel | 点取消 | - |
+| close | 关闭完成 | - |
+| clickLink | 点内容链接。`isHtml` 为 true 时 Android / iOS / 鸿蒙 / Web 均可拦截 | - |
+
+没有 `success` / `fail` / `complete`，只用 `confirm` / `cancel` / `close`。
+
+### 平台差异
+
+1. 微信小程序：`uni.showModal`，仅 `title`、`content`、`confirmText`、`cancelText`、`showCancel` 等基础字段生效，无法主动关闭官方弹层。`isHtml` 与 `clickLink` 不生效。
+2. `isHtml`：Android / iOS / 鸿蒙用内置 Lexbor 依赖包清洗后再画；Web 用 UTS 解析器。都不依赖 `x-html-u`。未开启时按纯文本显示。鸿蒙弹窗是 ETS，不再使用原来的弹窗 HAR。
+3. `isBlurMask`：仅 Web 生效。
+
+### 版本
+
+版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+### 1.0.9（2026-08-15）
+* 新增可选参数 `isHtml`：内容层解析清洗 HTML 后再渲染，并支持 `clickLink`。
+* 原生渲染性能强。可以直接代替官方的modal层。
+### 1.0.8（2026-04-21）
+* 修复可能存在的内存泄露风险
+### 1.0.7（2026-01-30）
+* 使用了sdk4.65+推出的接口来避免与官方的弹层冲突导致无法显示。
+### 1.0.6（2025-08-17）
+*  更新支持鸿蒙原生 Next，采用自己编译的 Har 包来支持
+### 1.0.5（2025-04-30）
+* ios,安卓,web内容现在可以渲染html内容,不要太复杂.安卓和web会拦截a标签,ios目前拦截不了会直接跳转外链.
+### 1.0.4（2025-04-13）
+* 安卓端弹层修改布局,现在可以覆盖官方的Dialog-page页面了,并且可以接受安卓的返回键及侧滑关闭弹层了.并且会自动隐藏状态栏,并可以覆盖底部安全区域
+### 1.0.3（2025-02-23）
+* 安卓添加了显示背景遮罩动画,及关闭遮罩动画
+* ios添加了显示背景遮罩动画,及关闭遮罩动画
+* 上述添加后,不管是显示和关闭都更加的自然
+### 1.0.2（2025-02-13）
+* 兼容微信
+### 1.0.1（2024-08-15）
+* 新增contentAlign,可以让内容顶左对齐,还是让内容左右上下居中对齐 .
+### 1.0.0（2024-08-06）
+安卓,ios,web可用。

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xModel3dU.md

@@ -0,0 +1,88 @@
+# x-model3d-u
+
+5 端静态 glTF 模型查看器。运行时只吃 **GLB 单文件**（无 Draco / meshopt / KTX2）。
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 #| 支持 | 支持 | 支持 | 支持 |
+
+### 用法
+
+```uvue
+<x-model3d-u ref="viewerRef" :src="modelUrl" width="100%" height="420"
+  @load="onLoad" @error="onError" @progress="onProgress"></x-model3d-u>
+```
+
+```uts
+viewerRef.value!.fitToScreen()
+viewerRef.value!.resetView()
+viewerRef.value!.load(url)
+```
+
+统一方法：`load` / `fitToScreen` / `resetView` / `setCamera` / `getCamera` / `snapshot` / `getBounds`  
+统一事件：`ready` / `load` / `error` / `progress`
+
+微信小程序要改**两个文件**，少一个都跑不起来。
+
+`pages.json` 里注册原生组件（用到的页面各写一份，或写进 `globalStyle` 全局生效）：
+
+```json
+{
+  "globalStyle": {
+    "usingComponents": {
+      "x-model3d-xr": "/uni_modules/x-model3d-u/wxcomponents/x-model3d-xr/index"
+    }
+  }
+}
+```
+
+`manifest.json` 的 `mp-weixin` 段里打开按需注入：
+
+```json
+{
+  "mp-weixin": {
+    "lazyCodeLoading": "requiredComponents"
+  }
+}
+```
+
+`lazyCodeLoading` 必须写在 `manifest.json`，写进 `pages.json` 不生效。xr-frame 是非 webview 渲染器，微信强制要求整个小程序开启按需注入，漏了会在真机和开发者工具里直接报：
+
+```text
+a render renderer besides `webview` will be accepted only with `lazyCodeLoading` set to `requiredComponents`
+```
+
+OBJ / 散装 glTF 必须先走仓库根目录 `scripts/prepare_model.sh` 转成无扩展纯 GLB。树叶请把 alpha blend 改成 alpha mask。回归树可用 `node scripts/generate_tree_glb.mjs`。
+
+
+### 截图对比清单
+
+| 项 | 约定 |
+|---|---|
+| 模型 | Helmet、tree |
+| 机位 | yaw 30 / pitch 20 / fill 1.15 |
+| 背景 | `#1a1a1e` |
+| 自转 | 关 |
+| 输出 | 各端 `snapshot`（鸿蒙、微信暂不回读像素，用真机截屏） |
+
+### 包体量级
+
+| 端 | 增量 | 备注 |
+|---|---|---|
+| 鸿蒙 | 0 | 系统  3D |
+| 微信 | 0 | 客户端内置  |
+| Web | ~1.2MB | `three.module.js` + addons，随插件走 |
+| Android | ~7MB | 4.7MB，当前只打 arm64-v8a |
+| iOS | ~4.3MB | 预置（ios-arm64） |
+
+帧率 / 内存需真机测：建议 Helmet + tree 各看 10 秒轨道操作，记峰值 RSS 与平均 FPS。
+
+## 更新日志
+
+### 0.1.0（2026-08-27）
+
+- 新增 5 端静态 GLB 查看器：Android Filament、iOS SceneKit+GLTFKit2、鸿蒙 ArkGraphics 3D、Web three.js、微信 xr-frame
+- 统一 API：load / fitToScreen / resetView / setCamera / snapshot
+- 离线管线：`scripts/prepare_model.sh`、`scripts/generate_tree_glb.mjs`

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xMoreshareS /346/233/264/345/244/232/345/210/206/344/272/253/351/235/242/346/235/277.md"

@@ -0,0 +1,155 @@
+# x-moreshare-s 更多分享面板
+
+从底部弹出的「更多 / 分享」面板，视觉对齐头条菜单更多：可选标题 + 宫格（图标或图片）+ cell 列表 + 取消。宫格支持单行横滑或自动断行；两区都可空，有才显示。
+
+详细规划见同目录 [PLAN.md](./PLAN.md)。
+
+**微信内使用官方 `uni.showActionSheet` 降级，图标、图片、横滑、断行不生效，仅保留标题和文案。**
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 支持（官方菜单降级） |
+
+### 调用
+
+```ts
+import { showMoreShare, hideMoreShare, XMoreShareOptions, XMoreShareGridItem, XMoreShareCellItem } from "@/uni_modules/x-moreshare-s"
+
+showMoreShare({
+  title: "分享到",
+  grids: [
+    { id: "wechat", title: "微信", icon: "F2B6" } as XMoreShareGridItem,
+    { id: "copy", title: "复制", icon: "ECD5" } as XMoreShareGridItem
+  ] as XMoreShareGridItem[],
+  cells: [
+    { id: "link", title: "复制链接", icon: "EEB8" } as XMoreShareCellItem,
+    { id: "report", title: "举报", icon: "ED3B" } as XMoreShareCellItem
+  ] as XMoreShareCellItem[],
+  gridClick: (index : number, item : XMoreShareGridItem) => {
+    console.log("宫格", index, item.title)
+  },
+  cellClick: (index : number, item : XMoreShareCellItem) => {
+    console.log("列表", index, item.title)
+  },
+  cancel: () => {
+    console.log("取消")
+  },
+  close: () => {
+    console.log("已关闭")
+  }
+} as XMoreShareOptions)
+```
+
+主动关闭：
+
+```ts
+hideMoreShare()
+```
+
+### 参数
+
+`XMoreShareGridItem`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| id | 条目标识 | `g` + 索引 |
+| title | 下方标题 | `""` |
+| image | 图片地址，有则优先于 icon | `""` |
+| icon | Remix unicode，如 `F2B6` | `""` |
+| iconBgColor | 圆角矩形背景 | `#F5F5F5` |
+| iconColor | 图标色 | `#333333` |
+| iconSize | 图标字号 px | `24` |
+| iconBoxSize | 方块边长 px | `52` |
+| iconBoxRound | 方块圆角 px | `12` |
+| titleColor | 标题色 | `#666666` |
+| titleSize | 标题字号 px | `11` |
+| disabled | 禁用 | `false` |
+
+`XMoreShareCellItem`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| id | 条目标识 | `c` + 索引 |
+| title | 文案 | 必填语义 |
+| icon | Remix，无框 | `""` |
+| iconColor | 图标色 | `#333333` |
+| iconSize | 图标字号 px | `18` |
+| titleColor | 文案色 | `#111111` |
+| titleSize | 文案字号 px | `16` |
+| showArrow | 右箭头 | `true` |
+| disabled | 禁用 | `false` |
+
+`XMoreShareOptions`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| title | 顶栏标题，空则不显示 | `""` |
+| showTitle | 是否显示标题（标题为空时仍不显示） | `true` |
+| grids | 宫格数组 | `[]` |
+| gridMode | `scroll` 横滑 / `wrap` 断行 | `scroll` |
+| cells | 列表数组 | `[]` |
+| showCancel | 是否显示取消 | `true` |
+| cancelText | 取消文字 | `取消` |
+| cancelColor | 取消文字色 | `#333333` |
+| overlayClick | 点击遮罩关闭 | `true` |
+| itemClickClose | 点击条目后关闭 | `true` |
+| space | 非通栏时面板相对屏幕左右留白；`false` 为通栏贴边。中间内容区（宫格 + cell）左右 10px，标题和取消通栏；标题到内容、取消到内容各 10px。宫格区域块与 cell 列表块 12px 圆角 | `true` |
+| round | 圆角 px | `16` |
+| maxHeight | 内容最大高度 px，0 为屏高 80% | `0` |
+| maskBgColor | 遮罩色 | `rgba(0,0,0,0.35)` |
+| contentBgColor | 面板间隙色 | `#f5f5f5` |
+| cellBgColor | 条目底色 | `#ffffff` |
+| titleColor | 标题色 | `#888888` |
+| arrowColor | 右箭头色 | `#C8C8C8` |
+| duration | 动画 ms | `350` |
+| gridClick | 点击宫格 | - |
+| cellClick | 点击列表 | - |
+| cancel | 取消 / 遮罩 / 手势返回 | - |
+| close | 关闭完成 | - |
+| success | 点了宫格或 cell，含 `type/index/id/title` | - |
+| fail | 取消或失败 | - |
+| complete | 结束（成功或失败都会走） | - |
+
+### 平台差异
+
+1. 微信小程序：`uni.showActionSheet`，最多 6 条，宫格标题在前、cell 标题在后；图标、图片、横滑、断行、内容区内间距不生效。`hideMoreShare` 为空实现。
+2. 关闭箭头与宫格图标使用插件内独立字体 `x-moreshare-remixicon.ttf`。Web 字体族名为 `x-moreshare-remixicon`，文件走全局 `/static/tmui4xLibs/static/remixicon.ttf`。
+
+### 版本
+
+版权归https://xui.tmui.design你不得修改及二次开发，仅供TMUI4会员商用使用。不得转给非VIP会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+### 1.0.9（2026-08-17）
+* iOS 宫格去掉多余顶距并按字体行高算高度，恢复底部 10px 内边距；cell 标题改回靠左跟图标对齐。
+
+### 1.0.8（2026-08-17）
+* 安卓单行宫格按文字实际行高撑开，避免标题底部被裁几个像素。
+
+### 1.0.7（2026-08-17）
+* wrap 宫格高度按实际行高收紧，避免标题/取消与内容之间被撑出大空隙。
+
+### 1.0.6（2026-08-17）
+* 原生单行宫格左对齐；wrap 按容器比例分列铺满，避免右边空一大块。
+
+### 1.0.5（2026-08-17）
+* Web 单行宫格改为横向滚动且不收缩挤叠，并隐藏滚动条。
+
+### 1.0.4（2026-08-17）
+* 标题/取消到内容的间距与内容左右 10px 对齐；wrap 按可用宽度等分列，避免 3 个就断行和高度虚高。
+
+### 1.0.3（2026-08-17）
+* 宫格区域块四角圆角；cell 列表作为一组，上左右 / 下左右圆角。
+
+### 1.0.2（2026-08-17）
+* 只有中间内容区（宫格 + cell）左右缩 10px，标题和取消仍通栏；标题到内容、取消到内容各 10px。
+
+### 1.0.1（2026-08-17）
+* 宫格 wrap 断行增加 8px 行距。微信官方菜单无法改布局。
+
+### 1.0.0（2026-08-17）
+* 新增 x-moreshare-s：头条风格底部更多面板，可选标题 + 宫格（横滑/断行）+ cell 列表 + 取消。
+* App 三端使用独立字体 `x-moreshare-remixicon.ttf`；微信官方 ActionSheet 降级。

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xMqttS MQTT/346/266/210/346/201/257.md"

@@ -0,0 +1,129 @@
+# x-mqtt-s MQTT消息
+
+进程级单连接 MQTT。`new xMqtt()` 只是门面，全局只保持一条活连接；再次 `create` 会断开旧连接，**监听保留**。
+
+**微信仅 WSS，且必须是 WebSocket 网关。** Web / 微信不支持自定义证书，`applyTls` 为空实现。
+
+### 兼容性
+
+| Harmony | IOS | Android | WEB | 小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 支持 | 支持 |
+
+### 调用
+
+```ts
+import { xMqtt, MQTT_SUBSCRIBE, MQTT_PUBLISH_TOPIC, MQTT_CONNECT_OPTS } from "@/uni_modules/x-mqtt-s"
+
+const mqtt = new xMqtt()
+
+mqtt.addEventListener("message", (_type, topic, str) => {
+  console.log(topic, str)
+})
+
+mqtt.create({
+  protocol: "wss",
+  path: "/mqtt",
+  clientId: "tmui4x-" + Date.now(),
+  server: "broker.emqx.io",
+  port: 8084,
+  useSSL: true,
+  keepAliveInterval: 60,
+  timeout: 30,
+  reconnect: true,
+  clean: true,
+  rejectUnauthorized: true
+} as MQTT_CONNECT_OPTS)
+
+mqtt.connect()
+mqtt.subscribe([{ topic: "xui/hi", qos: 1 }] as MQTT_SUBSCRIBE[])
+mqtt.publish({
+  topic: "xui/hi",
+  qos: 0,
+  message: "hello",
+  retained: false
+} as MQTT_PUBLISH_TOPIC, (_ok) => {})
+```
+
+### 方法
+
+| 名称 | 参数 | 说明 |
+| --- | --- | --- |
+| create | `MQTT_CONNECT_OPTS` | 配置并替换当前连接，不自动 connect |
+| connect | 无 | 连接服务器 |
+| subscribe | `[{ topic, qos }]` | 订阅；未连上会在连上后补订 |
+| unsubscribe | `topics: string[]` | 取消订阅 |
+| publish | `{ topic, message, qos, retained }` + `(isSuccess) => void` | 推送 |
+| disconnect | 无 | 断开，保留监听 |
+| destroy | 无 | 断开并清空监听 |
+| addEventListener | `open` / `disconnect` / `dissconnect` / `error` / `message` | 返回监听 id |
+| removeEventListener | `id` | 按 id 移除 |
+| getState | 无 | `wait` / `opening` / `open` / `dissconnect` / `error` |
+| applyTls | `MQTT_TLS_OPTS` | 写入证书配置，下次 create 生效。Web / 微信空实现 |
+
+`dissconnect` 与 `disconnect` 等价，旧监听名继续可用。
+
+### 证书
+
+Android / iOS / Harmony 从**各端插件资源目录**读取证书，更换后重新打包：
+
+| 平台 | 目录 |
+| --- | --- |
+| Android | `utssdk/app-android/assets/` |
+| iOS | `utssdk/app-ios/Resources/` |
+| Harmony | `utssdk/app-harmony/resources/rawfile/` |
+
+| 字段 | 说明 |
+| --- | --- |
+| certName | CA：`ca.crt` / `ca.pem`。若为 `.p12` 则作为客户端证书 |
+| clientCertName | 客户端证书。Android/iOS 用 p12；Harmony 用 pem |
+| clientKeyName | Harmony mTLS 私钥 pem |
+| certPassword | p12 或私钥密码 |
+| rejectUnauthorized | 默认 `true`。`allowUntrustCACertificate: true` 仍兼容，等价于关闭校验 |
+| serverName | SNI，默认 `server` |
+
+仓库自带示例 `ca.crt`（公共根 CA）。私有 CA / mTLS 请替换同名文件后重新出包。Web / 微信走系统信任链，自定义证书无效。
+
+### 协议
+
+- Android / iOS / Harmony：`ws`、`wss`；Android / iOS 额外支持 `tcp`、`ssl`
+- Web：`ws`、`wss`
+- 微信：仅 `wss`
+
+### 错误码
+
+| 码 | 含义 |
+| --- | --- |
+| 1001 | 系统错误 |
+| 1002 | 参数错误 |
+| 1005 | 连接超时 |
+| 1008 | 当前平台不支持此协议或证书 |
+| 1010 | 尚未 create |
+| 1011 | 证书加载失败 |
+| 1012 | 证书校验失败 |
+
+`error` 事件的 `str` 为 `errCode:errMsg`。
+
+### 版本
+
+版权归 https://xui.tmui.design 你不得修改及二次开发，仅供 TMUI4 会员商用使用。不得转给非 VIP 会员使用，一经查实数倍赔偿，并追究法律责任。
+
+## 更新日志
+
+### 1.1.1（2026-08-16）
+* 鸿蒙 type 字段 retained 改为可选，避免 @default 被编译成带初始值的确定赋值
+### 1.1.0（2026-08-16）
+* 改为进程级单连接：再次 create 自动断开旧实例，监听保留
+* 新增 destroy / getState / applyTls；证书从各端资源目录加载
+* 鸿蒙去掉 HAR，改为原生 WebSocket + MQTT 3.1.1
+* 统一 clean / will / timeout / retained，并修复微信二次连接与取消监听
+### 1.0.4（2026-04-07）
+* 修复ios连接wss失败的问题
+### 1.0.3（2025-08-17）
+* 兼容 原生鸿蒙 Next
+### 1.0.2（2025-02-13）
+* 兼容微信
+### 1.0.1（2024-09-13）
+* ios补充取消订阅的方法。
+### 1.0.0（2024-09-05）
+首次发布

package/data/tmui4x/10./346/217/222/344/273/266/345/272/223/xMusicnotifyS /351/200/232/347/237/245/346/240/217/351/237/263/344/271/220/346/222/255/346/224/276/345/231/250.md"

@@ -0,0 +1,128 @@
+# x-musicnotify-s 通知栏音乐播放器
+
+系统媒体控件。把正在播放的封面、标题、副标题和时间线同步到通知栏、锁屏、控制中心或鸿蒙播控中心，并回传播放、暂停、停止、上一首、下一首、拖进度。
+
+本插件**不解码音频**。真正播放请用业务播放器或 `x-mediaplay-s`，再把进度喂给本插件。
+
+### 兼容性
+
+| Harmony | iOS | Android | WEB | 微信小程序 |
+| --- | --- | --- | --- | --- |
+| 支持 | 支持 | 支持 | 部分支持 | 部分支持 |
+
+### 调用
+
+```ts
+import {
+  show,
+  update,
+  setProgress,
+  setPlaying,
+  hide,
+  onAction,
+  offAction,
+  getState,
+  XMusicNotifyShowOptions
+} from "@/uni_modules/x-musicnotify-s"
+
+onAction((res) => {
+  if (res.action == "pause") {
+    setPlaying({ playing: false })
+  }
+})
+
+show({
+  title: "晴天",
+  subtitle: "周杰伦",
+  album: "叶惠美",
+  cover: "/static/x-musicnotify/default-cover.png",
+  durationMs: 269000,
+  positionMs: 0,
+  playing: true,
+  success: (res) => {
+    console.log(res.errMsg)
+  }
+} as XMusicNotifyShowOptions)
+```
+
+### 方法
+
+| 名称 | 说明 |
+| --- | --- |
+| show | 展示或重建媒体通知，`title` 必填 |
+| update | 更新标题、副标题、专辑、封面、时长、进度、倍速、强调色 |
+| setProgress | 只更新时间线，适合跟播放器 `onInfo` |
+| setPlaying | 只切换播放/暂停外观 |
+| hide | 关闭通知并释放系统会话 |
+| onAction | 监听系统控件操作，后注册覆盖前一次 |
+| offAction | 取消监听 |
+| getState | 当前展示快照 |
+| isShowing | 通知是否仍在 |
+
+### 参数
+
+`XMusicNotifyShowOptions`
+
+| 字段 | 说明 | 默认 |
+| --- | --- | --- |
+| title | 歌名 | 必填 |
+| subtitle | 歌手 | 空 |
+| album | 专辑 | 空 |
+| cover | 本地绝对路径 / `file://` / `http(s)` / `/static` | 内置默认封面 |
+| durationMs | 总时长 ms，大于 0 才画时间线 | 0 |
+| positionMs | 当前进度 ms | 0 |
+| playing | 是否显示为播放中 | true |
+| speed | 倍速 | 1 |
+| showPrev / showNext / showStop | 按钮显隐 | true |
+| canSeek | 是否允许拖时间线 | true |
+| color | 强调色 `#RRGGBB`，主要影响 Android | `#31C27C` |
+
+`XMusicNotifyAction.action`：`play` / `pause` / `stop` / `prev` / `next` / `seek` / `close` / `click`。`seek` 时 `positionMs` 为目标进度。
+
+错误码：`1001` 系统错误，`1002` 参数错误，`1003` 通知服务不可用，`1004` 通知权限被拒绝，`1007` 当前环境无法显示控件，`1008` 平台不支持，`1009` 尚未 show。
+
+### 平台差异
+
+**Android**
+
+- `MediaSessionCompat` + `NotificationCompat.MediaStyle` + `mediaPlayback` 前台服务。
+- Android 13+ 需运行时授予 `POST_NOTIFICATIONS`，插件会先申请再展示。
+- Android 13+ 系统媒体通知的进度条来自 session 的 duration / position，不必自己画 RemoteViews。
+- 修改 `config.json` 后需重新打自定义基座。
+
+**iOS**
+
+- `MPNowPlayingInfoCenter` + `MPRemoteCommandCenter`。
+- 插件会把 `AVAudioSession` 设为 `playback`。锁屏控件在有真实音频在播时最稳定，建议同时用 `x-mediaplay-s`。
+- 宿主需允许后台音频：插件已声明 `UIBackgroundModes: audio`。
+
+**HarmonyOS**
+
+- `AVSession`，类型 `audio`。至少注册一条控制命令后播控中心才会出现。
+- 进度按官方建议节流，后台播放保活仍取决于你的播放器长时任务。
+- 宿主 `entry/module.json5` 建议声明 `backgroundModes: ["audio"]`。
+
+**Web**
+
+- `navigator.mediaSession`。Chrome 等通常要页面里有真实媒体在播，通知栏才会出现。
+- Safari 支持有限，不支持时 `fail` 1008。
+
+**微信小程序**
+
+- 只更新 `BackgroundAudioManager` 的 title / singer / coverImgUrl / epname，并转发 onPlay / onPause / onStop / onPrev / onNext。
+- 封面建议用 `https`。没有后台音频在播时，系统通知栏可能不出现。
+
+### 资源
+
+插件内置默认封面（黑胶 + 音符，QQ 绿强调）和播放 / 暂停 / 停止 / 上一首 / 下一首 / 关闭矢量图标。
+
+- 演示页封面：`/static/x-musicnotify/default-cover.png`
+- 原生回退封面：Android `assets/x_musicnotify_cover.png`、iOS `Resources/x_musicnotify_cover.png`、鸿蒙 `rawfile/x_musicnotify_cover.png`
+
+业务封面传 `cover` 即可覆盖。HTTP 封面建议用 `https`。
+
+## 更新日志
+
+### 1.0.0（2026-08-17）
+* 新增通知栏音乐播放器 API 插件：封面、标题、副标题、时间线、播放/暂停/停止/上一首/下一首。
+* Android MediaSession + MediaStyle 前台服务；iOS Now Playing；鸿蒙 AVSession；Web Media Session；微信后台音频元数据。