更新记录

1.0.0（2026-05-12） 下载此版本

发布插件

平台兼容性

uni-app(3.7.10)

n-checkbox

一个基于 uni-app 的自定义多选框组件，支持多端运行。

特性

• 支持自定义尺寸、颜色、边框宽度等样式
• 支持 v-model 双向绑定
• 支持禁用状态
• 支持插槽自定义标签内容
• 纯 CSS 绘制图标，性能优异
• 支持数字、字符串、布尔值作为 value

安装

将组件放入你的 uni-app 项目的 uni_modules 目录中即可使用。

基本使用

<template>
  <view>
    <n-checkbox v-model="checkedList" value="1" label="选项1" />
    <n-checkbox v-model="checkedList" value="2" label="选项2" />
    <n-checkbox v-model="checkedList" value="3" label="选项3" />
    <view>已选中: {{ checkedList }}</view>
  </view>
</template>

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

const checkedList = ref([])
</script>

Props

Events

Slots

示例：

<n-checkbox v-model="list" value="custom">
  <template #label>
    <text style="color: red;">自定义标签</text>
  </template>
</n-checkbox>

自定义样式（CSS 变量）

你可以通过修改以下 CSS 变量来自定义组件样式：

全局自定义示例：

:root {
  --n-checkbox-size: 40rpx;
  --n-checkbox-color: #409eff;
  --n-checkbox-border-width: 3rpx;
}

局部自定义示例：

<view style="--n-checkbox-color: green; --n-checkbox-size: 40rpx;">
  <n-checkbox v-model="list" value="1" label="绿色大尺寸选项" />
</view>

完整示例

<template>
  <view class="demo">
    <view class="title">基础用法</view>
    <n-checkbox v-model="list1" value="apple" label="苹果" />
    <n-checkbox v-model="list1" value="banana" label="香蕉" />
    <n-checkbox v-model="list1" value="orange" label="橙子" />
    <view class="result">选中：{{ list1 }}</view>

    <view class="title">禁用状态</view>
    <n-checkbox v-model="list2" value="a" label="禁用未选中" disabled />
    <n-checkbox v-model="list2" value="b" label="禁用已选中" disabled />
    <view class="result">选中：{{ list2 }}</view>

    <view class="title">自定义样式</view>
    <view class="custom-group">
      <n-checkbox v-model="list3" value="1" label="自定义1" />
      <n-checkbox v-model="list3" value="2" label="自定义2" />
      <n-checkbox v-model="list3" value="3" label="自定义3" />
    </view>
    <view class="result">选中：{{ list3 }}</view>

    <view class="title">数字值</view>
    <n-checkbox v-model="list4" :value="1" label="数字1" />
    <n-checkbox v-model="list4" :value="2" label="数字2" />
    <n-checkbox v-model="list4" :value="3" label="数字3" />
    <view class="result">选中：{{ list4 }}</view>
  </view>
</template>

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

const list1 = ref([])
const list2 = ref(['b'])
const list3 = ref([])
const list4 = ref([])
</script>

<style scoped>
.demo {
  padding: 30rpx;
  gap: 30rpx;
  display: flex;
  flex-direction: column;
}
.title {
  font-size: 28rpx;
  font-weight: bold;
  margin-bottom: 20rpx;
}
.result {
  margin-top: 20rpx;
  color: #666;
}
.custom-group {
  --n-checkbox-color: #67c23a;
  --n-checkbox-size: 40rpx;
  gap: 20rpx;
  display: flex;
  flex-direction: column;
}
</style>

注意事项

1. modelValue 必须是数组类型，组件会根据 value 是否在数组中来判断选中状态
2. 组件会自动触发 update:modelValue 事件，确保 v-model 正常工作
3. 如果同时设置了 label 属性和 #label 插槽，插槽内容优先级更高