persagy-vant 0.0.28 → 0.0.29

package/lib/checkbox/README.zh-CN.md

@@ -0,0 +1,417 @@
+# 复选框 Checkbox
+
+### 介绍
+
+在一组备选项中进行多选。
+
+### 引入
+
+通过以下方式来全局注册组件，更多注册方式请参考[组件注册](#/zh-CN/advanced-usage#zu-jian-zhu-ce)。
+
+```js
+import { createApp } from 'vue';
+import { Checkbox, CheckboxGroup } from 'vant';
+
+const app = createApp();
+app.use(Checkbox);
+app.use(CheckboxGroup);
+```
+
+## 代码演示
+
+### 基础用法
+
+通过 `v-model` 绑定复选框的勾选状态。
+
+```html
+<van-checkbox v-model="checked">复选框</van-checkbox>
+```
+
+```js
+import { ref } from 'vue';
+
+export default {
+  setup() {
+    const checked = ref(true);
+    return { checked };
+  },
+};
+```
+
+### 禁用状态
+
+通过设置 `disabled` 属性可以禁用复选框。
+
+```html
+<van-checkbox v-model="checked" disabled>复选框</van-checkbox>
+```
+
+### 自定义形状
+
+将 `shape` 属性设置为 `square`，复选框的形状会变成方形。
+
+```html
+<van-checkbox v-model="checked" shape="square">复选框</van-checkbox>
+```
+
+### 自定义颜色
+
+通过 `checked-color` 属性设置选中状态的图标颜色。
+
+```html
+<van-checkbox v-model="checked" checked-color="#ee0a24">复选框</van-checkbox>
+```
+
+### 尺寸
+
+通过 `size` 属性设置复选框尺寸，可选值为 `normal` 和 `large`（默认）。
+
+```html
+<van-checkbox v-model="checked" size="normal">普通复选框</van-checkbox>
+<van-checkbox v-model="checked" size="large">大号复选框</van-checkbox>
+```
+
+### 自定义大小
+
+通过 `icon-size` 和 `label-font-size` 属性可以分别自定义图标与文本的大小。
+
+```html
+<van-checkbox v-model="checked" icon-size="24px" label-font-size="16px">复选框</van-checkbox>
+```
+
+### 自定义图标
+
+通过 `icon` 插槽自定义图标，可以通过 `slotProps` 判断是否为选中状态.
+
+```html
+<van-checkbox v-model="checked">
+  自定义图标
+  <template #icon="props">
+    <img class="img-icon" :src="props.checked ? activeIcon : inactiveIcon" />
+  </template>
+</van-checkbox>
+
+<style>
+  .img-icon {
+    height: 20px;
+  }
+</style>
+```
+
+```js
+import { ref } from 'vue';
+
+export default {
+  setup() {
+    const checked = ref(true);
+    return {
+      checked,
+      activeIcon:
+        'https://fastly.jsdelivr.net/npm/@vant/assets/user-active.png',
+      inactiveIcon:
+        'https://fastly.jsdelivr.net/npm/@vant/assets/user-inactive.png',
+    };
+  },
+};
+```
+
+### 禁用文本点击
+
+设置 `label-disabled` 属性后，点击图标以外的内容不会触发复选框切换。
+
+```html
+<van-checkbox v-model="checked" label-disabled>复选框</van-checkbox>
+```
+
+### 复选框组
+
+复选框可以与复选框组一起使用，复选框组通过 `v-model` 数组绑定复选框的勾选状态。
+
+```html
+<van-checkbox-group v-model="checked">
+  <van-checkbox name="a">复选框 a</van-checkbox>
+  <van-checkbox name="b">复选框 b</van-checkbox>
+</van-checkbox-group>
+```
+
+```js
+import { ref } from 'vue';
+
+export default {
+  setup() {
+    const checked = ref(['a', 'b']);
+    return { checked };
+  },
+};
+```
+
+### 水平排列
+
+将 `direction` 属性设置为 `horizontal` 后，复选框组会变成水平排列。
+
+```html
+<van-checkbox-group v-model="checked" direction="horizontal">
+  <van-checkbox name="a">复选框 a</van-checkbox>
+  <van-checkbox name="b">复选框 b</van-checkbox>
+</van-checkbox-group>
+```
+
+```js
+import { ref } from 'vue';
+
+export default {
+  setup() {
+    const checked = ref([]);
+    return { checked };
+  },
+};
+```
+
+### 限制最大可选数
+
+通过 `max` 属性可以限制复选框组的最大可选数。
+
+```html
+<van-checkbox-group v-model="checked" :max="2">
+  <van-checkbox name="a">复选框 a</van-checkbox>
+  <van-checkbox name="b">复选框 b</van-checkbox>
+  <van-checkbox name="c">复选框 c</van-checkbox>
+</van-checkbox-group>
+```
+
+### 全选与反选
+
+通过 `CheckboxGroup` 实例上的 `toggleAll` 方法可以实现全选与反选。
+
+```html
+<van-checkbox-group v-model="checked" ref="checkboxGroup">
+  <van-checkbox name="a">复选框 a</van-checkbox>
+  <van-checkbox name="b">复选框 b</van-checkbox>
+  <van-checkbox name="c">复选框 c</van-checkbox>
+</van-checkbox-group>
+
+<van-button type="primary" @click="checkAll">全选</van-button>
+<van-button type="primary" @click="toggleAll">反选</van-button>
+```
+
+```js
+import { ref } from 'vue';
+
+export default {
+  setup() {
+    const checked = ref([]);
+    const checkboxGroup = ref(null);
+    const checkAll = () => {
+      checkboxGroup.value.toggleAll(true);
+    }
+    const toggleAll = () => {
+      checkboxGroup.value.toggleAll();
+    },
+
+    return {
+      checked,
+      checkAll,
+      toggleAll,
+      checkboxGroup,
+    };
+  },
+};
+```
+
+### 搭配单元格组件使用
+
+搭配单元格组件使用时，需要再引入 `Cell` 和 `CellGroup` 组件，并通过 `Checkbox` 实例上的 toggle 方法触发切换。
+
+```html
+<van-checkbox-group v-model="checked">
+  <van-cell-group inset>
+    <van-cell
+      v-for="(item, index) in list"
+      clickable
+      :key="item"
+      :title="`复选框 ${item}`"
+      @click="toggle(index)"
+    >
+      <template #right-icon>
+        <van-checkbox
+          :name="item"
+          :ref="el => checkboxRefs[index] = el"
+          @click.stop
+        />
+      </template>
+    </van-cell>
+  </van-cell-group>
+</van-checkbox-group>
+```
+
+```js
+import { ref, onBeforeUpdate } from 'vue';
+
+export default {
+  setup() {
+    const checked = ref([]);
+    const checkboxRefs = ref([]);
+    const toggle = (index) => {
+      checkboxRefs.value[index].toggle();
+    };
+
+    onBeforeUpdate(() => {
+      checkboxRefs.value = [];
+    });
+
+    return {
+      list: ['a', 'b'],
+      toggle,
+      checked,
+      checkboxRefs,
+    };
+  },
+};
+```
+
+## API
+
+### Checkbox Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| v-model | 是否为选中状态 | _boolean_ | `false` |
+| name | 标识符，通常为一个唯一的字符串或数字 | _any_ | - |
+| size | 尺寸：`normal` 为 16px 图标 / 14px 文本，`large` 为 20px 图标 / 16px 文本 | _string_ | `large` |
+| shape | 形状，可选值为 `square` | _string_ | `round` |
+| disabled | 是否禁用复选框 | _boolean_ | `false` |
+| label-disabled | 是否禁用复选框文本点击 | _boolean_ | `false` |
+| label-position | 文本位置，可选值为 `left` | _string_ | `right` |
+| icon-size | 图标大小，默认单位为 `px` | _number \| string_ | `16px` |
+| label-font-size | 文本字号，默认单位为 `px` | _number \| string_ | `14px` |
+| checked-color | 选中状态颜色 | _string_ | `#1989fa` |
+| bind-group | 是否与复选框组绑定 | _boolean_ | `true` |
+
+### CheckboxGroup Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| v-model | 所有选中项的标识符 | _any[]_ | - |
+| disabled | 是否禁用所有复选框 | _boolean_ | `false` |
+| max | 最大可选数，`0` 为无限制 | _number \| string_ | `0` |
+| direction | 排列方向，可选值为 `horizontal` | _string_ | `vertical` |
+| size | 所有复选框的尺寸：`normal` 为 16px 图标 / 14px 文本，`large` 为 20px 图标 / 16px 文本 | _string_ | `large` |
+| icon-size | 所有复选框的图标大小，默认单位为 `px` | _number \| string_ | `16px` |
+| label-font-size | 所有复选框的文本字号，默认单位为 `px` | _number \| string_ | `14px` |
+| checked-color | 所有复选框的选中状态颜色 | _string_ | `#1989fa` |
+
+### Checkbox Events
+
+| 事件名 | 说明                     | 回调参数            |
+| ------ | ------------------------ | ------------------- |
+| change | 当绑定值变化时触发的事件 | _checked: boolean_  |
+| click  | 点击复选框时触发         | _event: MouseEvent_ |
+
+### CheckboxGroup Events
+
+| 事件名 | 说明                     | 回调参数       |
+| ------ | ------------------------ | -------------- |
+| change | 当绑定值变化时触发的事件 | _names: any[]_ |
+
+### Checkbox Slots
+
+| 名称    | 说明       | 参数                                      |
+| ------- | ---------- | ----------------------------------------- |
+| default | 自定义文本 | -                                         |
+| icon    | 自定义图标 | _{ checked: boolean, disabled: boolean }_ |
+
+### CheckboxGroup 方法
+
+通过 ref 可以获取到 CheckboxGroup 实例并调用实例方法，详见[组件实例方法](#/zh-CN/advanced-usage#zu-jian-shi-li-fang-fa)。
+
+| 方法名 | 说明 | 参数 | 返回值 |
+| --- | --- | --- | --- |
+| toggleAll | 切换所有复选框，传 `true` 为选中，`false` 为取消选中，不传参为取反 | _options?: boolean \| object_ | - |
+
+### toggleAll 方法示例
+
+```js
+import { ref } from 'vue';
+import type { CheckboxGroupInstance } from 'vant';
+
+const checkboxGroupRef = ref<CheckboxGroupInstance>();
+
+// 全部反选
+checkboxGroupRef?.value.toggleAll();
+// 全部选中
+checkboxGroupRef?.value.toggleAll(true);
+// 全部取消
+checkboxGroupRef?.value.toggleAll(false);
+
+// 全部反选，并跳过禁用的复选框
+checkboxGroupRef?.value.toggleAll({
+  skipDisabled: true,
+});
+// 全部选中，并跳过禁用的复选框
+checkboxGroupRef?.value.toggleAll({
+  checked: true,
+  skipDisabled: true,
+});
+```
+
+### Checkbox 方法
+
+通过 ref 可以获取到 Checkbox 实例并调用实例方法，详见[组件实例方法](#/zh-CN/advanced-usage#zu-jian-shi-li-fang-fa)。
+
+| 方法名 | 说明 | 参数 | 返回值 |
+| --- | --- | --- | --- |
+| toggle | 切换选中状态，传 `true` 为选中，`false` 为取消选中，不传参为取反 | _checked?: boolean_ | - |
+
+### 类型定义
+
+组件导出以下类型定义：
+
+```ts
+import type {
+  CheckboxProps,
+  CheckboxShape,
+  CheckboxInstance,
+  CheckboxLabelPosition,
+  CheckboxGroupProps,
+  CheckboxGroupInstance,
+  CheckboxGroupDirection,
+  CheckboxGroupToggleAllOptions,
+} from 'vant';
+```
+
+`CheckboxInstance` 和 `CheckboxGroupInstance` 是组件实例的类型，用法如下：
+
+```ts
+import { ref } from 'vue';
+import type { CheckboxInstance, CheckboxGroupInstance } from 'vant';
+
+const checkboxRef = ref<CheckboxInstance>();
+const checkboxGroupRef = ref<CheckboxGroupInstance>();
+
+checkboxRef.value?.toggle();
+checkboxGroupRef.value?.toggleAll();
+```
+
+## 主题定制
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](#/zh-CN/config-provider)。
+
+| 名称 | 默认值 | 描述 |
+| --- | --- | --- |
+| --van-checkbox-size | _var(--van-font-size-lg)_ | normal 尺寸的图标大小 |
+| --van-checkbox-border-color | _var(--van-gray-5)_ | - |
+| --van-checkbox-transition-duration | _var(--van-animation-duration-fast)_ | - |
+| --van-checkbox-label-margin | _var(--van-padding-base)_ | normal 尺寸的图标与文本间距 |
+| --van-checkbox-label-color | _var(--van-text-color)_ | 复选框文本颜色 |
+| --van-checkbox-label-font-size | _var(--van-font-size-md)_ | 复选框文本字号 |
+| --van-checkbox-label-line-height | _var(--van-line-height-lg)_ | normal 尺寸的文本行高 |
+| --van-checkbox-large-size | _var(--van-font-size-xl)_ | 大号复选框图标尺寸 |
+| --van-checkbox-large-label-margin | _6px_ | 大号复选框图标与文本间距 |
+| --van-checkbox-large-label-font-size | _var(--van-font-size-lg)_ | 大号复选框文本字号 |
+| --van-checkbox-large-label-line-height | _var(--van-line-height-xl)_ | 大号复选框文本行高 |
+| --van-checkbox-checked-icon-color | _var(--van-primary-color)_ | - |
+| --van-checkbox-disabled-icon-color | _var(--van-gray-5)_ | - |
+| --van-checkbox-disabled-label-color | _var(--van-text-color-3)_ | - |
+| --van-checkbox-disabled-background-color | _var(--van-border-color)_ | - |

package/lib/checkbox/index.ts

@@ -0,0 +1,17 @@
+import { withInstall } from '../utils';
+import _Checkbox from './Checkbox';
+
+export const Checkbox = withInstall(_Checkbox);
+export default Checkbox;
+export type { CheckboxProps } from './Checkbox';
+export type {
+  CheckboxShape,
+  CheckboxInstance,
+  CheckboxLabelPosition,
+} from './types';
+
+declare module 'vue' {
+  export interface GlobalComponents {
+    VanCheckbox: typeof Checkbox;
+  }
+}

package/lib/checkbox/style/index.js

@@ -1,5 +1,5 @@
-require("../../style/base.css");
-require("../../badge/index.css");
-require("../../icon/index.css");
-require("../../checkbox-group/index.css");
-require("../index.css");
+require('../../style/base.css');
+require('../../badge/index.css');
+require('../../icon/index.css');
+require('../../checkbox-group/index.css');
+require('../index.css');

package/lib/checkbox/style/less.js

@@ -1,5 +1,5 @@
-require("../../style/base.less");
-require("../../badge/index.less");
-require("../../icon/index.less");
-require("../../checkbox-group/index.less");
-require("../index.less");
+require('../../style/base.less');
+require('../../badge/index.less');
+require('../../icon/index.less');
+require('../../checkbox-group/index.less');
+require('../index.less');

package/lib/checkbox/types.ts

@@ -0,0 +1,19 @@
+import type { ComponentPublicInstance, ComputedRef } from 'vue';
+import type { CheckboxProps } from './Checkbox';
+import type { CheckerShape, CheckerLabelPosition } from './Checker';
+
+export type CheckboxShape = CheckerShape;
+export type CheckboxLabelPosition = CheckerLabelPosition;
+
+export type CheckboxExpose = {
+  toggle: (newValue?: boolean) => void;
+  /** @private */
+  props: CheckboxProps;
+  /** @private */
+  checked: ComputedRef<boolean>;
+};
+
+export type CheckboxInstance = ComponentPublicInstance<
+  CheckboxProps,
+  CheckboxExpose
+>;

package/lib/checkbox-group/CheckboxGroup.tsx

@@ -0,0 +1,89 @@
+import {
+  watch,
+  defineComponent,
+  type PropType,
+  type InjectionKey,
+  type ExtractPropTypes,
+} from 'vue';
+
+// Utils
+import { numericProp, createNamespace, makeArrayProp } from '../utils';
+
+// Composables
+import { useChildren, useCustomFieldValue } from '@vant/use';
+import { useExpose } from '../composables/use-expose';
+
+// Types
+import type { CheckerDirection, CheckerSize } from '../checkbox/Checker';
+import type {
+  CheckboxGroupExpose,
+  CheckboxGroupProvide,
+  CheckboxGroupToggleAllOptions,
+} from './types';
+
+const [name, bem] = createNamespace('checkbox-group');
+
+const checkboxGroupProps = {
+  max: numericProp,
+  disabled: Boolean,
+  iconSize: numericProp,
+  labelFontSize: numericProp,
+  size: String as PropType<CheckerSize>,
+  direction: String as PropType<CheckerDirection>,
+  modelValue: makeArrayProp<unknown>(),
+  checkedColor: String,
+};
+
+export type CheckboxGroupProps = ExtractPropTypes<typeof checkboxGroupProps>;
+
+export const CHECKBOX_GROUP_KEY: InjectionKey<CheckboxGroupProvide> =
+  Symbol(name);
+
+export default defineComponent({
+  name,
+
+  props: checkboxGroupProps,
+
+  emits: ['change', 'update:modelValue'],
+
+  setup(props, { emit, slots }) {
+    const { children, linkChildren } = useChildren(CHECKBOX_GROUP_KEY);
+
+    const updateValue = (value: unknown[]) => emit('update:modelValue', value);
+
+    const toggleAll = (options: CheckboxGroupToggleAllOptions = {}) => {
+      if (typeof options === 'boolean') {
+        options = { checked: options };
+      }
+
+      const { checked, skipDisabled } = options;
+
+      const checkedChildren = children.filter((item: any) => {
+        if (!item.props.bindGroup) {
+          return false;
+        }
+        if (item.props.disabled && skipDisabled) {
+          return item.checked.value;
+        }
+        return checked ?? !item.checked.value;
+      });
+
+      const names = checkedChildren.map((item: any) => item.name);
+      updateValue(names);
+    };
+
+    watch(
+      () => props.modelValue,
+      (value) => emit('change', value)
+    );
+
+    useExpose<CheckboxGroupExpose>({ toggleAll });
+    useCustomFieldValue(() => props.modelValue);
+    linkChildren({
+      props,
+      updateValue,
+    });
+
+    return () => <div class={bem([props.direction])}>{slots.default?.()}</div>;
+  },
+});

package/lib/checkbox-group/index.ts

@@ -0,0 +1,17 @@
+import { withInstall } from '../utils';
+import _CheckboxGroup from './CheckboxGroup';
+
+export const CheckboxGroup = withInstall(_CheckboxGroup);
+export default CheckboxGroup;
+export type { CheckboxGroupProps } from './CheckboxGroup';
+export type {
+  CheckboxGroupInstance,
+  CheckboxGroupDirection,
+  CheckboxGroupToggleAllOptions,
+} from './types';
+
+declare module 'vue' {
+  export interface GlobalComponents {
+    VanCheckboxGroup: typeof CheckboxGroup;
+  }
+}

package/lib/checkbox-group/style/index.js

@@ -1,2 +1,2 @@
-require("../../style/base.css");
-require("../index.css");
+require('../../style/base.css');
+require('../index.css');

package/lib/checkbox-group/style/less.js

@@ -1,2 +1,2 @@
-require("../../style/base.less");
-require("../index.less");
+require('../../style/base.less');
+require('../index.less');

package/lib/checkbox-group/types.ts

@@ -0,0 +1,26 @@
+import type { ComponentPublicInstance } from 'vue';
+import type { CheckboxGroupProps } from './CheckboxGroup';
+import type { CheckerParent, CheckerDirection } from '../checkbox/Checker';
+
+export type CheckboxGroupDirection = CheckerDirection;
+
+export type CheckboxGroupToggleAllOptions =
+  | boolean
+  | {
+      checked?: boolean;
+      skipDisabled?: boolean;
+    };
+
+export type CheckboxGroupExpose = {
+  toggleAll: (options?: CheckboxGroupToggleAllOptions) => void;
+};
+
+export type CheckboxGroupInstance = ComponentPublicInstance<
+  CheckboxGroupProps,
+  CheckboxGroupExpose
+>;
+
+export type CheckboxGroupProvide = CheckerParent & {
+  props: CheckboxGroupProps;
+  updateValue: (value: unknown[]) => void;
+};