shujie-ui

一个基于 Vue 3 + TypeScript 的 UniApp 组件库，兼容小程序、H5、App。

特性

• Vue 3 + TypeScript + Composition API
• SCSS 设计系统（色彩/排版/间距/圆角/阴影）
• 全平台兼容（微信/支付宝/百度/字节/QQ 小程序 + H5 + App）
• 按需引入（easycom 自动注册）
• 单元测试覆盖
• 配套 VitePress 开发者文档（说明书 + 浏览器里粗看效果；验收以 UniApp 工程真机/模拟器为准）

安装

npm install shujie-ui

快速上手

平台说明（必读）

| 场景 | 推荐方式 | 说明 | |------|----------|------| | uni-app 小程序（微信/支付宝等） | easycom + 包内 src/**/*.vue | 预打包的 dist/*.es.js 依赖标准 Vue 运行时辅助函数，与 @dcloudio/uni-mp-vue 不兼容，请勿在小程序里 import SjUI from 'shujie-ui' + app.use。 | | H5 / App、或仅工具函数 | app.use(SjUI) + dist/shujie-ui.css，或按需 import { SjButton } from 'shujie-ui' | 使用 npm 中的 dist 即可。 |

自 v0.1.1 起，发布包包含 src（组件源码、样式、utils、hooks），小程序请按下方 easycom 使用。

1. uni-app：easycom（小程序推荐）

将仓库根目录 easycom.json 中与 pages.json 同级的 easycom 段合并到你的 pages.json（或按下面手写）：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^sj-(.*)": "shujie-ui/src/components/sj-$1/sj-$1.vue"
    }
  }
}

组件 SFC 已内置 @import 设计变量与 mixin，宿主项目无需再为 shujie-ui 配置 Vite additionalData。

模板里直接使用（sj- 前缀 + 短横线）：

<template>
  <view class="page">
    <sj-button type="primary">按钮</sj-button>
    <sj-cell title="标题" value="内容" is-link />
  </view>
</template>

可选：在入口再引一次聚合样式（与 SFC scoped 并存，用于 reset等）：

import 'shujie-ui/dist/shujie-ui.css'

2. uni-app：按路径按需引入 .vue

<script setup lang="ts">
import SjButton from 'shujie-ui/src/components/sj-button/sj-button.vue'
</script>

3. H5 / 非小程序：全局引入 dist

组件样式集中在 dist/shujie-ui.css。在 main.ts：

import { createSSRApp } from 'vue'
import App from './App.vue'
import SjUI from 'shujie-ui'
import 'shujie-ui/dist/shujie-ui.css'

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

4. H5 / 非小程序：按需 import 命名导出

import 'shujie-ui/dist/shujie-ui.css'

<script setup lang="ts">
import { SjButton, SjCell } from 'shujie-ui'
</script>

<template>
  <sj-button type="primary">按钮</sj-button>
  <SjCell title="标题" value="内容" />
</template>

组件列表

| 组件 | 说明 | |------|------| | sj-button | 按钮，多种类型/尺寸/形状/状态 | | sj-icon | 图标（iconfont，需自行替换字体资源） | | sj-cell | 单元格列表项 | | sj-loading | 加载指示 | | sj-divider | 分隔线 | | sj-tag | 标签 | | sj-badge | 徽标 | | sj-space | 间距布局 |

设计系统

主色

| 名称 | 色值 | 用途 | |------|------|------| | Primary | #2979ff | 品牌主色 | | Success | #19be6b | 成功状态 | | Warning | #ff9900 | 警告提示 | | Danger | #fa3534 | 错误/危险 | | Info | #909399 | 次要信息 |

自定义主题

// 覆盖变量
$sj-primary: #1890ff;

// 然后引入样式
@import 'shujie-ui/src/styles/index.scss';

工具函数

import { addUnit, debounce, throttle, deepClone, isPhone, isEmail } from 'shujie-ui'

Hooks

import { useVisible, useLoading, useScroll } from 'shujie-ui'

开发者文档站（非 UniApp 运行时）

shujie-ui 是 UniApp 组件库：组件模板使用 view / text 等，面向小程序与 uni-app 编译链路；业务里请以 你自己的 UniApp 项目 为准做联调与上线。

本仓库里的 VitePress 只做两件事：写清 API / 接入方式（和一般组件库文档一样），以及在 普通浏览器 里用近似方式跑一遍 sj-*，方便扫一眼样式与交互。它不是小程序模拟器，也不能替代微信开发者工具 / HBuilderX 真机预览。

npm run docs:dev

浏览器打开终端里提示的地址（一般为 http://localhost:5173）。静态部署：

npm run docs:build

产物在 docs/.vitepress/dist，可托管到 Gitee Pages、Nginx 等，给团队当在线说明书。

源码仓库（Gitee + GitHub）

日常开发与 npm run release 一键发版 会以 Gitee 为主远程（origin）。若需 GitHub 镜像，在本地增加名为 github 的第二个远程即可；发版脚本会在 git push origin 之后自动 git push github（含版本 tag）。

本仓库 GitHub 地址：Jia-2001/shujie-ui。若本地尚未添加第二个远程，首次配置：

git remote add github https://github.com/Jia-2001/shujie-ui.git
# 或 SSH：[email protected]:Jia-2001/shujie-ui.git

# 首次对齐远端（任选其一：推送当前分支，或先 fetch 再合并）
git push -u github master
# 若 GitHub 默认分支为 main：git push -u github master:main

之后只需正常 npm run release，脚本会同时推送 Gitee 与 GitHub（若已配置 github 远程）。

链接

• npm 包
• GitHub 仓库
• Gitee 仓库

License

MIT