更新记录

1.0.0（2026-11-13）

• 新增视频与实况素材选取、原生可视化选段、封面选择和预览源码。
• 新增 Android 动态壁纸服务、系统确认与状态查询源码。
• 新增 iOS 实况候选导出、相册保存核验与系统设置指引源码。
• 新增双宿主示例、任务取消、资源释放与完整脱敏报告。
• 新增原生全屏素材、桌面和锁屏模拟预览，内置喜欢、保存、分享、设置及可扩展操作栏。
• 新增预览文案、主题、按钮顺序/显隐/禁用配置，支持运行时更新和宿主动作结果回传。
• 新增统一尺寸线宽的内置图标，以及普通态、选中态、工具位和桌面图标地址配置、异步加载回退与错误事件。
• 新增 Android 视频相册保存与 iOS 普通视频保存，保留实况原件及真实保存回执。
• 新增自定义全屏示例、业务喜欢本地持久化与完整持续事件诊断。
• 新增参考式黑底视频选段界面、黄色双端胶片时间轴、白色封面游标与气泡、片段平移及长视频浏览。
• 新增全屏预览画面左右滑动切换锁屏/桌面，并让编辑器右上“预览”直接进入同一正式预览界面；视频选段保持当前区间循环。
• 新增编辑器右上全屏选段效果预览，支持素材、桌面和锁屏模拟，返回继续编辑、使用片段后保持原有编辑结果合同。
• 修复 iOS 编辑时间轴的手势方法缺少 override 导致云打包 Swift 编译失败，保留横向拖动和长按选段判断。
• 修复 iOS 选段效果预览的文字测量浮点常量类型歧义，保留按钮宽度、多行高度测量与原有布局。
• 修复双宿主示例导出回执携带选段时清空候选、修改时间后继续使用旧候选的问题，预览、保存和设置自动生成当前选段。
• 修复示例连续请求的任务编号及卸载清理，导出失败或取消后终止后续系统交接。
• 修复 iOS 保存成功后指引等待触发超时误报，及时返回相册回执与手动设置阶段。
• 修复 Android 预览静音状态、系统设置界面启动异常和已销毁编辑器的缩略图释放。
• 修复 Android 全屏长短操作文案混排时的图标错位、模式按钮高度不齐及自定义模式文案重复追加“预览”。
• 修复 Android 编辑器旋转后的预览高度，以及长日期、应用标签和底部操作栏的构图重叠。
• 修复 Android 窄屏大字号的长标题与操作区互遮，分别支持完整文案滚动和明确滚动提示。
• 修复 Android 编辑器退到后台后延迟加载回调重新播放的问题，返回时保留用户的播放或暂停选择。
• 修复 Android 编辑器大字号标签与控制行裁切，播放按钮跟随实际播放意图更新，增强未选滑轨的可辨识性。
• 修复 Android 非方形视频缩略图被拉伸的问题，使用等比居中裁剪并保留异步资源释放。
• 修复 Android 保存源文件失效时的模糊提示，返回可识别的读取错误并保留原生原因及媒体库回滚。
• 修复 Android 壁纸组件查询受限时误判未生效并清理素材造成黑屏的问题，保留未知状态及素材，并通过当前非预览服务的真实首帧核验生效状态。
• 修复 Android 连续设置与中断重试时的素材交接、迟到回执匹配及临时副本并发清理，取消新候选时保留原有壁纸。
• 修复 Windows Web 复制报告时系统转换换行造成正文长度不一致，完整报告与分段在生成时固定换行并避免拆开 CRLF。
• 修复 uni-app x 示例折叠按钮嵌套 text 导致 iOS 原生组件警告，标题与展开状态改用按钮直接文本并保留完整点击区域。
• 优化 Android 自定义文字色对比、操作按压反馈、喜欢选中状态及无障碍名称。
• 优化 Android 与 iOS 全屏预览，按照新参考图常驻返回、锁屏预览/桌面预览分段器和渐变应用按钮，默认直接进入锁屏，保留显式素材模式和自定义动作。
• 优化顶部锁屏/桌面分段按钮，清除系统默认蓝色背景与高亮着色，保留白色选中胶囊和深色文字。
• 优化 20 秒以上视频的选段拖动与视口边界，允许把固定长度窗口移动到完整视频的任意时间段；iOS 低版本应用失败时提供“保存到相册 / 知道了”真实降级。
• 优化视频时间轴的窗口化浏览与手势冲突处理，普通横向拖动连续浏览源视频，选段整体移动改为长按后拖动，并保留已加载缩略帧减少滑动黑屏。
• 优化全屏桌面图标、两模式页点与贴底磨砂 Dock 的比例，锁屏按锁图标、日期、大号时间排列，并按真实安全区避让导航。
• 优化 Android 保存成功面板的自适应高度、对齐、中文核验说明与设置指引点击区域。
• 优化 Android 默认桌面图标与标签的对应关系，以及锁屏默认日期的中文星期。
• 优化双端全屏桌面和锁屏构图，使用完整彩色应用图形、独立Dock与真实安全区，进入仿真默认沉浸，操作层显隐不挤压壁纸布局。
• 优化双宿主示例为视频壁纸、实况壁纸和界面设置三个分类，提供素材类型校验、清晰主操作和按需展开的精确参数，保留全部诊断、分段复制及手动回退入口。
• 调整默认全屏操作为喜欢、保存、预览、分享和设置，预览动作打开桌面/锁屏选择；保留客户动作配置与系统真实回执。
• 优化 Android 封面选帧交互，松手后保留所选帧，便于确认封面。
• 优化宿主兼容声明，明确uni-app Vue2/Vue3与uni-app x普通/蒸汽模式的接入和验收范围。
• 优化客户说明的配置、参数和业务模块示例，补充双宿主示例的中文注释并保留生成结果。

平台兼容性

uni-app(5.34)

uni-app x(5.34)

其他

动态壁纸与实况制作 UTS 插件

介绍

lizhao-wallpaper 为 uni-app Vue2/Vue3、uni-app x 普通模式（VDOM）和蒸汽模式（Vapor）提供视频与实况制作、原生全屏桌面/锁屏预览、喜欢、相册保存、分享及 Android/iOS 壁纸系统交接。当前为开发候选源码，匹配基座与真机效果需要按文末范围验收。

功能特色

适合哪些场景

下载与导入

从基础到进阶：按业务模块使用

基础功能配置示例

导入、注册与宿主选择

1. 将整个 uni_modules/lizhao-wallpaper/ 导入工程，保留 uni_modules/lizhao-wallpaper/utssdk/、uni_modules/lizhao-wallpaper/example/ 与 uni_modules/lizhao-wallpaper/static/。无需安装另一套实况或视频编辑插件。
2. uni-app Vue2、Vue3 注册 uni_modules/lizhao-wallpaper/example/uniapp/index.vue，页面代码使用 JavaScript；uni-app x 注册 uni_modules/lizhao-wallpaper/example/uniappx/index.uvue，页面代码使用 UTS。
3. uni-app x 普通模式与蒸汽模式共用同一个 .uvue 示例、根 import 和 API。蒸汽模式在项目根 manifest.json 的 uni-app-x 节点设置 vapor: true；普通模式设为 false。只修改该字段，保留项目其他配置。
4. 按第8节配置原生构建并制作匹配自定义基座。新增插件后仅更新页面资源不能补入 Swift/Kotlin 与系统服务。

以下是 pages.json 的单个路由条目，应加入现有 pages 数组，保留原来的启动页。uni-app x 使用下面的路径；uni-app 将路径中的 uniappx 改为 uniapp，路由都不写文件后缀。

{
  // 完整页面文件为uni_modules/lizhao-wallpaper/example/uniappx/index.uvue。
  "path": "uni_modules/lizhao-wallpaper/example/uniappx/index",
  "style": { "navigationBarTitleText": "动态壁纸与实况制作" }
}

最小流程：选择并预览视频

以下 JavaScript 函数适用于 uni-app Vue2/Vue3 的页面脚本，可由按钮调用。先检测能力，预览关闭或失败后释放本次资源。uni-app x 的类型写法及完整页面见本节后文。

import { getWallpaperCapabilities, chooseWallpaperMedia, previewWallpaper } from '@/uni_modules/lizhao-wallpaper'

import { releaseWallpaperResources } from '@/uni_modules/lizhao-wallpaper'

export function chooseAndPreview() {
  // 能力来自当前运行端；Web/小程序没有壁纸业务能力，不能仅凭页面可打开就调用成功。
  const capabilities = getWallpaperCapabilities()
  if (!capabilities.chooseVideo || !capabilities.preview) {
    console.warn(capabilities.reason)
    return
  }
  chooseWallpaperMedia({
    // 默认也是video；原始实况用live-photo，后续仍使用返回的resourceId。
    mediaType: 'video',
    success(result) {
      if (result.media == null) return
      const resourceId = result.media.resourceId
      previewWallpaper({
        resourceId,
        // 最小示例只展示素材。完整下载/分享界面见后文，需保留资源并等待其子任务结束。
        ui: { preview: { initialMode: 'media' }, actions: [] },
        // preview-closed只表示预览关闭；相册实况识别和锁屏动态资格须分别核对。
        success(preview) { console.log(preview.state, preview.message) },
        fail(error) { console.error(error.errSubject, error.errCode, error.errMsg) },
        complete() {
          // complete在成功或失败后均执行，此时预览已不再占用素材；仅释放本次选择的资源。
          releaseWallpaperResources({ resourceIds: [resourceId],
            fail(error) { console.error('资源释放失败', error.errCode, error.errMsg) } })
        }
      })
    },
    // 9358003是用户取消，仍需保留该真实结果；不要提示“已选取”。
    fail(error) { console.error(error.errSubject, error.errCode, error.errMsg) },
    complete(outcome) { console.log('选择结束', outcome.requestId, outcome.success) }
  })
}

mediaType 默认为 video。选择已有实况时传 live-photo，后续使用本次返回的 resourceId。该标识只在当前进程和本插件资源表中有效，应用重启后重新选择。

高级示例

视频选段与封面

前置数据是 chooseWallpaperMedia 成功返回的当前进程 resourceId。下面分别演示原生可视化编辑和手动参数导出，其他辅助函数用于保存、状态与清理。手动示例选取输入视频的 0–2000ms，封面为输入视频的 1000ms，要求输入至少长2000ms。Android 选段长度为 500–30000ms，iOS 为 500–3000ms，全部时间必须落在真实媒体时长内。

原生编辑器采用黑色背景和大幅视频画面。拖动胶片两端的黄色把手调整起止，普通横向拖动胶片浏览完整视频；如需整体移动片段，请长按选区后再拖动，长视频可连续浏览到视频末尾。白色封面框及“封面”气泡用于定位封面，封面始终位于所选区间内。底部“已选取 x.x s”只对显示值取一位小数，返回参数仍保留实际毫秒。

极短选段的把手与封面靠近时，可长按胶片选区后拖动，整体移动片段并保留时长与封面相对位置。无障碍也可分别调节起点、终点与封面。

视频下方的“预览”用于循环播放当前区间，再点暂停，播放不会改变封面。右上玫红“预览”进入当前选段的全屏效果界面，可切换素材、桌面和锁屏模拟；返回编辑会保留选段与封面。只有点“使用此片段”才返回 state=edited 及 result.edit，查看效果和返回编辑不会提前触发编辑成功回调。退出整个编辑器按原取消错误 9358003 返回。

横屏编辑时，视频居中完整显示，播放/暂停叠在画面上，Android声音开关也放在画面内；已选时长位于底部全宽胶片时间轴上方。大字号或小窗口允许工具区滚动，保持按钮与完整文案可达。

编辑器右上角“预览”直接复用正式全屏预览界面，按当前选段循环播放；左右滑动可在锁屏预览与桌面预览之间切换，返回编辑会保留选段与封面，不生成文件，也不代表 iOS 已生成配对实况或系统已经接受壁纸。需要保存、分享或设置时，先将确认得到的 result.edit 传给 exportWallpaper，再使用导出返回的新 resourceId。Android 可在编辑器切换静音；iOS 当前视频候选保持静音。

import {
  openWallpaperEditor, exportWallpaper, cancelWallpaperTask,
  releaseWallpaperResources, saveWallpaperToAlbum, getWallpaperState,
  getWallpaperDiagnostics
} from '@/uni_modules/lizhao-wallpaper'

export function editAndExport(resourceId) {
  // 返回编辑任务编号。预览内点“使用此片段”后result.edit才有参数，取消通过fail返回9358003。
  return openWallpaperEditor({
    resourceId,
    success(result) {
      if (result.edit == null) return
      // 编辑器不直接生成文件；使用返回的绝对毫秒和静音选择，继续调用正式导出API。
      exportWallpaper({
        resourceId,
        startMs: result.edit.startMs,
        endMs: result.edit.endMs,
        coverTimeMs: result.edit.coverTimeMs,
        muted: result.edit.muted,
        // output.media.resourceId是新候选。接入方同时登记原素材和候选，结束后分别释放。
        success(output) { console.log(JSON.stringify(output)) },
        fail(error) { console.error(error.errCode, error.errMsg) }
      })
    },
    fail(error) { console.error(error.errCode, error.errMsg) }
  })
}
export function exportSpecifiedRange(resourceId) {
  // 封面必须满足startMs <= coverTimeMs < endMs。iOS视频候选仅支持muted=true。
  return exportWallpaper({ resourceId, startMs: 0, endMs: 2000, coverTimeMs: 1000, muted: true,
    success(result) { console.log(JSON.stringify(result)) },
    fail(error) { console.error(error.errCode, error.errMsg) } })
}
export function cancelCurrent(taskId) {
  // taskId使用当前在途API立即返回的编号，不能误用resourceId；取消请求不代表原任务已经结束。
  cancelWallpaperTask({ taskId, success(result) { console.log(result.state) },
    fail(error) { console.error(error.errCode, error.errMsg) } })
}
export function saveLivePhoto(resourceId) {
  // 先查询saveToAlbum。Android保存资源的视频，iOS保存普通视频或完整实况原件。
  // verified表示读取回资产并核对类型；iOS实况还检查photoLive，锁屏资格仍需单独核对。
  saveWallpaperToAlbum({ resourceId, success(result) { console.log(result.assetId, result.albumVerification) },
    fail(error) { console.error(error.errCode, error.errMsg) } })
}
export function queryState(resourceId) {
  // 省略resourceId时查询系统状态；传入时进一步核对该素材是否与当前壁纸匹配。
  getWallpaperState({ resourceId, success(result) { console.log(result.wallpaperVerification, result.target) },
    fail(error) { console.error(error.errCode, error.errMsg) } })
}
export function releaseOwned(resourceIds) {
  // 仅传本会话取得的资源ID。仍被导出/预览引用时会返回9358008，等待结束后重试。
  releaseWallpaperResources({ resourceIds, success(result) { console.log(result.releasedCount) },
    fail(error) { console.error(error.errCode, error.errMsg) } })
}
// 同步返回已脱敏的JSON文本；示例完整报告还会合并运行环境和所有保留的操作日志。
export function diagnostics() { return getWallpaperDiagnostics() }

iOS 视频生成候选默认静音，muted=false 返回明确的不支持错误。已有实况的导出仅保留完整原件，调用时省略三个时间参数。预览、导出和系统交接正在引用的资源暂不能释放，结束后按实际回执释放。相册提交或系统应用进入不可撤销阶段后，取消请求可能返回结果未知，原任务最终回执仍需保留。

原始实况与相册保存

iOS 选择 mediaType: 'live-photo' 后使用原件资源预览、保存或设置指引。需要显式调用 exportWallpaper 时仅传 resourceId 和回调，省略 startMs、endMs、coverTimeMs，原始实况保留完整配对和音轨。Android 的同名选择路径支持带标准 XMP 视频长度信息的 JPEG Motion Photo，其预览、导出与相册保存使用视频表示。

保存前检查 getWallpaperCapabilities().saveToAlbum。保存成功后分别记录 assetId 与 albumVerification，失败时保留 9358004/9358009 的原始错误；结果未知时先核对相册再重试。相册资产是系统副本，之后释放插件临时资源不删除该资产。

全屏界面、按钮配置与业务接管

下面的 uni-app Vue2/Vue3 函数接收已有的 resourceId。两个图标参数可直接传空字符串使用默认图标，也可以传开发者准备的可访问图片地址。下载按钮保存当前素材到系统相册，视频编辑后的预览应传入导出候选编号。

import { previewWallpaper, resolveWallpaperPreviewAction, updateWallpaperPreview,
  cancelWallpaperTask } from '@/uni_modules/lizhao-wallpaper'

export function openFullScreen(resourceId, normalIconUrl = '', selectedIconUrl = '') {
  // 此示例用本地存储演示业务接管。接入账号收藏时，可在服务器确认后再回传最终状态。
  const storageKey = 'wallpaper-like-' + resourceId
  let initialLiked = false
  try { initialLiked = uni.getStorageSync(storageKey) === true }
  catch (error) { console.warn('读取喜欢状态失败', error) }
  return previewWallpaper({
    resourceId, liked: initialLiked, actionTimeoutMs: 60000,
    ui: {
      appearance: { accentColor: '#FF5C8A', contentMode: 'cover' },
      preview: { initialMode: 'lock', showModeSwitcher: true },
      texts: { title: '我的壁纸', guideButton: '查看设置方法' },
      // 数组决定按钮顺序。visible控制显隐，enabled保留按钮并显示禁用状态。
      // 传actions: []可隐藏整个动作栏，关闭入口始终可用。
      actions: [
        { id: 'like', handler: 'host', label: '喜欢', selectedLabel: '已喜欢',
          icon: 'heart', iconUrl: normalIconUrl, selectedIconUrl },
        { id: 'download', label: '下载', icon: 'download' },
        { id: 'share', visible: true, icon: 'share' },
        { id: 'apply', label: '设置', icon: 'wallpaper' },
        // 自定义id必须交给host处理，最多6项。超过4个可见动作会自动收入更多菜单。
        { id: 'show-lock', label: '看锁屏', icon: 'eye', handler: 'host' }
      ],
      saveFeedback: { enabled: true, showGuide: true },
      share: { content: 'video', title: '分享壁纸', text: '' }
    },
    onEvent(event) {
      // 保存/分享结果和图标失败都从持续事件取得，保持完整错误码与请求关联编号。
      console.log('预览事件', JSON.stringify(event))
      if (event.event !== 'action' || !event.pending) return
      if (event.action === 'like') {
        const nextLiked = !event.liked
        try { uni.setStorageSync(storageKey, nextLiked) }
        catch (error) {
          resolveWallpaperPreviewAction({ previewId: event.requestId,
            actionId: event.actionId, succeeded: false, message: '喜欢状态保存失败',
            fail(failure) { console.error(failure.errCode, failure.errMsg) } })
          return
        }
        // 先完成实际业务，再通知插件切换图标和文字。actionId只用于本次点击。
        resolveWallpaperPreviewAction({ previewId: event.requestId,
          actionId: event.actionId, succeeded: true, liked: nextLiked,
          fail(error) { console.error(error.errCode, error.errMsg) } })
      } else if (event.action === 'show-lock') {
        // 待业务动作完成后再更新模式，避免在忙碌时替换正在等待回执的按钮。
        resolveWallpaperPreviewAction({ previewId: event.requestId,
          actionId: event.actionId, succeeded: true,
          success() {
            updateWallpaperPreview({ previewId: event.requestId, mode: 'lock',
              fail(error) { console.error(error.errCode, error.errMsg) } })
          },
          fail(error) { console.error(error.errCode, error.errMsg) }
        })
      }
    },
    success(result) { console.log('预览关闭', result.state) },
    fail(error) { console.error(error.errSubject, error.errCode, error.errMsg) },
    complete(outcome) {
      // 此时预览会话结束。资源由调用方统一管理，继续使用时保留，使用结束后释放。
      console.log('预览结束', outcome.requestId, outcome.success)
    }
  })
}

export function closeFullScreen(previewId) {
  // previewId来自openFullScreen的返回值。取消走原预览fail(9358003)和complete。
  cancelWallpaperTask({ taskId: previewId,
    fail(error) { console.error(error.errCode, error.errMsg) } })
}

默认 like 使用 handler: 'native'，状态保留在当前预览会话，通过 like-change 事件供业务持久化。使用 handler: 'host' 时必须提供 onEvent 并完成对应 actionId。超时解除忙碌，迟到或重复回传返回9358001。

uni-app x 使用同一配置结构，完整带中文注释的强类型用法已放入 uni_modules/lizhao-wallpaper/example/uniappx/index.uvue 的 configuredPreviewUI 和 onPreviewEvent。其中还演示配置面板、图标输入、喜欢持久化及实时切换锁屏。uni-app 对应完整实现为 uni_modules/lizhao-wallpaper/example/uniapp/index.vue。

uni-app x 的 UTS 调用

普通模式和蒸汽模式都可使用下面的强类型函数，完整页面为 uni_modules/lizhao-wallpaper/example/uniappx/index.uvue。参数、回调和资源编号与前面的 JavaScript 相同。

import {
  exportWallpaper, WallpaperResult, WallpaperFail, ExportWallpaperOptions
} from '@/uni_modules/lizhao-wallpaper'

function exportVideoInUts(resourceId: string): string {
  // 所有时间均为输入视频绝对毫秒；前置素材必须至少有2000ms。
  const options: ExportWallpaperOptions = {
    resourceId: resourceId, startMs: 0, endMs: 2000, coverTimeMs: 1000, muted: true,
    success: (result: WallpaperResult): void => {
      // 只有导出成功才会得到新候选，记住其resourceId供预览/交接和后续释放。
      if (result.media != null) console.log('候选编号', result.media!.resourceId)
    },
    fail: (error: WallpaperFail): void => {
      // 保留主题、错误码和阶段，完整原生错误链可从底部报告复制。
      console.error(error.errSubject, error.errCode, error.stage, error.errMsg)
    }
  }
  // 立即返回请求编号，不是导出文件路径；需要取消时将此编号传给cancelWallpaperTask。
  return exportWallpaper(options)
}

完整示例

选择、编辑、导出与系统交接

下面串联选择、编辑、导出与系统交接。complete 表示本次插件调用结束，系统实际壁纸状态在结果字段中单独提供。iOS 完成保存和指引后仍需要在系统中选择并确认。

import {
  chooseWallpaperMedia, openWallpaperEditor, exportWallpaper,
  applyWallpaper, releaseWallpaperResources
} from '@/uni_modules/lizhao-wallpaper'

export function makeWallpaper() {
  // 资源由本次业务链独立持有，不能释放其他页面或会话的资源。
  const owned = []
  const logFailure = error => console.error(error.errSubject, error.errCode, error.errMsg)
  const release = () => {
    // 清理失败只记录错误，不递归调用release，避免繁忙资源形成无限重试。
    if (owned.length > 0) releaseWallpaperResources({ resourceIds: owned, fail: logFailure })
  }
  const fail = error => { logFailure(error); release() }
  chooseWallpaperMedia({ mediaType: 'video', fail,
    success(selection) {
      if (selection.media == null) return
      const source = selection.media.resourceId
      owned.push(source)
      // 编辑返回参数，原视频仍保留，取消时走统一fail和清理。
      openWallpaperEditor({ resourceId: source, fail,
        success(edited) {
          if (edited.edit == null) return
          exportWallpaper({ resourceId: source,
            startMs: edited.edit.startMs, endMs: edited.edit.endMs,
            coverTimeMs: edited.edit.coverTimeMs, muted: edited.edit.muted, fail,
            success(output) {
              if (output.media == null) return
              if (!owned.includes(output.media.resourceId)) owned.push(output.media.resourceId)
              // Android打开系统确认页；iOS保存实况并给出指引，用户仍需手动完成系统设置。
              applyWallpaper({ resourceId: output.media.resourceId, fail: logFailure,
                success(result) {
                  // 不把success等同壁纸生效。iOS通常是requires-user-action及unknown。
                  console.log(result.state, result.albumVerification, result.wallpaperVerification)
                },
                complete(outcome) {
                  console.log('系统交接调用结束', outcome.success)
                  // 系统交接完成后清理临时文件；Android服务保留独立的生产副本。
                  release()
                }
              })
            }
          })
        }
      })
    }
  })
}

页面生命周期还应取消未完成任务并在可释放时清理素材。可运行页面及其资源清理、失败处理和日志复制流程位于 uni_modules/lizhao-wallpaper/example/uniapp/index.vue 与 uni_modules/lizhao-wallpaper/example/uniappx/index.uvue。

完整页面的预览、保存和设置按钮会先核对当前原素材与选段参数，视频缺少匹配候选时自动导出，再继续目标操作。重新编辑或修改毫秒参数后会重新生成。导出失败、取消或页面卸载会终止后续操作，原始实况可直接进入预览、保存或系统交接。

接入自有页面时，在编辑成功后传入 result.edit，在导出成功后记录 result.media.resourceId。导出结果同时包含 media 与 edit，其中 edit 记录本次输入选段，应保留新候选供后续调用。连续请求需要同时维护当前任务编号，并按各自的 complete 回执结束状态。

切换分类保留已选择的素材和选段；当前素材类型与分类不匹配时需要重新选择，避免误用上一分类的资源。任务进行中分类暂不可切换，可用“取消当前任务”结束操作。视频导出成功后自动继续预览、保存或设置，不必先手动点击生成。

API 用途速查

参数、默认值与回调

各方法的参数对象对应 uni_modules/lizhao-wallpaper/utssdk/interface.uts，没有按宿主另起一套 API：

getWallpaperCapabilities() 和 getWallpaperDiagnostics() 不接收参数，分别同步返回能力对象与脱敏 JSON 文本。以上其他方法立即返回 string 类型的请求编号。参数字段含义如下：

所有异步方法立即返回请求编号，结果经回调派发。getWallpaperState(null) 查询当前系统状态。持续进度监听本阶段未提供，完整原生阶段可在诊断中查看。

success(result: WallpaperResult) 与 fail(error: WallpaperFail) 二选一，随后执行 complete(outcome: WallpaperComplete)，每个回调至多一次。outcome.success 表示调用是否成功，outcome.result/outcome.error 分别为对应回执或null。回调中的异常被独立隔离，不阻止本次complete。取消请求的回调与原任务回调各自独立，接入方仍需等待原任务终态。全屏预览通过onEvent持续交付状态与动作，中途动作保留预览会话，一次性回调在该会话终态执行，事件监听随会话结束释放。

全屏预览配置

previewWallpaper 的新增字段均为可选项。其他使用 WallpaperResourceOptions 的API只读取各自业务参数。

主题、预览与图标

默认操作栏图标采用24pt/dp画布、2pt/dp圆端线条和统一绘制风格，点击区域至少44pt/dp。桌面与Dock使用独立的完整彩色应用图形，Dock按电话、浏览器、联系人、音乐排列。自定义操作图标按固定容器等比适配，建议交付同一套24单位设计网格、相同线宽与留白的透明PNG；自定义桌面图标可使用完整的方形应用图形。

默认直接进入全屏锁屏预览：左上返回、居中“锁屏预览 / 桌面预览”分段器和右上渐变“应用”按钮常驻；在画面区域左右滑动可切换锁屏与桌面，实况资源进入后自动播放。锁屏按锁图标、日期、大号时间排列；桌面采用两排应用图标、贴底磨砂Dock，两个模式圆点与顶部选中状态同步。系统状态栏和底部手势条由设备提供，时间默认随可见界面更新；配置 clockText 或 dateText 时保留指定文本。页面仍是App内效果预览，实际应用保持系统确认或保存后手动设置流程。

显式配置额外动作、播放控件或操作提示时保留工具层，点按媒体可显示或收起，返回与顶部导航始终可用。initialMode: 'media' 和 updateWallpaperPreview({ mode: 'media', ... }) 继续支持纯素材模式，此时顶部两段均不选中；直接点击任一分段进入对应模拟模式。自定义动作、媒体播放与实况长按能力保持原合同。

所有图标地址最多2048个UTF-16字符，支持HTTP(S)、file://、应用可访问绝对路径以及 static/、/static/、_www/、_doc/、/uni_modules/ 资源前缀。具体图片由开发者准备。地址为空使用默认图标。优先使用PNG/JPEG，GIF取首帧，WebP以当前系统解码支持为准。SVG及无法解码的文件回退默认图标并触发 icon-error。

单张文件上限4MiB，源图单边上限4096像素，网络超时15秒。加载期间、失败、超限时均保留默认图标，更新配置会隔离旧请求，关闭界面释放加载任务。远程地址仍遵循宿主的ATS/网络安全配置，推荐HTTPS。

动作与保存分享

内置id为 like、download、share、apply、preview，其中preview打开桌面/锁屏选择，取消选择保留当前模式。原图模式可显式设置 initialMode: 'media' 或调用 updateWallpaperPreview；启用附加操作时也可在模式选择中返回原图。自定义id必须由host处理。系统分享的目标App决定如何接收文件，files 不保证对方将图片与视频识别为实况。Android回执 share-sheet-opened 表示已交接系统分享面板，iOS按系统完成回执返回 shared 或 share-cancelled。

界面文字

以下字段位于 ui.texts，均可选，类型均为string，长度按UTF-16字符计。空字符串用于隐藏对应自定义文字，必要的无障碍名称保留默认值。

实时更新、业务回传与事件

表中的update、resolve分别代表 updateWallpaperPreview、resolveWallpaperPreviewAction 的参数对象。更新期间有动作等待时返回9358008，已关闭或失效会话返回9358001。更新UI是完整替换，更新少量字段时建议由业务保存当前配置并合并后传入。控制请求返回自己的编号，原预览请求持续有效直到关闭。

ready 表示媒体与控件就绪，mode-change 和 like-change 表示状态已改变。action 表示接受点击，每次接受的动作产生对应结果事件。icon-error 携带9358005及图标槽位，界面继续显示默认图标。仅host的action事件需要调用resolve，事件监听异常会被隔离并记录。预览关闭后停止新事件，释放监听随预览会话结束完成。

已提交的相册写入或系统分享可能在关闭预览后继续持有资源。完整流程应保留resourceId，释放返回9358008时等待后重试。两宿主完整示例在卸载时每秒重试忙碌释放，最多五分钟，期间的新候选会继续登记并清理，其他错误保留到诊断。最小纯预览示例关闭后即可按回执释放。

能力检测

WallpaperCapabilities 提供 platform、systemVersion 与 implementation/reason，以及 chooseVideo、chooseLivePhoto、exportCandidate、visualEditor、preview、saveToAlbum、systemWallpaperPicker、directApply 和 wallpaperEligibility。以实际布尔字段决定按钮和业务路径，不按 Vue2/Vue3 或 Vapor 名称推断系统能力。directApply=false 表示不能绕过系统确认；iOS 的锁屏素材资格仍为 unknown，旧系统可为 unsupported-os。

结果与生命周期

WallpaperResult 包含 operation、requestId、state、media、edit、target、assetId、albumVerification、wallpaperVerification、releasedCount 与 message。media 提供真实文件路径、字节数、时长、方向后的显示尺寸和来源。edit 提供起止、封面毫秒及静音选择。所有时间为毫秒。

albumVerification=verified 表示读取回目标相册资产并核对输出类型，iOS实况还检查实况标记。权限或系统无法核实时返回 unknown。wallpaperVerification=active/inactive/unknown 表达实际可观测的壁纸状态。iOS 查询保持 unknown，保存与指引成功为 requires-user-action。Android 打开系统预览可能先返回 system-ui-opened，应按实际回执或后续查询核对。

Android 状态判断会同时核对系统组件查询与当前非预览壁纸服务的素材、生命周期和真实首帧。系统查询受到权限或可见性限制时，空结果保持 unknown，不会据此删除待确认素材；仅有历史保存记录或系统确认回执也不能证明视频已生效。当前服务确已渲染匹配素材后可返回 active。系统明确使用其他组件、或请求素材与当前已核验素材不同时返回 inactive。无法确认桌面或锁屏目标时，target 仍为 unknown，不由 active 推断为两者都已设置。

iOS 的 applyWallpaper 在获得相册保存回执、核验资产并展示设置指引后返回 requires-user-action，同时交付 assetId 和 albumVerification。用户可随后前往系统设置，指引窗口的“知道了”按钮只负责关闭窗口。iOS 16 及更低版本无法进入新的锁屏实况设置流程时，预览失败面板提供“保存到相册”和“知道了”，前者只有收到真实相册保存回执后才显示成功。已有窗口尚未关闭时，新交互请求可能返回 9358008，关闭后重试。无法展示指引窗口时，已取得的保存结果和文字操作指引仍通过成功回执提供。

取消完成、预览关闭、导出成功、相册保存与壁纸生效分别有独立含义。系统持有的壁纸生产文件与页面临时资源分别管理，资源释放以服务引用和返回结果为准。

错误码说明

统一 errSubject 为 lizhao-wallpaper，失败同时保留操作、请求、阶段和可采集的原生类型、原因及堆栈摘要。日志与复制前统一脱敏。

注意事项

宿主与渲染模式兼容性

uni_modules/lizhao-wallpaper/package.json 的 Vue2、Vue3、app-vue、Android、iOS 与蒸汽模式声明为支持。该表描述已提供的源码接入范围，匹配基座及真实业务效果仍按下一节验收。普通模式和蒸汽模式必须分别构建，不能用其中一项推断另一项。配置方式参考 DCloud 蒸汽模式说明；插件目录和根入口遵循 DCloud UTS 插件规范。

app-nvue 的页面接入未单独验收，市场字段保留未声明。Harmony、Chrome/Safari Web、所有小程序与快应用没有壁纸业务实现，市场字段明确为不支持；调用进入不支持分支时返回9358002。Web示例和日志报告可以编译，不代表浏览器可以设置系统动态壁纸。暗黑模式、宽屏与多语言未提供专项适配，当前示例和原生交互文案为中文。

工具、系统与验收层级

本候选按 HBuilderX 5.34.0 及以上维护，当前本地验证使用5.34.2026102909，不承诺截图中4.84版本可用。Android最低API23，iOS素材选择与处理要求14+，新壁纸指引要求17+。不同厂商ROM、编解码器、系统壁纸交互和锁屏规则仍有设备差异。

资源构建、实际生成Kotlin/HX运行库联编、Swift语法及Foundation核心检查分别记录。Apple SDK完整SwiftCompile/链接、匹配基座运行、两端真实媒体/编辑UI/壁纸效果和实际剪贴板验收均待统一基座后完成。Vapor按工具规则跳过LSP，以真实构建交叉验证；静态检查和资源导出不能代替上述设备验收。

原生配置、权限与基座

Android使用系统选择和确认，API23–28保存到相册时按需请求写入权限，API29+通过MediaStore提交。自定义远程图标使用网络权限，BIND_WALLPAPER由系统绑定服务。iOS的PHPicker与后续保存核验分别按系统机制授权，有限授权/拒绝时保留真实错误或unknown。原生配置由插件目录交付。

远程图标会向开发者配置的地址发起图片请求，接入方需保证地址与应用隐私说明一致。Android分享使用独立只读副本，保留24小时并在后续分享时清理过期副本，系统可按缓存策略更早回收。iOS分享期间持有资源引用，收到系统完成回执后释放。分享期间关闭预览会清理界面与等待中的业务动作，已提交的相册写入仍保留真实最终回执。

新增或修改 Swift/Kotlin、系统服务、Manifest、权限或原生配置后，需要重新原生联编或制作匹配自定义基座。appResource/WGT 不能更新旧基座内已经编译的原生实现。本轮按开发流程完成源码后再统一制作基座。

素材范围、资源与隐私

iOS 视频合成候选与原始实况的锁屏动态资格由系统判断。App 内预览、相册识别、系统动态选项和锁屏唤醒播放均应分别验证。低电量状态、素材运动和系统版本可能影响效果。原始实况保留配对原件，视频候选不包含原音轨。

原生全屏预览默认以等比填充显示真实视频或实况，可配置为等比适配。桌面与锁屏模式叠加示意图标、日期和时钟，配置只影响显示，导出素材沿用原选段参数。系统最终裁切和动态效果需要在系统预览及真机锁屏中核对。Android 预览继承当前素材的静音设置，编辑封面滑块松手后停留在所选帧，继续播放可使用编辑器播放按钮。

Android 在窄屏、横屏或大字号下分别滚动较长的标题和操作区域，保留完整文案及关闭/播放入口。模拟桌面与锁屏的装饰按剩余空间显示，无法完整容纳的图标行或日期会收起，不影响真实操作按钮。默认星期使用中文，自定义日期与图标配置保持原意。

applyWallpaper 的新系统指引要求 iOS 17+。iOS 14–16 会在申请照片权限或保存之前返回 9358002，仍可独立使用素材选择、预览、导出及 saveWallpaperToAlbum。

iOS 视频输入上限为 512MiB，显示尺寸单边上限为 4096 像素。当前进程最多持有 16 个素材、8 个任务，同时只执行一个重型导出。原生诊断最多保留 400 条及约 256KiB，发生容量淘汰会记录丢弃数量。照片库有限授权或资产不可读时，相册核验会说明实际范围。

uni_modules/lizhao-wallpaper/utssdk/app-ios/PrivacyInfo.xcprivacy 声明应用私有文件及用户所选文件的大小、元数据读取用途。原始媒体和诊断默认保留在本地，插件不进行追踪或自动上传。

Android 编辑使用固定版本的官方 Media3 仓储依赖，原生服务按可见性管理播放。文件操作仅作用于插件私有目录，系统相册原件和用户输入文件保留。不要把临时 resourceId 当作长期业务编号。完整原件和视频路径只在业务调用边界返回，诊断不保留明文路径或媒体内容。

Android 最低为 API 23，使用 androidx.media3:media3-transformer:1.8.0。单个素材最多 512MiB，输入视频最长一小时，临时素材最多 16 项。选段与封面时间使用整数毫秒。实况输入限具有标准 XMP 尾部视频长度信息的 JPEG Motion Photo，未知厂商容器明确返回格式错误。相册保存能力可通过 saveToAlbum 查询。

Android 的 active 需要当前非预览壁纸服务与已提交素材相符，并已有真实首帧证据；退到后台暂停不代表壁纸已被替换，服务销毁、换源或播放错误后会重新核验。Android 13 及以下的组件查询可能受权限限制，插件不为状态查询申请宽泛的应用列表权限；Android 14 及以上使用 Manifest 中的壁纸服务精确查询声明。不可观测时返回 unknown 并保留待确认素材，建议回到桌面后再查询，原生诊断区分查询受限与服务首帧证据。临时资源释放后，壁纸服务使用独立持久化副本。iOS 原始实况保留音轨，视频生成候选采用静音。

底部报告包含插件版本来源、源码标记、运行环境、可采集的编译器/运行时字段、完整操作日志与原生诊断。安装包 HX、基座身份及无法取得的信息明确为 unknown，可在云打包时补充构建证据。复制失败保留同一快照及分段序号，并显示可手动复制的原文。Windows Web 在生成快照时固定 CRLF 换行，正文长度与完整/分段复制使用同一份字符串，分段不拆开换行或表情字符。

作者系列 UTS 插件

以下系列清单由项目统一发布清单生成。具体能力和适用范围请查各插件详情页。