weapp-vite/dist/docs/uni-app-component-libraries.md

weapp-vite 一个现代化的小程序打包工具

# uni-app 组件库兼容（实验性）

> [!WARNING]
> 这是实验性能力，当前兼容基线固定为 `@wot-ui/ui@2.2.0` 与 `uview-plus@3.8.86`。默认完全关闭；只有项目源码和 `weapp.uniApp.include` 明确列出的 npm 包会进入 uni-app 方言转换。

## uview-plus

```bash
pnpm add weapp-vite wevu uview-plus@3.8.86
```

```ts
import { defineConfig } from 'weapp-vite/config'
import { UviewPlusResolver } from 'weapp-vite/resolvers'

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: '@use "uview-plus/theme.scss" as *;\n',
      },
    },
  },
  weapp: {
    uniApp: {
      include: ['uview-plus'],
    },
    autoImportComponents: {
      resolvers: [UviewPlusResolver()],
      vueComponents: true,
      vueComponentsModule: 'wevu',
    },
  },
})
```

应用启动时调用 `mount$u()`，再把 `uni.$u` 同步到 `app.config.globalProperties.$u`；全局样式引入 `uview-plus/index.scss`。不要使用会在 Web 调用 `Vue.component` 的默认插件注册流程。

仓库兼容矩阵还通过 pnpm patch 修复了 3.8.86 中 `u-slider` 设置 `height` 时引用未定义变量 `val` 的缺陷。复用同一基线时应保留 `patches/uview-plus@3.8.86.patch`；升级 uview-plus 后先确认上游是否已经修复，再决定是否移除补丁。

`UviewPlusResolver()` 同时解析 `u-*` 与 `up-*` 标签。静态清单以 3.8.86 npm 发布包中的 137 个顶层 SFC 为准，双前缀共 274 个标签；135 个具名组件各有独立测试页。`u-action-sheet-data` 与 `u-column-notice` 没有组件名，分别由 action-sheet 和 notice-bar 页面覆盖。

`supportFilesStrategy` 默认为 `'used'`；需要生成全量组件辅助文件时可传入 `UviewPlusResolver({ supportFilesStrategy: 'full' })`。

## 微信开发者工具回归分层

组件库 IDE 验收拆分为运行时、代表性视觉和全量视觉三种命令。运行时命令覆盖全部组件页面的行为与交互，不调用截图；视觉命令独立执行截图对比。

```bash
pnpm e2e:ide:component-libraries
pnpm e2e:ide:component-libraries:visual
pnpm e2e:ide:component-libraries:visual:full
```

也可以分别运行 `pnpm e2e:ide:uview-plus`、`pnpm e2e:ide:wot-ui` 及其 `:visual` / `:visual:full` 变体。视觉套件在 `App.captureScreenshot` 协议超时后轮换 DevTools 会话；自动恢复只处理连接级错误，视觉差异仍会直接失败。

## Wot UI

## 安装

```bash
pnpm add weapp-vite wevu @wot-ui/ui@2.2.0
```

## 配置

```ts
import { defineConfig } from 'weapp-vite/config'
import { WotUiResolver } from 'weapp-vite/resolvers'

export default defineConfig({
  weapp: {
    uniApp: {
      include: ['@wot-ui/ui'],
    },
    autoImportComponents: {
      resolvers: [WotUiResolver()],
      vueComponents: true,
      vueComponentsModule: 'wevu',
    },
  },
})
```

`WotUiResolver()` 使用 Wot UI 2.2.0 的真实公开 SFC 清单建立标签映射，并返回 `sourceType: 'wevu-sfc'` 与可解析的源码 ID。不要自行假设所有 `wd-*` 标签都能通过目录名拼接得到入口。

`weapp.uniApp` 的行为：

- 未配置或设为 `false` 时不扫描依赖，也不改变现有项目行为。
- 项目源码自动参与 uni-app 条件编译；npm 依赖必须出现在 `include` 白名单中。
- 微信目标启用 `MP-WEIXIN`，Web 目标启用 `H5`。
- 支持 script、template、style 中嵌套的 `#ifdef`、`#ifndef`、`#else`、`#endif` 和 `A || B`。
- 自由 `uni` 引用会在小程序目标静态绑定到 `wx`；Vue 运行时导入会按组件源码需要改写到 `wevu`。
- 转换错误会包含包名、SFC 路径和区块类型，不会静默输出残缺组件。

## 启动与构建

```bash
# 微信小程序
pnpm dev
pnpm build

# Web
pnpm dev:web
pnpm build:web
```

微信产物通过项目根 `project.config.json` 导入微信开发者工具。Web 项目需要按 Web runtime 约定提供引用 `/@weapp-vite/web/entry` 的 `index.html`。

## 兼容矩阵

矩阵以 `@wot-ui/ui@2.2.0/global.d.ts` 实际公开的 99 个 Vue SFC 为准。每个组件都有独立页面；依赖父容器的组件会在自己的页面内使用最小父组件承载。

```text
组件 | 独立页 | Web | 微信小程序 | Headless
wd-action-sheet | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-avatar | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-avatar-group | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-backtop | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-badge | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-button | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-calendar | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-calendar-view | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-card | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-cascader | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-cell | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-cell-group | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-checkbox | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-checkbox-group | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-circle | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-col | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-collapse | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-collapse-item | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-config-provider | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-count-down | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-count-to | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-curtain | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-datetime-picker | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-datetime-picker-view | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-dialog | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-divider | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-drop-menu | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-drop-menu-item | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-empty | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-fab | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-floating-panel | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-form | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-form-item | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-gap | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-grid | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-grid-item | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-icon | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-image-preview | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-img | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-img-cropper | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-index-anchor | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-index-bar | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-input | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-input-number | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-keyboard | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-loading | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-loadmore | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-navbar | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-navbar-capsule | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-notice-bar | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-notify | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-overlay | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-pagination | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-password-input | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-picker | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-picker-view | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-popover | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-popup | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-progress | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-radio | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-radio-group | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-rate | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-resize | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-root-portal | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-row | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-search | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-segmented | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-select-picker | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-sidebar | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-sidebar-item | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-signature | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-skeleton | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-slide-verify | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-slider | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-sort-button | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-step | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-steps | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-sticky | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-sticky-box | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-swipe-action | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-swiper | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-swiper-nav | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-switch | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-tab | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-tabbar | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-tabbar-item | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-table | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-table-column | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-tabs | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-tag | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-text | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-textarea | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-toast | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-tooltip | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-tour | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-transition | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-upload | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-video-preview | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
wd-watermark | 是 | 行为+移动/桌面视觉 | 行为+视觉 | 行为
```

`wd-swiper-indicator` 和 `wd-tour-step` 没有独立公开 SFC，分别在 `wd-swiper` / `wd-swiper-nav` 与 `wd-tour` 场景中覆盖，不伪造 resolver 入口。

## 已知边界

- 兼容矩阵承诺默认渲染、代表性 props/slot 和至少一个稳定状态；不承诺每个组件的全部 props、业务组合或宿主权限流程。
- 当前只承诺微信小程序和 Web；支付宝、抖音等其他 uni-app 条件分支尚未纳入验收。
- 这是面向当前组件场景的兼容层，不是完整 uni-app 运行时。未被组件触达的 `uni.*` API 不会因此自动具备实现。
- 上传、视频、图片、裁剪、签名和倒计时示例应使用本地固定资源与测试 mock，避免依赖公网、用户授权或实时时钟。
- 外部 SFC 的样式、资源和最终产物仍由 Vite/Rolldown transform、emit 和 write 管理；不要通过脚本手写构建产物。