前端通用基础组件设计：按钮/输入框/弹窗，统一设计标准｜组件化设计基础篇

【Vue3 基础组件设计】+【中后台组件化场景】：从统一 API/状态边界/交互规范到按钮、输入框、弹窗落地实操，彻底搞懂可维护通用组件的最佳写法，避开状态失控、行为不一致、重复造轮子的高频坑！

📑 文章目录

一、先统一认知：基础组件不是"会写就行"，而是"团队标准"
[二、设计前先定规则：通用组件的 6 条"地基原则"](#二、设计前先定规则：通用组件的 6 条“地基原则”)
- [1）API 要"少而清晰"](#1）API 要“少而清晰”)
- 2）样式和行为分离
- 3）可控与不可控状态要明确
- 4）默认值要"安全"
- 5）无障碍（a11y）不要忽略
- [6）先满足 80% 高频场景](#6）先满足 80% 高频场景)
三、目录结构建议（Vue3）
四、实战一：BaseButton（按钮）
五、实战二：BaseInput（输入框）
六、实战三：BaseModal（弹窗）
七、统一设计标准（建议你直接贴进团队规范）
八、升级建议：从"会写"到"写得稳"
九、你可以直接复用的"落地步骤"
十、结语
[🔍 系列模块导航](#🔍 系列模块导航)
- [📝 组件化设计基础](#📝 组件化设计基础)
- [📚 系列总览](#📚 系列总览)

同学们好，我是 Eugene（尤金），一名多年中后台前端开发工程师。

（Eugene 发音 /juːˈdʒiːn/，大家怎么顺口怎么叫就好）

当你能写出规范、可维护的代码后，下一个真正的瓶颈，就是架构。

面对大型项目、复杂业务，你是否也会遇到：组件越写越乱、重复开发越来越多；需求一变全链路改动；不知道怎么分层、怎么抽象、怎么设计才能支撑长期迭代；想晋升、想带项目，却缺少架构思维。

这一系列《前端组件化与架构实战》，我会继续用大白话 + 真实业务场景 ，不讲玄学、不啃晦涩源码，只教你能落地、能抗复杂项目的架构思路。

帮你从「写页面的开发者」，真正升级为「能做架构、能带项目、能搞定复杂需求的前端工程师」。

一、先统一认知：基础组件不是"会写就行"，而是"团队标准"

很多项目后期难维护，不是业务复杂，而是基础组件没有标准，导致：

每个页面按钮样式都不一样
输入框校验行为不一致（有的 blur 验证、有的 input 验证）
弹窗关闭逻辑混乱（点遮罩能不能关、ESC 能不能关、是否锁滚动）

基础组件的核心价值：

统一交互和视觉（用户体验稳定）
降低重复代码（开发效率）
降低沟通成本（团队协作）
降低改版成本（集中升级）

二、设计前先定规则：通用组件的 6 条"地基原则"

这 6 条建议你直接当 checklist：

1）API 要"少而清晰"

能用 type/size/disabled/loading 解决的，不要加一堆奇怪参数。
参数命名语义化，避免 flag1、mode2 这种黑盒写法。

2）样式和行为分离

样式通过 class/variant 控制
行为通过 props + emits 控制
不要把业务逻辑写死在基础组件里

3）可控与不可控状态要明确

输入框、弹窗优先支持 v-model（可控）
内部临时状态可有，但最终状态应可被父组件管理

4）默认值要"安全"

比如弹窗默认 closeOnOverlay = true 还是 false，要结合业务安全性
按钮默认 type="button"，避免表单里误触发提交

Button 原生 button 标签
Modal 提供 role="dialog"、aria-modal="true" 等基础能力
键盘行为（Enter/ESC/Tab）尽量有基本支持

6）先满足 80% 高频场景

不要一上来就做超级大而全组件
先把核心功能做稳，再逐步扩展

三、目录结构建议（Vue3）

复制代码

src/
  components/
    base/
      BaseButton.vue
      BaseInput.vue
      BaseModal.vue
  styles/
    tokens.css

说明：

base 目录放基础组件，和业务组件分层
tokens.css 放设计令牌（颜色、间距、圆角、字号等），统一视觉来源

四、实战一：BaseButton（按钮）

我们先做一个可直接复用的按钮组件，支持：type/size/disabled/loading/block。

1）组件代码（完整示例）

html 复制代码

<!-- src/components/base/BaseButton.vue -->
<template>
  <button
    class="base-button"
    :class="[
      `base-button--${type}`,
      `base-button--${size}`,
      { 'is-loading': loading, 'is-block': block }
    ]"
    :disabled="disabled || loading"
    :type="nativeType"
    @click="handleClick"
  >
    <span v-if="loading" class="base-button__spinner"></span>
    <span class="base-button__content">
      <slot />
    </span>
  </button>
</template>

<script setup lang="ts">
interface Props {
  type?: 'primary' | 'default' | 'danger' | 'text'
  size?: 'small' | 'medium' | 'large'
  disabled?: boolean
  loading?: boolean
  block?: boolean
  nativeType?: 'button' | 'submit' | 'reset'
}

const props = withDefaults(defineProps<Props>(), {
  type: 'default',
  size: 'medium',
  disabled: false,
  loading: false,
  block: false,
  nativeType: 'button'
})

const emit = defineEmits<{
  (e: 'click', event: MouseEvent): void
}>()

function handleClick(event: MouseEvent) {
  if (props.disabled || props.loading) return
  emit('click', event)
}
</script>

<style scoped>
.base-button {
  --btn-height-small: 28px;
  --btn-height-medium: 36px;
  --btn-height-large: 44px;
  --btn-radius: 6px;

  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: 8px;
  border: 1px solid transparent;
  border-radius: var(--btn-radius);
  padding: 0 14px;
  cursor: pointer;
  transition: all 0.2s ease;
  user-select: none;
}

.base-button:disabled {
  cursor: not-allowed;
  opacity: 0.6;
}

.base-button.is-block {
  width: 100%;
}

.base-button--small { height: var(--btn-height-small); font-size: 12px; }
.base-button--medium { height: var(--btn-height-medium); font-size: 14px; }
.base-button--large { height: var(--btn-height-large); font-size: 16px; }

.base-button--default {
  background: #fff;
  border-color: #dcdfe6;
  color: #303133;
}
.base-button--default:hover:not(:disabled) {
  border-color: #409eff;
  color: #409eff;
}

.base-button--primary {
  background: #409eff;
  color: #fff;
}
.base-button--primary:hover:not(:disabled) {
  background: #66b1ff;
}

.base-button--danger {
  background: #f56c6c;
  color: #fff;
}
.base-button--danger:hover:not(:disabled) {
  background: #f78989;
}

.base-button--text {
  background: transparent;
  color: #409eff;
  padding: 0;
}

.base-button__spinner {
  width: 14px;
  height: 14px;
  border: 2px solid rgba(255, 255, 255, 0.5);
  border-top-color: #fff;
  border-radius: 50%;
  animation: spin 0.8s linear infinite;
}

.base-button--default .base-button__spinner,
.base-button--text .base-button__spinner {
  border: 2px solid rgba(64, 158, 255, 0.3);
  border-top-color: #409eff;
}

@keyframes spin {
  to { transform: rotate(360deg); }
}
</style>

2）使用示例

html 复制代码

<BaseButton type="primary" @click="submitForm">提交</BaseButton>
<BaseButton type="danger">删除</BaseButton>
<BaseButton loading>加载中</BaseButton>
<BaseButton block size="large">整行按钮</BaseButton>

3）常见坑

忘了 nativeType="button"，在 form 中默认触发 submit
loading 状态还允许点击，造成重复请求
把业务确认逻辑写在按钮内部（应放父组件）

五、实战二：BaseInput（输入框）

输入框是"最容易写乱"的组件之一。先实现常用能力：v-model、clearable、maxlength、disabled、error 提示。

1）组件代码（完整示例）

html 复制代码

<!-- src/components/base/BaseInput.vue -->
<template>
  <div class="base-input-wrap">
    <label v-if="label" class="base-input__label">{{ label }}</label>

    <div class="base-input" :class="{ 'is-error': !!error, 'is-disabled': disabled }">
      <input
        class="base-input__inner"
        :value="modelValue"
        :placeholder="placeholder"
        :maxlength="maxlength"
        :disabled="disabled"
        @input="onInput"
        @blur="onBlur"
        @focus="onFocus"
      />
      <button
        v-if="clearable && modelValue && !disabled"
        class="base-input__clear"
        type="button"
        @click="clear"
      >
        ×
      </button>
    </div>

    <div class="base-input__meta">
      <span class="base-input__error" v-if="error">{{ error }}</span>
      <span class="base-input__count" v-if="showCount && maxlength">
        {{ modelValue.length }}/{{ maxlength }}
      </span>
    </div>
  </div>
</template>

<script setup lang="ts">
interface Props {
  modelValue: string
  label?: string
  placeholder?: string
  maxlength?: number
  disabled?: boolean
  clearable?: boolean
  error?: string
  showCount?: boolean
}

const props = withDefaults(defineProps<Props>(), {
  modelValue: '',
  label: '',
  placeholder: '请输入',
  maxlength: undefined,
  disabled: false,
  clearable: false,
  error: '',
  showCount: false
})

const emit = defineEmits<{
  (e: 'update:modelValue', value: string): void
  (e: 'blur', event: FocusEvent): void
  (e: 'focus', event: FocusEvent): void
  (e: 'clear'): void
}>()

function onInput(event: Event) {
  const target = event.target as HTMLInputElement
  emit('update:modelValue', target.value)
}

function onBlur(event: FocusEvent) {
  emit('blur', event)
}

function onFocus(event: FocusEvent) {
  emit('focus', event)
}

function clear() {
  emit('update:modelValue', '')
  emit('clear')
}
</script>

<style scoped>
.base-input-wrap {
  display: flex;
  flex-direction: column;
  gap: 6px;
}

.base-input__label {
  font-size: 14px;
  color: #606266;
}

.base-input {
  position: relative;
  display: flex;
  align-items: center;
  border: 1px solid #dcdfe6;
  border-radius: 6px;
  padding: 0 10px;
  transition: border-color 0.2s ease;
  background: #fff;
}

.base-input:focus-within {
  border-color: #409eff;
}

.base-input.is-error {
  border-color: #f56c6c;
}

.base-input.is-disabled {
  background: #f5f7fa;
  cursor: not-allowed;
}

.base-input__inner {
  width: 100%;
  height: 36px;
  border: none;
  outline: none;
  font-size: 14px;
  background: transparent;
  color: #303133;
}

.base-input__inner:disabled {
  cursor: not-allowed;
}

.base-input__clear {
  border: none;
  background: transparent;
  cursor: pointer;
  color: #909399;
  font-size: 16px;
  line-height: 1;
}

.base-input__meta {
  min-height: 20px;
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.base-input__error {
  color: #f56c6c;
  font-size: 12px;
}

.base-input__count {
  color: #909399;
  font-size: 12px;
}
</style>

2）父组件接入（包含校验思路）

html 复制代码

<script setup lang="ts">
import { ref } from 'vue'

const username = ref('')
const error = ref('')

function validate() {
  if (!username.value.trim()) {
    error.value = '用户名不能为空'
    return false
  }
  if (username.value.length < 3) {
    error.value = '至少输入 3 个字符'
    return false
  }
  error.value = ''
  return true
}
</script>

<template>
  <BaseInput
    v-model="username"
    label="用户名"
    placeholder="请输入用户名"
    :maxlength="20"
    show-count
    clearable
    :error="error"
    @blur="validate"
  />
</template>

3）常见坑

把校验规则硬编码在 BaseInput 内部（基础组件不应绑定具体业务）
v-model 事件名写错（必须是 update:modelValue）
只处理 UI，不抛出 blur/focus/clear 等事件，导致父层无法接管行为

六、实战三：BaseModal（弹窗）

弹窗最常见问题：开关状态混乱、滚动穿透、关闭逻辑不统一 。

这里给一份够用且清晰的基础版。

1）组件代码（完整示例）

html 复制代码

<!-- src/components/base/BaseModal.vue -->
<template>
  <Teleport to="body">
    <div v-if="modelValue" class="base-modal">
      <div class="base-modal__overlay" @click="onOverlayClick"></div>

      <div
        class="base-modal__panel"
        role="dialog"
        aria-modal="true"
        :aria-label="title || '弹窗'"
      >
        <header class="base-modal__header">
          <h3 class="base-modal__title">{{ title }}</h3>
          <button class="base-modal__close" type="button" @click="close">×</button>
        </header>

        <section class="base-modal__body">
          <slot />
        </section>

        <footer class="base-modal__footer">
          <slot name="footer">
            <BaseButton @click="close">取消</BaseButton>
            <BaseButton type="primary" @click="confirm">确定</BaseButton>
          </slot>
        </footer>
      </div>
    </div>
  </Teleport>
</template>

<script setup lang="ts">
import { watch, onBeforeUnmount } from 'vue'
import BaseButton from './BaseButton.vue'

interface Props {
  modelValue: boolean
  title?: string
  closeOnOverlay?: boolean
  closeOnEsc?: boolean
  lockScroll?: boolean
}

const props = withDefaults(defineProps<Props>(), {
  modelValue: false,
  title: '',
  closeOnOverlay: true,
  closeOnEsc: true,
  lockScroll: true
})

const emit = defineEmits<{
  (e: 'update:modelValue', value: boolean): void
  (e: 'confirm'): void
  (e: 'close'): void
}>()

function close() {
  emit('update:modelValue', false)
  emit('close')
}

function confirm() {
  emit('confirm')
}

function onOverlayClick() {
  if (!props.closeOnOverlay) return
  close()
}

function onEsc(event: KeyboardEvent) {
  if (!props.closeOnEsc) return
  if (event.key === 'Escape' && props.modelValue) {
    close()
  }
}

function updateBodyScrollLock(visible: boolean) {
  if (!props.lockScroll) return
  document.body.style.overflow = visible ? 'hidden' : ''
}

watch(
  () => props.modelValue,
  (visible) => {
    updateBodyScrollLock(visible)
  },
  { immediate: true }
)

window.addEventListener('keydown', onEsc)

onBeforeUnmount(() => {
  window.removeEventListener('keydown', onEsc)
  updateBodyScrollLock(false)
})
</script>

<style scoped>
.base-modal {
  position: fixed;
  inset: 0;
  z-index: 999;
}

.base-modal__overlay {
  position: absolute;
  inset: 0;
  background: rgba(0, 0, 0, 0.45);
}

.base-modal__panel {
  position: relative;
  width: 520px;
  max-width: calc(100vw - 32px);
  margin: 12vh auto 0;
  background: #fff;
  border-radius: 10px;
  overflow: hidden;
  z-index: 1;
}

.base-modal__header,
.base-modal__footer {
  padding: 14px 16px;
  border-bottom: 1px solid #ebeef5;
}

.base-modal__footer {
  border-bottom: none;
  border-top: 1px solid #ebeef5;
  display: flex;
  justify-content: flex-end;
  gap: 10px;
}

.base-modal__title {
  margin: 0;
  font-size: 16px;
  color: #303133;
}

.base-modal__close {
  position: absolute;
  top: 12px;
  right: 12px;
  border: none;
  background: transparent;
  font-size: 20px;
  color: #909399;
  cursor: pointer;
}

.base-modal__body {
  padding: 16px;
  color: #606266;
}
</style>

2）使用示例（完整）

html 复制代码

<script setup lang="ts">
import { ref } from 'vue'

const visible = ref(false)

function openModal() {
  visible.value = true
}

function handleConfirm() {
  // 这里处理提交逻辑
  visible.value = false
}
</script>

<template>
  <BaseButton type="primary" @click="openModal">打开弹窗</BaseButton>

  <BaseModal
    v-model="visible"
    title="删除确认"
    :close-on-overlay="false"
    @confirm="handleConfirm"
  >
    确定删除这条数据吗？该操作不可恢复。
  </BaseModal>
</template>

3）常见坑

弹窗关闭后忘记恢复 body 滚动
组件卸载时不清理 keydown 监听（内存泄漏）
遮罩点击关闭和"危险操作确认"场景冲突（应允许配置）

七、统一设计标准（建议你直接贴进团队规范）

下面这份可以当"基础组件规范 1.0"：

命名标准 ：基础组件统一 BaseXxx，如 BaseButton
Props 标准：默认值必须写清，类型必须可读
事件标准 ：可变状态统一支持 v-model，输出事件命名语义化（confirm/close/clear）
样式标准 ：类名统一 BEM 风格或约定前缀（如 base-button__...）
交互标准：禁用态不可触发事件；loading 态要阻止重复操作
可访问性标准：优先原生语义标签，补充必要 aria 属性
扩展标准：保留 slot（如 Modal footer），避免未来全重构

八、升级建议：从"会写"到"写得稳"

如果你已经有几年经验，最容易忽略的是"习惯债"：

不再追求一个页面快，而是追求全项目一致性
每个基础组件都要有边界意识（只做通用，不掺业务）
先做最小可用标准，再逐步演进
把踩坑写进规范，你未来会感谢现在的自己
边做边输出博客/文档，这是最好的"反刍学习"

九、你可以直接复用的"落地步骤"

第一步：先把 BaseButton/BaseInput/BaseModal 接入一个真实页面
第二步：记录本项目里的 5 个高频坑，补成 props 或文档说明
第三步：沉淀组件使用示例页（哪怕先是 markdown）
第四步：约定"新页面优先用基础组件，不允许重复造轮子"
第五步：每两周小迭代一次 API，不追求一步到位

十、结语

基础组件设计的本质不是"炫技"，而是让团队写代码更稳、更统一、更可维护 。

按钮、输入框、弹窗看起来简单，但它们正是项目"工程质量"的地基。

如果你正在补基础，这条路线非常适合：
一个组件 = 一次标准化训练 + 一次工程思维升级 + 一篇可沉淀的技术文章。

当你把这三件事持续做下去，你会明显感觉到：

你写代码的速度不一定慢下来，但质量和可控性会稳步上升。

🔍 系列模块导航

📝 组件化设计基础

持续更新中，敬请期待～

👉 跟着系列慢慢学，把技术功底扎扎实实地打牢～

📚 系列总览

前端体系化学习完全体：基础 → 规范 → 架构 → 大厂面试

四套系列、百余篇高质量实战文，从入门到进阶，一站式补齐前端核心能力

前端基础实战系列 ：《前端基础实战：JS/TS与Vue体系化扫盲（47 篇完整目录 + 避坑）》
前端规范实战系列 ：《JS/TS/Vue 前端规范实战：从写对到写优，搞定中后台规范落地，打造可维护代码（40 篇全目录）》
前端架构实战系列：聚焦工程化、性能优化、可维护架构、中后台体系设计（持续更新中）
前端大厂面试系列：覆盖高频考点、手写题、项目深挖、简历与面试技巧（规划中）

每个系列完结后，都会整理成一篇完整导航文并附上直达链接，方便大家按顺序、体系化学习。

全套内容持续更新中，敬请期待～

前端的成长路径很清晰：

会写代码 → 写规范代码 → 做可扩展架构。

每一步，都是职业晋升的关键台阶。

后续我会持续输出组件化、配置驱动、权限架构、工程化、复杂业务实战干货，帮你真正建立架构思维，在工作与面试中更有竞争力。

觉得有用欢迎 点赞 + 收藏 + 关注，不错过每一篇硬核内容。

我是 Eugene，与你一起从业务走向架构，搞定复杂项目，我们下篇干货见～

前端通用基础组件设计：按钮/输入框/弹窗，统一设计标准｜组件化设计基础篇

📑 文章目录

一、先统一认知：基础组件不是"会写就行"，而是"团队标准"

二、设计前先定规则：通用组件的 6 条"地基原则"

1）API 要"少而清晰"

2）样式和行为分离

3）可控与不可控状态要明确

4）默认值要"安全"

5）无障碍（a11y）不要忽略

6）先满足 80% 高频场景

三、目录结构建议（Vue3）

四、实战一：BaseButton（按钮）

1）组件代码（完整示例）

2）使用示例

3）常见坑

五、实战二：BaseInput（输入框）

1）组件代码（完整示例）

2）父组件接入（包含校验思路）

3）常见坑

六、实战三：BaseModal（弹窗）

1）组件代码（完整示例）

2）使用示例（完整）

3）常见坑

七、统一设计标准（建议你直接贴进团队规范）

八、升级建议：从"会写"到"写得稳"

九、你可以直接复用的"落地步骤"

十、结语

🔍 系列模块导航

📝 组件化设计基础

📚 系列总览