更新记录

1.4.0（2026-10-04） 下载此版本

• 新增 14 个基础表单组件（分批第 2 批）：
  • simple-input 输入框：类型（text/number/digit/password/idcard）、清空、字数统计、 前后置图标与插槽、三种边框模式、错误态与必填标记
  • simple-textarea 文本域：自动增高、字数统计、固定高度
  • simple-inputnumber 数字输入框：步进、范围收敛、精度控制
  • simple-search 搜索框：圆角 / 方形、清空、右侧操作区插槽
  • simple-radio-group / simple-radio 单选框：横向纵向、禁用、形状、选中色
  • simple-checkbox-group / simple-checkbox 复选框：最大勾选数（超出触发 overflow）
  • simple-switch 开关：三档尺寸、状态文字与配色、加载态
  • simple-slider 滑块：单滑块与双滑块区间、步长吸附、拖动回调
  • simple-rate 评分：半星、自定义星星数与配色、右侧分值
  • simple-upload 上传：选择、自动上传（带进度）、删除、预览、数量限制
  • simple-form / simple-form-item 表单校验（见下）
• 新增表单校验体系
  • 规则支持 required / min / max / pattern / 自定义 validator （validator 支持返回 false、错误信息字符串、或 Promise）
  • 方法：validate()、validateField(prop)、clearValidate()、resetFields()
  • 值变化时自动清除该字段的错误提示，用户改正后不会一直显示红字
  • 多字段并行校验，提升长表单响应速度
  • resetFields() 恢复到字段注册时的初始值（数组 / 对象做浅拷贝）
  • FormItem 插槽：label、默认（作用域 { value, error }）、error
• libs/theme.scss 补充表单类主题变量（输入框、单选复选、开关、滑块、 评分、表单标签与错误、上传）
• index.js 注册全部 27 个组件；库 readme 补齐各组件 API 表与校验规则说明
• demo 页「表单组件」分组扩到 12 项，新增 11 个演示区块

关键实现说明

• simple-inputnumber：输入过程中不立即收敛，失焦时才做范围与精度处理， 避免打断输入；用 toFixed 处理浮点误差（如 0.1 + 0.2）
• simple-rate 半星：把每颗星拆成左右两个触摸区，不依赖坐标计算（更可靠）
• simple-slider：触摸热区上下各留 24rpx，把细轨道的可点区域撑到 56rpx； 双滑块拖动自动判断目标并保证 start <= end
• simple-radio / simple-checkbox：label 是值，显示文字用 text 或默认插槽

1.2.9（2026-10-04） 下载此版本

• package.json 的 displayName 改为原名 + 简介内容去掉标点符号的版本
  • 与 description 信息保持一致，便于插件市场的检索匹配
  • 去掉中英文标点（，。、（）/ 等），并合并多余空格
  • 当前长度 100 字

1.2.6（2026-10-04） 下载此版本

新增 预览图

平台兼容性

uni-app(5.0)

simple-ui 简约组件库

一套基于 uni-app + Vue3 的 UI 组件库，覆盖大部分复杂业务应用场景，组件可直接投入使用，无需二次封装。

特性

• 面向业务场景设计：组件能力覆盖表单、选择、反馈等常见复杂业务需求，拿来即用
• 全平台兼容：App（Android / iOS）、H5、微信 / 支付宝 / 头条 / 百度 / 快手 / 京东 / QQ / 飞书 / 小红书 小程序
• easycom 按需引入：无需 import，直接用标签，不用的组件不会打包进产物
• SCSS 变量主题：覆盖变量即可整库换肤
• BEM 命名：sui- 前缀，不污染你的全局样式

安装

方式一：插件市场导入（推荐）

1. 在 HBuilderX 中打开你的项目
2. 访问 DCloud 插件市场，搜索 simple-ui
3. 点击「下载插件并导入 HBuilderX」，选择你的项目

导入后组件会出现在你项目的 uni_modules/simple-ui 目录下，无需任何额外配置。

后续更新：右键 uni_modules/simple-ui 目录 → 更新插件。

方式二：手动拷贝

把整个 simple-ui 目录拷贝到你项目的 uni_modules/ 下即可。

目录名必须保持为 simple-ui，改名会导致 easycom 失效。

环境要求

快速开始

插件内置 easycom 规则，无需 import 和注册，直接在页面里使用：

<template>
    <view>
        <simple-button text="提交" type="primary" @click="onSubmit" />
    </view>
</template>

<script>
export default {
    methods: {
        onSubmit() {
            uni.showToast({ title: '已提交', icon: 'none' })
        }
    }
}
</script>

全局注册（可选）

想一次性注册全部组件时使用：

// main.js
import { createSSRApp } from 'vue'
import App from './App.vue'
import SimpleUI from '@/uni_modules/simple-ui'

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

按需手动引入（可选）

需要在代码里持有组件引用时使用：

<script>
import { SimpleButton } from '@/uni_modules/simple-ui'

export default {
    components: { SimpleButton }
}
</script>

主题定制

组件内部所有颜色、尺寸都使用 !default 变量。在你项目的 uni.scss 中先引入主题文件、再声明覆盖值：

// uni.scss
@import '@/uni_modules/simple-ui/libs/theme.scss';

/* 覆盖主色 */
$sui-color-primary: #ff6b00;
/* 覆盖圆角 */
$sui-radius-base: 20rpx;

变量声明顺序必须在 @import 之后，因为 SCSS 后声明的变量覆盖先声明的。

常用变量

组件列表

simple-button 按钮

常用的操作按钮，支持 6 种类型、3 种尺寸与多种状态。

属性

插槽 / 事件

用法

<simple-button text="主要" type="primary" />
<simple-button text="成功" type="success" />
<simple-button text="朴素" plain />
<simple-button text="圆角" round />
<simple-button text="禁用" disabled />
<simple-button text="加载中" loading />
<simple-button text="通栏" block @click="onClick" />

simple-icon 图标

内置常用符号集，支持图片图标与图标字体接入。

事件：click

<simple-icon name="success" size="40" color="#19be6b" />
<simple-icon name="search" size="40" />
<!-- 接入自己的图标字体 -->
<simple-icon name="home" custom-prefix="iconfont icon-" size="40" />
<!-- 图片图标 -->
<simple-icon src="/static/logo.png" size="48" />

组件库不内置图标字体（避免体积膨胀与版权问题），内置符号集仅覆盖常用图标。 完整图标集请用 customPrefix 接入自己的字体，或用 src / 默认插槽。

simple-image 图片

事件：load、error、click 插槽：placeholder（加载中占位）、error（失败占位）

<simple-image src="/static/logo.png" :width="110" :height="110" :radius="12" />
<simple-image src="/static/logo.png" :width="110" :height="110" preview />

simple-avatar 头像

事件：click、error　插槽：默认

<simple-avatar src="/static/logo.png" size="large" />
<simple-avatar text="张" bg-color="#2979ff" />
<simple-avatar icon="user" bg-color="#19be6b" />
<simple-avatar src="/static/logo.png" shape="square" />

simple-badge 徽标

插槽：默认（徽标依附的内容）

<simple-badge :value="5"><view>消息</view></simple-badge>
<simple-badge :value="120" :max="99"><view>上限</view></simple-badge>
<simple-badge dot><view>圆点</view></simple-badge>

simple-tag 标签

事件：click、close　插槽：默认

<simple-tag text="主要" type="primary" />
<simple-tag text="朴素" type="primary" plain />
<simple-tag text="圆角" type="success" round />
<simple-tag text="可关闭" type="warning" closable @close="onClose" />

simple-progress 进度条

插槽：默认（替换百分比文字）

<simple-progress :percent="30" />
<simple-progress :percent="60" status="success" />
<simple-progress :percent="80" status="warning" :stroke-width="20" />
<simple-progress :percent="95" color="#8e44ad" />

simple-empty 空状态

插槽：默认（底部操作区）、image（替换占位图）

<simple-empty />
<simple-empty description="还没有添加任何商品">
  <simple-button text="去添加" type="primary" size="small" />
</simple-empty>

默认占位图用纯 CSS 绘制，不依赖图片资源，因此不会增加包体积。

simple-loading 加载中

插槽：默认（替换文案）

<simple-loading type="spinner" :size="40" />
<simple-loading type="circle" :size="40" color="#19be6b" />
<simple-loading type="dots" :size="40" color="#ff9900" />
<simple-loading type="spinner" text="加载中..." layout="column" />

simple-skeleton 骨架屏

插槽：默认（loading 为 false 时渲染）

<simple-skeleton :loading="loading" :rows="3" avatar>
  <view>真实内容</view>
</simple-skeleton>

动画用透明度呼吸而非渐变位移——小程序对 background-position 动画支持不稳定。

simple-divider 分割线

<simple-divider />
<simple-divider text="居中文字" />
<simple-divider text="靠左" position="left" />
<simple-divider text="虚线" dashed />
<simple-divider vertical />

simple-countdown 倒计时

事件：change、finish、start、pause 插槽：默认，作用域参数 { display, remain } 方法：start()、pause()、reset()

<simple-countdown :time="90000" />
<simple-countdown :time="90000" format="DD天HH时mm分ss秒" />
<simple-countdown ref="cd" :time="90000" :auto-start="false" @finish="onFinish" />

<!-- 通过 ref 控制 -->
this.$refs.cd.start()
this.$refs.cd.pause()
this.$refs.cd.reset()

simple-input 输入框

事件：update:modelValue、input、change、focus、blur、clear、confirm 插槽：prefix、suffix

<simple-input v-model="name" label="姓名" clearable placeholder="请输入姓名" />
<simple-input v-model="pwd" type="password" prefix-icon="user" />
<simple-input v-model="txt" :maxlength="50" show-word-limit />

simple-textarea 文本域

事件：update:modelValue、input、change、focus、blur

<simple-textarea v-model="desc" :maxlength="200" auto-height placeholder="请输入描述" />

simple-inputnumber 数字输入框

事件：update:modelValue、change、plus、minus

<simple-inputnumber v-model="count" :min="1" :max="99" />
<simple-inputnumber v-model="price" :step="0.1" :precision="2" />

输入过程中不立即收敛，失焦时才做范围收敛与精度处理，避免打断输入。 内部用 toFixed 处理浮点误差（如 0.1 + 0.2）。

simple-search 搜索框

事件：update:modelValue、input、change、search、clear、focus、blur、action 插槽：action

<simple-search v-model="kw" @search="onSearch" />
<simple-search v-model="kw" show-action action-text="搜索" @search="onSearch" />

simple-radio-group / simple-radio 单选框

RadioGroup

Radio

事件：RadioGroup change；Radio change

<simple-radio-group v-model="gender" direction="row">
  <simple-radio label="1" text="男" />
  <simple-radio label="2" text="女" />
  <simple-radio label="3" text="保密" disabled />
</simple-radio-group>

label 是值，显示文字来自 text 或默认插槽 —— 与 uView 等库的习惯一致。

simple-checkbox-group / simple-checkbox 复选框

CheckboxGroup

Checkbox

事件：CheckboxGroup change、overflow（超出 max 时触发）；Checkbox change

<simple-checkbox-group v-model="hobbies" :max="3" @overflow="onOverflow">
  <simple-checkbox label="a" text="阅读" />
  <simple-checkbox label="b" text="运动" />
  <simple-checkbox label="c" text="音乐" />
</simple-checkbox-group>

simple-switch 开关

事件：update:modelValue、change

<simple-switch v-model="enabled" />
<simple-switch v-model="enabled" active-text="开" inactive-text="关" active-color="#19be6b" />

simple-slider 滑块

事件：update:modelValue、change、drag

<simple-slider v-model="progress" :min="0" :max="100" show-value />
<simple-slider v-model="priceRange" range :min="0" :max="1000" show-value />

触摸热区上下各留 24rpx，把细轨道的可点区域撑到 56rpx。 双滑块拖动时自动判断该拖哪一个，并保证 start <= end。

simple-rate 评分

事件：update:modelValue、change

<simple-rate v-model="score" />
<simple-rate v-model="score" allow-half show-text />
<simple-rate v-model="score" :max="10" size="56" color="#fa3534" />

半星通过把每颗星拆成左右两个触摸区实现，不依赖坐标计算（更可靠）。 再次点击同一分值会清零。

simple-upload 文件上传

事件：update:modelValue、change、success、fail、remove、preview 插槽：默认（替换添加按钮）、file（自定义文件项，作用域 { file, index }）

<simple-upload v-model="files" action="https://example.com/upload" :max-count="9" />
<!-- 只存本地路径，不上传 -->
<simple-upload v-model="files" :max-count="3" tip="上传凭证" />

simple-form 表单

Form

Form 事件：validate（全部通过）、validateFail（返回错误列表） Form 方法：validate()、validateField(prop)、clearValidate()、resetFields()

校验规则支持

<simple-form :model="form" :rules="rules" label-width="140">
  <simple-form-item label="用户名" prop="name">
    <simple-input v-model="form.name" placeholder="请输入用户名" />
  </simple-form-item>
  <simple-form-item label="手机号" prop="phone">
    <simple-input v-model="form.phone" />
  </simple-form-item>
</simple-form>

<script>
export default {
  data() {
    return {
      form: { name: '', phone: '' },
      rules: {
        name: [
          { required: true, message: '请输入用户名' },
          { min: 2, max: 10, message: '长度 2~10 个字符' }
        ],
        phone: [
          { required: true, message: '请输入手机号' },
          { pattern: '^1[3-9]\\d{9}$', message: '手机号格式不正确' }
        ]
      }
    }
  },
  methods: {
    async onSubmit() {
      const ok = await this.$refs.form.validate()
      if (!ok) return
      // 校验通过，提交
    }
  }
}
</script>

• 值变化时自动清除该字段的错误提示，用户改正后不会一直显示红字
• resetFields() 会恢复到字段注册时的初始值（数组 / 对象做了浅拷贝）
• 多字段校验并行执行，提升长表单的响应速度

simple-form-item 表单项

配合 simple-form 使用，负责单个字段的标签、内容与错误提示。

插槽：label（自定义标签）、默认（内容区，作用域 { value, error }）、error（自定义错误提示）

<simple-form-item label="用户名" prop="name">
  <simple-input v-model="form.name" placeholder="请输入用户名" />
</simple-form-item>

<!-- 自定义标签与错误提示 -->
<simple-form-item prop="phone">
  <template #label>
    <text class="my-label">手机号</text>
  </template>
  <simple-input v-model="form.phone" />
  <template #error="{ message }">
    <text class="my-error">! {{ message }}</text>
  </template>
</simple-form-item>

标签显示条件：有 label、有 label 插槽、或该字段规则里有 required。 想完全不显示标签栏，三个条件都不满足即可。

simple-select 选择器

功能完善的下拉选择器：单选 / 多选、底部弹层 / 顶部弹层 / 下拉面板、默认选中、文字对齐、选项插槽、确认前拦截、选项搜索。

属性

事件 / 插槽

生效时机

beforeChange 在两种模式下都会触发，可作为统一的拦截入口。

用法

<!-- 基础：底部弹层 -->
<simple-select v-model="city" :options="options" placeholder="请选择城市" />

<!-- 顶部弹层 -->
<simple-select v-model="city" :options="options" position="top" title="请选择" />

<!-- 下拉面板 -->
<simple-select v-model="cate" :options="options" mode="dropdown" />

<!-- 默认选中（非受控） -->
<simple-select :options="options" :default-value="'shanghai'" />

<!-- 多选 -->
<simple-select v-model="values" multiple clearable :options="options" />

<!-- 对齐方式 -->
<simple-select v-model="city" :options="options" align="right" />

<!-- 选项可搜索 -->
<simple-select v-model="city" searchable :options="options" @search="onSearch" />

<!-- 确认前拦截 -->
<simple-select v-model="city" :options="options" :before-change="beforeChange" />

<!-- 自定义选项插槽 -->
<simple-select v-model="city" :options="options">
    <template #option="{ item, index, selected }">
        <view class="my-option">
            <text>{{ index + 1 }}. {{ item.label }}</text>
            <text v-if="selected">已选</text>
        </view>
    </template>
</simple-select>

<!-- 自定义字段名 -->
<simple-select v-model="userId" :options="userList" label-key="name" value-key="id" />

选项数据结构

const options = [
    { label: '北京', value: 'beijing' },
    { label: '上海', value: 'shanghai' },
    { label: '广州（禁用）', value: 'guangzhou', disabled: true }
]

• label —— 展示文字（可用 labelKey 自定义字段名）
• value —— 选中值（可用 valueKey 自定义字段名），必须唯一，不要用对象
• disabled —— 可选，为 true 时该项不可点击

注意事项

1. value 必须唯一且为基本类型（字符串 / 数字），不要传对象，否则选中判断会失效
2. popup 模式基于 position: fixed 全屏定位，若父级使用了 transform 会导致定位异常
3. 选择器列表高度由 maxHeight 控制，超过后内部滚动
4. dropdown 模式的面板会撑开父级，建议给外层容器留出空间或设置 overflow: visible
5. 多选的值必须传数组，单选建议传基本类型；清空时单选输出 ''，多选输出 []
6. popup 模式下点击「取消」或遮罩不会回写值，暂存态会被丢弃
7. 组件目录名与文件名必须一致（simple-xxx/simple-xxx.vue），否则 easycom 无法识别

更新日志

见 changelog.md