更新记录

1.1.2（2026-09-17） 下载此版本

• 移除组件级未登录预检（1.1.1 引入的 openidMissing 选图入口拦截）：正常流程 （页面登录守卫 + getUserInfo 后放开组件）下不可达，且未登录时上传第一步 getOssAuth 即 401 失败、已登录未加载资料时 mediaCheckAsync 有 「用户资料未加载，请重试」兜底——组件不再感知登录态，保持单一职责。 使用前提（登录态与用户信息由宿主页面保证）已写入组件头注释与 readme。

1.1.0（2026-09-17） 下载此版本

• 审核开关（自动判定 + 可覆盖）：新增 isAvatarReviewEnabled() 与 setup 配置 reviewEnabled?: boolean | (() => boolean)。
  • 默认自动判定：仅微信小程序非开发版（体验版 / 正式版）启用内容安全检测； 开发版（开发者工具 / 开发预览）联调免审；微信 H5、支付宝 H5、App 等环境无小程序检测通道，恒免审。
  • 免审模式下上传成功即回写 v-model 并触发 approve，toast「头像已更新」，无「审核中/继续检测」环节。
  • avatar-review-core 的 createAvatarReviewModel 新增 reviewEnabled 选项（默认 true，纯逻辑层不感知平台）。

平台兼容性

uni-app(5.24)

uni-app x(5.24)

wc-avatar-picker

头像上传组件：选图 → OSS 直传（依赖 wc-upload）→ 微信内容安全异步检测（轮询结果）， 审核通过才回写 v-model，未通过 / 审核中的图片只作预览，不会写入业务资料。

封装自 won-passion-for-sports（uni1）的 ProfileAvatarPicker + modules/security 实现，逻辑与视觉保持一致。

安装前置

1. 已安装 wc-upload ≥ 1.1.0（及其依赖 wc-request，已 setupWcAuth()）
2. 已安装 uni-icons（相机角标图标）
3. wc-upload 已按项目体系配置授权端点（见下），server 已放行 OSS 上传域名
4. 宿主在 main.ts 调用一次 setupWcAvatarPicker()（见下）

宿主接线（本项目 main.ts 已配置）

插件无法感知宿主账号体系，openid / 应用标识需一次性注入； 本项目（收款 3.0）的接线方式：

import { useAuthStore } from "@/uni_modules/wc-auth/commons";
import { setOssAuthUrl } from "@/uni_modules/wc-upload/commons/api";
import { setupWcAvatarPicker } from "@/uni_modules/wc-avatar-picker/commons/config";

// 本项目登录体系为 wonUser，OSS 授权走 /core/mobile/wonUser 路径
setOssAuthUrl("/core/mobile/wonUser/aliyun/ossAuth");

setupWcAvatarPicker({
    // openid 取当前登录账号快照（小程序登录必有；需先 getUserInfo() 加载）
    getOpenid: () => useAuthStore().userInfo?.account?.openid || "",
    // 与登录 wcappid 同源（.env 的 VITE_APP_WCAPPID）
    wcAppId: (import.meta.env.VITE_APP_WCAPPID || "").trim(),
    // 兜底图：本项目无默认头像资源，留空显示灰底圆形占位
    fallbackSrc: "",
    // 审核开关（可选，缺省自动判定）：仅微信小程序非开发版启用检测；
    // 开发版联调、微信 H5 / 支付宝 H5 等环境自动免审（上传成功即过审）。
    // 需要强制覆盖时传 boolean 或函数，例如体验版也免审：
    // reviewEnabled: () => {
    //   try { return uni.getAccountInfoSync().miniProgram.envVersion === "release" }
    //   catch { return true }
    // },
});

• getOpenid 返回空时，提交检测直接报「用户资料未加载，请重试」； 使用组件的页面应先 await getUserInfo()（mine 页已有此调用，store 有缓存直接复用）。
• server 侧需保证 wc_app_id（wonCollectPayment）已在望潮用户中心登记本小程序的 appid/secret，/core/mobile/security/mediaCheckAsync 才能对 openid 发起检测。

使用（easycom，免注册）

<template>
    <wc-avatar-picker
        ref="avatarPickerRef"
        v-model="form.headimgurl"
        :avatar-size="176"
        tip-text="点击更换头像"
        :disabled="pageLoading"
    />
</template>

<script setup lang="ts">
interface AvatarPickerInstance {
    hasPending: () => boolean
    isBusy: () => boolean
}
const avatarPickerRef = ref<AvatarPickerInstance | null>(null)

// 保存前统一拦截：上传/审核进行中，或存在待审核候选头像
const avatarBusy = computed(() => avatarPickerRef.value?.isBusy() ?? false)
const hasPendingAvatar = computed(() => avatarPickerRef.value?.hasPending() ?? false)
</script>

本项目用户信息字段为 headimgurl（wc-auth WonUserInfo），绑定时注意字段名。

Props

Events

实例方法（ref 调用）

行为约定

SDK（commons）

// 统一出口（mp-weixin 下如遇 barrel 问题，可直接 import 具体模块）
import {
    setupWcAvatarPicker,
    createAvatarReviewModel,   // 审核状态机（纯逻辑，可复用到昵称等其它资料检测）
    mediaCheckAsync,           // 提交微信异步检测
    waitForMediaCheckResult,   // 轮询检测结果
    isMediaCheckPassed,        // 回调结果判定
    MEDIA_SCENE,
    MEDIA_TYPE,
} from '@/uni_modules/wc-avatar-picker/commons'

范围说明

刻意不包含（保持简单）：

• 资料保存接口（各业务自己提交 v-model 拿到的过审 URL）
• 装饰边框 / 认证徽标等展示形态（宿主可自行包一层或改样式）
• 昵称等文本检测（createAvatarReviewModel 已解耦依赖，可参照组件接线复用）