Sard Uniapp

Appearance

在新窗口打开⤴

Checkbox复选框

介绍 ​

在一组可选项中进行任意选择。

引入 ​

js
import Checkbox from 'sard-uniapp/components/checkbox/checkbox.vue'
import CheckboxGroup from 'sard-uniapp/components/checkbox-group/checkbox-group.vue'

代码演示 ​

基础使用 ​

使用 checked 属性控制是否选中。

vue
<template>
  <sar-checkbox v-model:checked="checked" @change="onChange">
    {{ checked ? '已选中' : '未选中' }}
  </sar-checkbox>
</template>

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

const checked = ref(false)

const onChange = (value: any) => {
  console.log('change', value)
}
</script>
vue
<template>
  <sar-checkbox v-model:checked="checked" @change="onChange">
    {{ checked ? '已选中' : '未选中' }}
  </sar-checkbox>
</template>

<script setup lang="js">
import { ref } from "vue";
const checked = ref(false);
const onChange = (value) => {
  console.log("change", value);
};
</script>

只读和禁用 ​

只读或禁用后不可点击。

vue
<template>
  <doc-title>只读</doc-title>
  <sar-checkbox readonly>复选框</sar-checkbox>
  <sar-checkbox readonly checked root-style="margin-top: 10rpx">
    复选框
  </sar-checkbox>

  <doc-title>禁用</doc-title>
  <sar-checkbox disabled>复选框</sar-checkbox>
  <sar-checkbox disabled checked root-style="margin-top: 10rpx">
    复选框
  </sar-checkbox>
</template>

图标大小 ​

使用 size 属性设置图标大小。

vue
<template>
  <sar-checkbox size="48rpx">复选框</sar-checkbox>
</template>

图标颜色 ​

使用 checked-color 属性设置选中时的图标颜色。

vue
<template>
  <sar-checkbox checked checked-color="var(--sar-red)">复选框</sar-checkbox>
</template>

图标类型 ​

设置 type 属性为 circle 可以使图标变为圆形。

vue
<template>
  <sar-checkbox checked type="circle">复选框</sar-checkbox>
</template>

自定义图标 ​

如果内置的图标不满足需求，可以使用 icon 插槽设置为任意的图标。 插槽接收checked属性表示当前的选中状态。

vue
<template>
  <sar-checkbox checked>
    <template #icon="{ checked }">
      <sar-icon family="demo-icons" :name="checked ? 'heart-fill' : 'heart'" />
    </template>
    复选框
  </sar-checkbox>
</template>

复选框组 ​

复选框组用于收集选中状态的复选框的值。

vue
<template>
  <sar-checkbox-group v-model="value" @change="onChange">
    <sar-checkbox value="option1">选项1</sar-checkbox>
    <sar-checkbox value="option2">选项2</sar-checkbox>
    <sar-checkbox value="option3">选项3</sar-checkbox>
  </sar-checkbox-group>
</template>

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

const value = ref(['option2'])

const onChange = (value: any) => {
  console.log('change', value)
}
</script>
vue
<template>
  <sar-checkbox-group v-model="value" @change="onChange">
    <sar-checkbox value="option1">选项1</sar-checkbox>
    <sar-checkbox value="option2">选项2</sar-checkbox>
    <sar-checkbox value="option3">选项3</sar-checkbox>
  </sar-checkbox-group>
</template>

<script setup lang="js">
import { ref } from "vue";
const value = ref(["option2"]);
const onChange = (value2) => {
  console.log("change", value2);
};
</script>

排列方向 ​

将 direction 属性设置为 horizontal 后，复选框组会变成水平排列。

vue
<template>
  <sar-checkbox-group v-model="value" direction="horizontal">
    <sar-checkbox value="option1">选项1</sar-checkbox>
    <sar-checkbox value="option2">选项2</sar-checkbox>
    <sar-checkbox value="option3">选项3</sar-checkbox>
  </sar-checkbox-group>
</template>

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

const value = ref(['option2'])
</script>
vue
<template>
  <sar-checkbox-group v-model="value" direction="horizontal">
    <sar-checkbox value="option1">选项1</sar-checkbox>
    <sar-checkbox value="option2">选项2</sar-checkbox>
    <sar-checkbox value="option3">选项3</sar-checkbox>
  </sar-checkbox-group>
</template>

<script setup lang="js">
import { ref } from "vue";
const value = ref(["option2"]);
</script>

自动渲染复选框 ​

使用 options 属性设置可选项。

vue
<template>
  <sar-checkbox-group v-model="value" :options="options"></sar-checkbox-group>
</template>

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

const value = ref(['option2'])

const options = Array(3)
  .fill(0)
  .map((_, i) => {
    return {
      value: `option${i + 1}`,
      label: `选项${i + 1}`,
    }
  })
</script>
vue
<template>
  <sar-checkbox-group v-model="value" :options="options"></sar-checkbox-group>
</template>

<script setup lang="js">
import { ref } from "vue";
const value = ref(["option2"]);
const options = Array(3).fill(0).map((_, i) => {
  return {
    value: `option${i + 1}`,
    label: `\u9009\u9879${i + 1}`
  };
});
</script>

自定义 UI ​

如果只想使用复选的逻辑，并想自定义 UI，可以使用复选框组的 custom 插槽。

这个插槽接收 toggle方法和 value 属性作为参数。toggle 用于切换指定选项的选中状态，value 用于判断选中状态。

vue
<template>
  <sar-checkbox-group v-model="value">
    <template #custom="{ toggle, value }">
      <view>
        <sar-tag
          v-for="option in options"
          :key="option.value"
          theme="primary"
          root-style="margin-right: 20rpx"
          :plain="!value.includes(option.value)"
          @click="toggle(option.value)"
        >
          {{ option.label }}
        </sar-tag>
      </view>
    </template>
  </sar-checkbox-group>
</template>

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

const value = ref(['option2'])

const options = [
  { value: 'option1', label: '选项1' },
  { value: 'option2', label: '选项2' },
  { value: 'option3', label: '选项3' },
]
</script>
vue
<template>
  <sar-checkbox-group v-model="value">
    <template #custom="{ toggle, value }">
      <view>
        <sar-tag
          v-for="option in options"
          :key="option.value"
          theme="primary"
          root-style="margin-right: 20rpx"
          :plain="!value.includes(option.value)"
          @click="toggle(option.value)"
        >
          {{ option.label }}
        </sar-tag>
      </view>
    </template>
  </sar-checkbox-group>
</template>

<script setup lang="js">
import { ref } from "vue";
const value = ref(["option2"]);
const options = [
  { value: "option1", label: "\u9009\u98791" },
  { value: "option2", label: "\u9009\u98792" },
  { value: "option3", label: "\u9009\u98793" }
];
</script>

结合 list 组件使用：

vue
<template>
  <sar-checkbox-group v-model="value" root-style="margin-top: 40rpx">
    <template #custom="{ toggle, value }">
      <sar-list card>
        <sar-list-item
          v-for="option in options"
          :key="option.value"
          :title="option.label"
          hover
          @click="toggle(option.value)"
        >
          <template #value>
            <sar-icon
              v-if="value.includes(option.value)"
              color="var(--sar-red)"
              size="32rpx"
              name="success"
            />
          </template>
        </sar-list-item>
      </sar-list>
    </template>
  </sar-checkbox-group>
</template>

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

const value = ref(['option2'])

const options = [
  { value: 'option1', label: '选项1' },
  { value: 'option2', label: '选项2' },
  { value: 'option3', label: '选项3' },
]
</script>
vue
<template>
  <sar-checkbox-group v-model="value" root-style="margin-top: 40rpx">
    <template #custom="{ toggle, value }">
      <sar-list card>
        <sar-list-item
          v-for="option in options"
          :key="option.value"
          :title="option.label"
          hover
          @click="toggle(option.value)"
        >
          <template #value>
            <sar-icon
              v-if="value.includes(option.value)"
              color="var(--sar-red)"
              size="32rpx"
              name="success"
            />
          </template>
        </sar-list-item>
      </sar-list>
    </template>
  </sar-checkbox-group>
</template>

<script setup lang="js">
import { ref } from "vue";
const value = ref(["option2"]);
const options = [
  { value: "option1", label: "\u9009\u98791" },
  { value: "option2", label: "\u9009\u98792" },
  { value: "option3", label: "\u9009\u98793" }
];
</script>

复选框组里面 checkbox 组件，会自动判断选中状态；可以给 checkbox 组件添加 readonly 属性以便将点击操作交给其他组件。

vue
<template>
  <sar-checkbox-group v-model="value" root-style="margin-top: 40rpx">
    <template #custom="{ toggle }">
      <sar-list card>
        <sar-list-item
          v-for="option in options"
          :key="option.value"
          :title="option.label"
          hover
          @click="toggle(option.value)"
        >
          <template #icon>
            <sar-checkbox readonly :value="option.value" />
          </template>
        </sar-list-item>
      </sar-list>
    </template>
  </sar-checkbox-group>
</template>

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

const value = ref(['option2'])

const options = [
  { value: 'option1', label: '选项1' },
  { value: 'option2', label: '选项2' },
  { value: 'option3', label: '选项3' },
]
</script>
vue
<template>
  <sar-checkbox-group v-model="value" root-style="margin-top: 40rpx">
    <template #custom="{ toggle }">
      <sar-list card>
        <sar-list-item
          v-for="option in options"
          :key="option.value"
          :title="option.label"
          hover
          @click="toggle(option.value)"
        >
          <template #icon>
            <sar-checkbox readonly :value="option.value" />
          </template>
        </sar-list-item>
      </sar-list>
    </template>
  </sar-checkbox-group>
</template>

<script setup lang="js">
import { ref } from "vue";
const value = ref(["option2"]);
const options = [
  { value: "option1", label: "\u9009\u98791" },
  { value: "option2", label: "\u9009\u98792" },
  { value: "option3", label: "\u9009\u98793" }
];
</script>

不确定状态 ​

vue
<template>
  <sar-checkbox
    v-model:checked="allChecked"
    :indeterminate="isIndeterminate"
    root-style="margin-bottom: 40rpx"
    @change="onAllChange"
  >
    全选
  </sar-checkbox>

  <sar-checkbox-group v-model="checkedResult">
    <sar-checkbox
      v-for="option in options"
      :key="option.value"
      :value="option.value"
    >
      {{ option.label }}
    </sar-checkbox>
  </sar-checkbox-group>
</template>

<script setup lang="ts">
import { useIndeterminate } from 'sard-uniapp'
import { ref } from 'vue'

const checkedResult = ref(['option2'])

const options = [
  { value: 'option1', label: '选项1' },
  { value: 'option2', label: '选项2' },
  { value: 'option3', label: '选项3' },
]

const { allChecked, isIndeterminate, onAllChange } = useIndeterminate(
  checkedResult,
  options,
)
</script>
vue
<template>
  <sar-checkbox
    v-model:checked="allChecked"
    :indeterminate="isIndeterminate"
    root-style="margin-bottom: 40rpx"
    @change="onAllChange"
  >
    全选
  </sar-checkbox>

  <sar-checkbox-group v-model="checkedResult">
    <sar-checkbox
      v-for="option in options"
      :key="option.value"
      :value="option.value"
    >
      {{ option.label }}
    </sar-checkbox>
  </sar-checkbox-group>
</template>

<script setup lang="js">
import { useIndeterminate } from "sard-uniapp";
import { ref } from "vue";
const checkedResult = ref(["option2"]);
const options = [
  { value: "option1", label: "\u9009\u98791" },
  { value: "option2", label: "\u9009\u98792" },
  { value: "option3", label: "\u9009\u98793" }
];
const { allChecked, isIndeterminate, onAllChange } = useIndeterminate(
  checkedResult,
  options
);
</script>

API ​

CheckboxProps ​

属性描述类型默认值
root-class组件根元素类名string-
root-style组件根元素样式StyleValue-
checked (v-model)是否选中booleanfalse
indeterminate 1.6+是否处于不确定状态booleanfalse
value复选框的值，配合复选框组一起使用any-
label复选框标签string-
disabled禁用状态boolean-
readonly只读状态boolean-
size图标的尺寸string-
type图标类型'square' | 'circle''square'
checked-color选中时图标的颜色string-
validate-event是否触发表单验证booleantrue

CheckboxSlots ​

插槽描述属性
default自定义默认内容-
icon自定义图标{ checked: boolean }

CheckboxEmits ​

事件描述类型
click点击时触发(event: any) => void
update:checked选中状态改变时触发(checked: boolean) => void
change选中状态改变时触发(checked: boolean) => void

CheckboxGroupProps ​

属性描述类型默认值
root-class组件根元素类名string-
root-style组件根元素样式StyleValue-
model-value (v-model)指定选中的选项any[]-
disabled禁用状态boolean-
readonly只读状态boolean-
size图标的尺寸string-
type图标类型'square' | 'circle''square'
checked-color选中时图标的颜色string-
validate-event是否触发表单验证booleantrue
options自动设置复选框CheckboxGroupOption[]-
option-keys自定义 options 的 label、value 的字段OptionKeys{label: 'label', value: 'value'}

CheckboxGroupOption ​

ts
export type CheckboxGroupOption =
  | {
      [key: PropertyKey]: any
    }
  | string
  | number
  | boolean

OptionKeys ​

ts
export interface OptionKeys {
  label?: string
  value?: string
}

CheckboxGroupSlots ​

插槽描述属性
default自定义默认内容-
custom同默认插槽，额外可以接收 toggle 方法切换选中状态，用于自定义复选框结构和样式{ toggle: (value: any) => void, value: any[] }

CheckboxGroupEmits ​

事件描述类型
update:model-value复选框组值改变时触发(value: any[]) => void
change复选框组值改变时触发(value: any[]) => void

主题定制 ​

CSS 变量 ​

scss
page,
.sar-portal {
  --sar-checkbox-group-column-gap: 24rpx;
  --sar-checkbox-group-row-gap: 16rpx;

  --sar-checkbox-icon-font-size: 40rpx;
  --sar-checkbox-icon-color: var(--sar-fourth-color);
  --sar-checkbox-icon-checked-color: var(--sar-primary);
  --sar-checkbox-icon-disabled-color: var(--sar-disabled-color);
  --sar-checkbox-icon-transition-duration: var(--sar-duration);

  --sar-checkbox-label-margin-left: 16rpx;
}

Released under the MIT License.

Copyright © 2023-present wuzhitao