常用组件速查表

本文件记录项目中常用的组件使用模式，方便快速查找和复制。

nut-button

基础用法

<!-- 主要按钮 -->
<nut-button type="primary">确定</nut-button>

<!-- 次要按钮（描边） -->
<nut-button plain type="primary">取消</nut-button>

<!-- 独占一行 -->
<nut-button type="primary" block>确定</nut-button>

<!-- 禁用状态 -->
<nut-button disabled>禁用</nut-button>

<!-- 加载中 -->
<nut-button loading>提交中...</nut-button>

自定义样式（项目常用）

<!-- 双按钮并排（取消 + 主要操作） -->
<div class="flex gap-3 w-full">
  <nut-button
    plain
    type="primary"
    class="flex-1 !h-[88rpx] !rounded-[16rpx] !text-[30rpx] !border-blue-600"
  >
    取消
  </nut-button>
  <nut-button
    type="primary"
    color="#2563EB"
    class="flex-1 !h-[88rpx] !rounded-[16rpx] !text-[30rpx]"
  >
    确定
  </nut-button>
</div>

<!-- 单按钮独占一行 -->
<nut-button
  type="primary"
  color="#2563EB"
  block
  class="!h-[88rpx] !rounded-[16rpx] !text-[30rpx]"
>
  确定
</nut-button>

<!-- 灰色关闭按钮 -->
<nut-button
  type="primary"
  color="#9CA3AF"
  block
  class="!h-[88rpx] !rounded-[16rpx] !text-[30rpx]"
>
  关闭
</nut-button>

nut-popup

基础用法

<template>
  <nut-popup
    :visible="visible"
    position="bottom"
    round
    @update:visible="handleVisibleChange"
  >
    <div>弹窗内容</div>
  </nut-popup>
</template>

<script setup>
import { ref } from 'vue'

const visible = ref(false)

const handleVisibleChange = (value) => {
  visible.value = value
}
</script>

项目常用配置

<nut-popup
  :visible="visible"
  position="bottom"
  round
  :style="{ height: '90%' }"
  :close-on-click-overlay="true"
  :safe-area-inset-bottom="true"
  @update:visible="handleVisibleChange"
>
  <div class="h-full flex flex-col bg-gray-50 overflow-hidden rounded-t-2xl">
    <!-- Header -->
    <div class="flex justify-between items-center px-5 py-4 bg-white border-b border-gray-100 flex-shrink-0">
      <span class="text-lg font-bold text-gray-900">标题</span>
      <div class="p-2 -mr-2" @click="handleClose">
        <IconFont name="close" size="16" color="#9CA3AF" />
      </div>
    </div>

    <!-- Scrollable Content -->
    <div class="flex-1 overflow-y-auto p-4">
      <div class="bg-white rounded-xl p-5 shadow-sm">
        内容
      </div>
    </div>

    <!-- Footer Buttons -->
    <div class="p-4 bg-white border-t border-gray-100 flex gap-3 flex-shrink-0 pb-safe">
      <nut-button
        plain
        type="primary"
        class="flex-1 !h-[88rpx] !rounded-[16rpx] !text-[30rpx]"
        @click="handleClose"
      >
        取消
      </nut-button>
      <nut-button
        type="primary"
        color="#2563EB"
        class="flex-1 !h-[88rpx] !rounded-[16rpx] !text-[30rpx]"
        @click="handleSubmit"
      >
        确定
      </nut-button>
    </div>
  </div>
</nut-popup>

nut-tabs

基础用法

<nut-tabs v-model="activeTab">
  <nut-tab-pane title="标签1">内容1</nut-tab-pane>
  <nut-tab-pane title="标签2">内容2</nut-tab-pane>
</nut-tabs>

自定义标题

<nut-tabs v-model="activeTab">
  <template #titles>
    <view class="filter-tabs-wrapper">
      <view
        v-for="item in tabsData"
        :key="item.id"
        :class="[
          'filter-tab-item',
          activeTab === item.id ? 'filter-tab-active' : 'filter-tab-inactive'
        ]"
        @tap="onTabClick(item.id)"
      >
        <text class="filter-tab-text">{{ item.name }}</text>
      </view>
    </view>
  </template>
</nut-tabs>

nut-input / nut-textarea

nut-input

<nut-input
  v-model="value"
  placeholder="请输入"
  :clearable="true"
  @input="handleInput"
/>

nut-textarea

<!-- NutUI textarea (部分样式可能不支持深度选择器) -->
<nut-textarea
  v-model="content"
  placeholder="请输入内容"
  :maxlength="200"
  @input="handleInput"
/>

<!-- 原生 textarea (完全控制样式) -->
<textarea
  v-model="content"
  class="custom-textarea"
  :maxlength="200"
  @input="handleInput"
/>

.custom-textarea {
  width: 100%;
  min-height: 200rpx;
  padding: 24rpx;
  border: 2rpx solid #E5E7EB;
  border-radius: 16rpx;
  font-size: 28rpx;
}

nut-picker

基础用法

<template>
  <nut-picker
    :visible="showPicker"
    :columns="columns"
    :default-value="value"
    @update:visible="showPicker = $event"
    @confirm="handleConfirm"
    @cancel="handleCancel"
  />
</template>

<script setup>
import { ref } from 'vue'

const showPicker = ref(false)
const value = ref(['选项1'])
const columns = ref([
  { text: '选项1', value: '1' },
  { text: '选项2', value: '2' },
])

const handleConfirm = ({ selectedOptions }) => {
  console.log('选中:', selectedOptions)
}
</script>

nut-toast / NutUI.showToast

轻提示

import Taro from '@tarojs/taro'

// 成功提示
Taro.showToast({
  title: '操作成功',
  icon: 'success',
  duration: 2000
})

// 失败提示
Taro.showToast({
  title: '操作失败',
  icon: 'error',
  duration: 2000
})

// 加载提示
Taro.showLoading({
  title: '加载中...',
  mask: true
})

// 关闭加载
Taro.hideLoading()

// 纯文本提示
Taro.showToast({
  title: '提示信息',
  icon: 'none'
})

nut-dialog

弹窗确认

import Taro from '@tarojs/taro'

Taro.showModal({
  title: '提示',
  content: '确定要删除吗？',
  success: (res) => {
    if (res.confirm) {
      console.log('用户点击确定')
    } else if (res.cancel) {
      console.log('用户点击取消')
    }
  }
})

图标组件

IconFont 组件

<template>
  <!-- 使用 IconFont 组件 -->
  <IconFont name="close" size="16" color="#9CA3AF" />
  <IconFont name="heart" size="20" color="#EF4444" />
  <IconFont name="heart-fill" size="20" color="#EF4444" />
</template>

<script setup>
import IconFont from '@/components/icons/IconFont.vue'
</script>

动态切换图标

⚠️ 重要: IconFont 动态切换时需要添加 :key 强制重新渲染

<template>
  <IconFont :name="iconName" :key="iconName" size="20" />
</template>

<script setup>
import { ref } from 'vue'
import IconFont from '@/components/icons/IconFont.vue'

const iconName = ref('heart')

const toggleIcon = () => {
  iconName.value = iconName.value === 'heart' ? 'heart-fill' : 'heart'
}
</script>

列表组件

nut-cell

<nut-cell
  title="单元格"
  sub-title="副标题"
  is-link
  @click="handleClick"
/>

nut-checkbox / nut-checkbox-group

<template>
  <nut-checkbox-group v-model="checkedList">
    <nut-checkbox label="选项1">选项1</nut-checkbox>
    <nut-checkbox label="选项2">选项2</nut-checkbox>
  </nut-checkbox-group>
</template>

<script setup>
import { ref } from 'vue'

const checkedList = ref(['选项1'])
</script>

表单组件

表单验证模式

<template>
  <nut-form>
    <nut-form-item label="姓名" required>
      <nut-input
        v-model="form.name"
        placeholder="请输入姓名"
        :clearable="true"
      />
    </nut-form-item>

    <nut-form-item label="手机号" required>
      <nut-input
        v-model="form.phone"
        placeholder="请输入手机号"
        type="tel"
        :clearable="true"
      />
    </nut-form-item>

    <nut-button type="primary" @click="handleSubmit">提交</nut-button>
  </nut-form>
</template>

<script setup>
import { reactive } from 'vue'

const form = reactive({
  name: '',
  phone: ''
})

const handleSubmit = () => {
  // 验证
  if (!form.name) {
    Taro.showToast({ title: '请输入姓名', icon: 'none' })
    return
  }

  if (!form.phone) {
    Taro.showToast({ title: '请输入手机号', icon: 'none' })
    return
  }

  // 提交逻辑
  console.log('表单数据:', form)
}
</script>

常用 TailwindCSS 类

布局

<!-- Flexbox 布局 -->
<div class="flex items-center justify-between">...</div>
<div class="flex gap-3">...</div>
<div class="flex flex-col">...</div>

<!-- Grid 布局 -->
<div class="grid grid-cols-2 gap-4">...</div>

尺寸

<!-- 宽度 -->
<div class="w-full">全宽</div>
<div class="w-1/2">一半宽</div>
<div class="flex-1">自适应</div>

<!-- 高度 -->
<div class="h-[88rpx]">固定高度</div>
<div class="min-h-[100rpx]">最小高度</div>

间距

<!-- Padding -->
<div class="p-4">四周内边距</div>
<div class="px-4 py-2">水平+垂直内边距</div>

<!-- Margin -->
<div class="mb-4">下边距</div>
<div class="mx-auto">水平居中</div>

<!-- Gap (flex/grid 子元素间距) -->
<div class="gap-3">子元素间距</div>

文字

<!-- 大小 -->
<div class="text-[30rpx]">30rpx</div>
<div class="text-lg">大号</div>
<div class="text-sm">小号</div>

<!-- 颜色 -->
<div class="text-gray-900">深灰</div>
<div class="text-blue-600">蓝色</div>
<div class="text-red-500">红色</div>

<!-- 对齐 -->
<div class="text-left">左对齐</div>
<div class="text-center">居中</div>
<div class="text-right">右对齐</div>

圆角和边框

<!-- 圆角 -->
<div class="rounded-[16rpx]">16rpx 圆角</div>

<!-- 边框 -->
<div class="border border-gray-200">边框</div>

样式覆盖技巧

深度选择器

<style lang="less" scoped>
// 修改 NutUI 组件内部样式
:deep(.nut-button) {
  border-radius: 16rpx !important;
}

:deep(.nut-tabs__titles) {
  display: none;
}
</style>

TailwindCSS + !important

<template>
  <!-- 使用 ! 覆盖 TailwindCSS 样式 -->
  <nut-button class="!h-[88rpx] !rounded-[16rpx] !text-[30rpx]">
    按钮
  </nut-button>
</template>

最后更新

• 更新时间: 2026-02-10
• 维护者: Claude Code
• Taro 版本: 4.1.11
• NutUI 版本: 4.3.14