做多端业务时，最容易拖慢进度的不是接口，而是页面层：H5 一套间距，小程序一套安全区，App 又要处理状态栏和底部横条。@hy-app/ui 的定位很明确：面向 uni-app + Vue3 + TypeScript，用一套 hy-* 组件覆盖 H5、App vue 页面和常见小程序。

我按当前源码 @hy-app/ui@1.1.0 核对了一遍：包内有 90 个 hy-* 组件目录，package.json 的平台矩阵写得很直白。它不是“理论上跨端”的库，边界先摆出来，后面用起来才不会踩坑。

它解决了什么问题

1. 组件数量够业务用

当前源码包含基础、布局、表单、导航、数据展示、反馈和业务组件：

• 基础：hy-button、hy-icon、hy-image、hy-text、hy-tag、hy-badge
• 布局：hy-flex、hy-grid、hy-sticky、hy-scroll-list、hy-list、hy-waterfall
• 表单：hy-form、hy-input、hy-textarea、hy-upload、hy-picker、hy-calendar、hy-cascader
• 导航：hy-tabs、hy-tabbar、hy-navbar、hy-steps、hy-index-bar
• 数据：hy-table、hy-parse、hy-read-more、hy-skeleton、hy-empty
• 反馈：hy-popup、hy-modal、hy-toast、hy-notify、hy-action-sheet
• 业务：hy-price、hy-coupon、hy-submit-bar、hy-watermark

这类组件清单的价值不在“多”，而在常见业务不用再手写。比如设置页可以直接用 hy-cell + hy-cell-item，提交订单栏不用自己算安全区。

2. TypeScript 不是口号

包内每个组件都有 props.ts 和 typing.d.ts。props.ts 里的注释包含用途、可选值和默认值，typing.d.ts 描述事件和暴露方法。

这对实际开发很有用。比如 hy-form：

export interface IFormExpose {
  validate: () => Promise<boolean>
  resetFields: () => void
  clearValidate: (fields?: string[]) => void
  submit: () => Promise<AnyObject | boolean>
  formData?: AnyObject
  errors?: Record<string, string>
}

写代码时能直接知道 submit() 返回 Promise，不需要翻实现。

3. easycom 按需引入

组件标签统一使用 kebab-case，例如：

<hy-button text="提交" />
<hy-input v-model="keyword" placeholder="搜索" />

配置 easycom 后不需要手动 import 组件。构建时只处理页面里出现的组件，代码也干净。

4. 主题走变量

组件颜色依赖 --hy-* 变量。主色实际由 --hy-theme-color 驱动，暗色模式由 hy-theme--dark 这组变量驱动。也就是说，换品牌色、适配暗色，不是到处改样式，而是修改变量。

先安装

前提条件要记住：只支持 Vue3，不支持 Vue2。Node 建议 16.14.0 以上。官方文档还要求 Sass 版本高于 1.78.0 且不超过 1.101.0，示例给的是 1.98.0。

pnpm add @hy-app/ui
pnpm add dayjs
pnpm add -D sass@1.98.0

dayjs 不是可选项。时间选择器依赖它，项目里没有就要装。

四步接入

1. 注册全局工具

修改 src/main.ts：

import { globalRegister } from '@hy-app/ui'
import { createSSRApp } from 'vue'
import App from './App.vue'

export function createApp() {
  const app = createSSRApp(App)
  app.use(globalRegister)
  return { app }
}

globalRegister 会挂载 $hy.addUnit、$hy.random、$hy.formatTime、$hy.bytesToSize 这类工具。

2. 配置 easycom

修改 src/pages.json：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^hy-(.*)": "@hy-app/ui/components/hy-$1/hy-$1.vue"
    }
  }
}

3. 引入全局样式

修改 src/uni.scss：

@use '@hy-app/ui/index.scss' as *;

漏了这一步，组件还能渲染，但变量、基础样式和图标样式会不完整。

4. 开启类型识别

修改 tsconfig.json：

{
  "compilerOptions": {
    "types": ["@hy-app/ui/global"]
  }
}

支持范围和边界

当前包的平台矩阵：

能力	支持情况
Vue3 uni-app	支持
H5	支持
App vue 页面	支持
nvue	不支持
uni-app-x	不支持
微信小程序	支持
支付宝小程序	支持
QQ 小程序	支持
抖音小程序	支持
鸿蒙小程序	支持
百度、快手、京东、飞书小程序	不支持
Vue2	不支持

这些信息来自包内 package.json 的 uni_modules.platforms，不是宣传语。技术选型时可以直接拿这张表过架构评审。

我会怎么用

场景一：标准业务后台

H5 管理侧用 hy-form 做筛选，用 hy-table 做结果，用 hy-pagination 做分页。需要移动端操作时，把操作列换成 hy-button size="mini"。

场景二：商城小程序

首页用 hy-swiper 和 hy-grid，详情页用 hy-price、hy-count-down、hy-submit-bar，列表用 hy-waterfall，订单确认用 hy-cell。

场景三：审批与签署

表单用 hy-form，附件用 hy-upload，签名用 hy-signature，页面加 hy-watermark 防截屏扩散。

三个容易误判的点

1. 它是未编译的 Vue + TS 包。 不要把它当纯 JS 包处理，版本、Vite 缓存和依赖预构建都可能影响开发体验。
2. nvue 页面不要硬用。 平台矩阵已经标明不支持，nvue 页面应换 vue 页面或原生实现。
3. 不要覆盖内部 BEM 类。 例如 hy-button__text 这类内部结构可能随版本变化。局部调整优先用 customStyle、customClass，主题调整用 --hy-*。

一个极端用法：局部主题

大多数项目会在根节点包 hy-config-provider，但有些页面要临时呈现另一个品牌色。可以这样：

<template>
  <hy-config-provider theme="light" theme-color="#00b42a" padding="16px">
    <view class="activity">
      <hy-button text="领取券包" />
      <hy-input placeholder="输入手机号" />
    </view>
  </hy-config-provider>
</template>

这只影响该容器内部的主色变量，不影响外层页面。做活动页、嵌入页、多租户皮肤时很有用。

结尾

如果你觉得这篇文章帮你解决了你现在的问题，那就请给我来个 三连支持一下 ♥️

➡️ 点赞 支持一下
➡️ 收藏 以防找不到
➡️ 评论 我会回访你！
➡️ 关注 不会迷路哦！

你的支持是我持续更新的动力，我们下篇更精彩！🚀🔥

参考github项目地址：hy-design-uni
官方文档: https://www.hy-design-uni.top

👉 欢迎大家给华玥组件库star。 ✅