更新记录

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

新增 预览图

1.2.5（2026-10-03） 下载此版本

• 文档形态简化：统一使用普通 readme.md，不再引入额外的在线文档页
  • 插件市场仅渲染纯 Markdown，嵌 HTML 不可靠（渲染器有 HTML 白名单过滤， 且无 JS 能力，无法实现导航跳转、滚动高亮、组件预览等交互），故保持纯文字文档
• readme.md 补齐「注意事项」小节，覆盖 v-model 取值规则、弹层定位限制、 多选数据类型、value 唯一性等易踩点

1.2.3（2026-10-03） 下载此版本

• 文档改造：readme.md 全面改为面向使用者的写法
  • 「安装」重写为两种用户视角的方式：插件市场导入 / 手动拷贝到 uni_modules
  • 移除所有面向维护者的内容（脚手架用法、目录结构、本地路径等）
  • 补充环境要求表、21 个主题变量表、Select 完整 API（20 属性 / 7 事件 / 1 插槽）与生效时机对照表
• 新增可视化文档页 docs/index.html
  • 左侧导航 + 右侧内容布局，与 Demo 首页保持一致
  • 每个组件均提供实时渲染的预览效果，并配套可折叠、可复制的示例代码块
  • 单文件、零依赖，双击即可在浏览器打开
  • 说明：插件市场仅渲染纯 Markdown，无法渲染 Vue 组件，因此可视化预览以独立 HTML 页承载
• 插件市场提交修复
  • keywords 精简至 5 个（插件市场标签上限为 5，超出会导致提交失败）

平台兼容性

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-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