• UI组件
• 前端

本文围绕 Varlet（基于 Material Design 2/3、同时支持移动端与桌面端的 Vue 3 组件库）官方文档中的「默认值定制（Defaults Customization）」能力展开，系统讲解如何通过组件静态方法setPropsDefaults批量定制组件属性的默认值，并结合仓库源码剖析其底层实现、生效范围与使用约束。读完本文，你将能够为项目中的 Varlet 组件统一预设主题风格与行为默认值，并理解该机制为何只在声明式组件上生效、为何必须在组件初始化之前调用。

一、功能概述：为什么要定制组件属性默认值

在实际业务中，同一个组件库往往需要被多个页面或多个业务线共用。不同项目对「默认外观」的需求可能各不相同：例如 A 项目希望所有按钮默认使用primary主色，B 项目则希望按钮默认带有更高等级的阴影（elevation）。如果逐处书写type="primary"或:elevation="10"，不仅模板冗长，后续调整主题时也需要大范围改动。

Varlet 组件库为此提供了组件属性默认值定制能力：通过组件导出的静态方法setPropsDefaults，可以在组件初始化之前，批量改写组件 props 的定义，从而让「未显式声明属性的组件」自动获得定制后的默认值。该能力与 CSS 变量主题定制（Themes）互为补充，前者作用于组件行为与结构层（props），后者作用于视觉层（CSS 变量），共同构成 Varlet 的主题定制体系。

二、基本用法：在入口文件中预设全局默认值

官方文档（英文版、中文版）给出的核心用法非常简单：在应用入口文件（如main.ts）中，导入组件后直接调用其静态方法setPropsDefaults，传入一个「属性名 → 默认值」的映射对象即可：

// playground-ignore // main.ts import { Button } from '@varlet/ui' Button.setPropsDefaults({ type: 'primary', elevation: 10 })

以上代码执行完毕后，下面两种模板写法将完全等价：

<!-- playground-ignore --> <!-- App.vue：写法一，未显式声明属性 --> <template> <var-button>Hello</var-button> </template>

<!-- playground-ignore --> <!-- App.vue：写法二，显式声明属性 --> <template> <var-button type="primary" :elevation="10">Hello</var-button> </template>

也就是说，<var-button>Hello</var-button>在渲染时会被视为<var-button type="primary" :elevation="10">。定制遵循「就近覆盖」的自然规则：凡是模板中显式传入的属性值，优先级始终高于setPropsDefaults设定的默认值；只有未传入的属性才会落到定制后的默认值上。

2.1 类型签名

从类型层面看，setPropsDefaults并非组件各自独立实现的零散方法，而是 Varlet 所有组件统一遵守的静态接口。仓库中 types/varComponent.d.ts 定义了统一的函数类型：

export type SetPropsDefaults<P> = (defaults: Partial<Record<keyof P, any>>) => void

而每个组件的声明文件中都会声明该静态方法，例如 types/button.d.ts：

export class Button extends VarComponent { static setPropsDefaults: SetPropsDefaults<ButtonProps> // ... }

这意味着：defaults的键必须取自对应组件的ButtonProps（如type、size、elevation、color等公开属性名），传入不存在的属性名会被安全忽略（详见下文实现解析），TypeScript 也会在编译期给出属性名的约束提示。

三、底层实现剖析：withPropsDefaultsSetter 的合并逻辑

setPropsDefaults并非组件库在运行时临时拼装的魔法，而是由工具函数withPropsDefaultsSetter在组件模块初始化时统一挂载到组件对象上的。该函数位于 src/utils/components.ts：

export function withPropsDefaultsSetter(target: any, props: Record<string, any>) { target.setPropsDefaults = function (defaults: Record<string, any>) { Object.entries(defaults).forEach(([key, value]) => { const prop = props[key] if (prop == null) { return } if (isPlainObject(prop)) { // 例如 prop 形如 { type: String } props[key] = { ...prop, default: value, } return } props[key] = { type: prop, default: value, } }) } }

其核心逻辑可拆解为三步：

1. 挂载静态方法：将setPropsDefaults定义为target（即组件对象）上的静态方法，闭包持有该组件的props定义对象。
2. 按键名匹配：遍历传入的defaults条目，若props中不存在对应属性（prop == null）则直接跳过，保证传入非法键名不会报错、也不会产生脏数据。
3. 改写 props 定义：
   • 若原属性定义是纯对象（如{ type: String }形态），则通过展开运算符保留原有type等字段，并追加default: value；
   • 若原属性定义是裸的构造函数或构造数组（如String、[String, Number]形态），则包装成{ type: prop, default: value }。

3.1 组件模块中的装配现场

以文档示例中的Button为例，其模块入口 src/button/index.ts 同时调用了两个工具函数：

import { withInstall, withPropsDefaultsSetter } from '../utils/components' import Button from './Button.vue' import { props as buttonProps } from './props' withInstall(Button) withPropsDefaultsSetter(Button, buttonProps)

• withInstall为组件追加install(app)方法，使其可作为插件被app.use()注册；
• withPropsDefaultsSetter为组件挂载setPropsDefaults静态方法。

这种「两个工具函数一行装配」的模式遍布整个组件库：Input、Dialog、Cell、Tabs等几乎所有组件的入口文件（如 src/input/index.ts）都遵循同一模式。换句话说，只要组件的入口文件调用了withPropsDefaultsSetter，该组件就天然支持setPropsDefaults定制。

3.2 被改写的 props 长什么样

Button的 props 定义见 src/button/props.ts。其中type与elevation的原始形态分别是：

type: String as PropType<ButtonType>, // 裸构造函数形态 elevation: { type: [Boolean, Number, String], // 纯对象形态 default: true, },

因此在调用Button.setPropsDefaults({ type: 'primary', elevation: 10 })之后：

• type由String as PropType<ButtonType>被改写为{ type: String as PropType<ButtonType>, default: 'primary' }；
• elevation由{ type: [Boolean, Number, String], default: true }被改写为{ type: [Boolean, Number, String], default: 10 }。

由于 Vue 3 的 props 默认值解析由组件实例化时的resolveProps完成，这份被改写后的定义会被所有后续实例共享，从而实现对全应用按钮的默认值覆盖。

3.3 测试用例的印证

仓库为withPropsDefaultsSetter提供了专门的单测，见 src/utils/tests/components.spec.js。测试构造了三种典型属性形态——裸构造函数String、构造数组[String, Number]、纯对象{ type: String }——并在调用setPropsDefaults后断言 props 被正确改写：

withPropsDefaultsSetter(mock, props) mock.setPropsDefaults({ name: 'default name', age: 'default age', gender: 'default gender', }) expect(props).toStrictEqual({ name: { type: String, default: 'default name' }, age: { type: [String, Number], default: 'default age' }, gender: { type: String, default: 'default gender' }, })

这份测试精确验证了上文所述的两条改写分支（裸类型包装为对象、纯对象追加default），可作为理解该机制行为的权威依据。

四、生效范围与使用约束

4.1 只对声明式组件生效

官方文档明确指出：「属性定制只对声明式组件生效（attribute customization only takes effect for declarative components）」。所谓声明式组件，指通过defineComponent+props选项声明、以<var-button>这类标签形式使用的组件——setPropsDefaults改写的正是这类组件的props定义。

反过来看，Dialog这类「命令式（函数式）组件」比较特殊：它们除了提供声明式的<var-dialog>标签用法，还导出了Dialog(options)命令式调用。命令式调用并不走组件 props 解析流程，因此其默认值由另一套机制管理——src/dialog/index.ts 中的Dialog.setDefaultOptions：

Dialog.setDefaultOptions = function (options: DialogOptions) { defaultOptions = options } Dialog.resetDefaultOptions = function () { defaultOptions = {} }

Dialog(options)在normalizeOptions中会把defaultOptions与本次调用传入的options合并（src/dialog/index.ts），从而实现命令式对话框默认配置的定制与重置。可以推断，组件库正是通过「声明式走setPropsDefaults、命令式走setDefaultOptions」的双轨设计，来分别覆盖两种使用形态的默认值需求。

4.2 必须在组件初始化之前调用

由于setPropsDefaults会直接改写组件模块共享的props对象（属于模块级的全局副作用），因此官方文档强调：定制行为应当发生在组件初始化之前。实践中最稳妥的做法，是在应用的入口文件（main.ts）中、createApp(...).use(...)注册组件之前完成所有定制，例如：

// playground-ignore // main.ts —— 定制与注册、挂载的顺序 import { createApp } from 'vue' import { Button, Input } from '@varlet/ui' import App from './App.vue' // 1. 先定制默认值 Button.setPropsDefaults({ type: 'primary', elevation: 10 }) Input.setPropsDefaults({ clearable: true }) // 2. 再注册与挂载 createApp(App).use(Button).use(Input).mount('#app')

4.3 属性值语义与既有默认值的关系

定制会整体覆盖原属性定义中的default字段。以Button的elevation为例，其原始默认值为true（见 src/button/props.ts），而按钮渲染时会通过工具函数formatElevation(elevation, 2)将阴影值映射为var-elevation--N类（src/utils/components.ts）：

export function formatElevation(elevation: number | boolean | string, defaultLevel?: number) { if (elevation === false) { return null } if (elevation === true && defaultLevel) { elevation = defaultLevel } return `var-elevation--${elevation}` }

因此：

• 默认（未定制）时elevation === true，会被换算为var-elevation--2（二级阴影）；
• 定制为elevation: 10后，默认渲染即为var-elevation--10（十级阴影）；
• 若业务需要关闭阴影，可定制为elevation: false，formatElevation将返回null，按钮不再带阴影。

可见，定制值不仅改变默认值本身，还会联动组件内部的语义化换算逻辑，理解这一点有助于避免「定制了数字却看不出阴影变化」之类的困惑。

五、典型实战场景与进阶建议

5.1 统一品牌色：全站按钮一键换肤

// playground-ignore // main.ts import { Button, Chip, Link } from '@varlet/ui' Button.setPropsDefaults({ type: 'primary', round: true }) Chip.setPropsDefaults({ type: 'primary' }) Link.setPropsDefaults({ type: 'primary', underline: true })

将品牌主色统一收敛到type: 'primary'，既消除了模板中大量重复的type声明，也方便在品牌色调整时只改一处。

5.2 表单体系默认行为对齐

// playground-ignore // main.ts import { Input, Counter, Select } from '@varlet/ui' Input.setPropsDefaults({ clearable: true, variant: 'outlined' }) Counter.setPropsDefaults({ readonly: false })

表单类组件往往横跨多个页面，通过默认值定制可以强制统一交互细节（如是否可清除、输入框形态），避免不同页面写法漂移。

5.3 与组件库其他定制能力的搭配

• 主题变量定制：属性默认值负责「组件怎么渲染」（结构/行为），CSS 变量主题（themes目录）负责「组件长什么样」（视觉），二者结合可实现完整的品牌化定制；
• 样式覆盖与扩展：若需在默认值基础上进一步做局部差异化，可通过 Vue 的组件继承或全局attrs传递实现，setPropsDefaults提供的只是「全局基线」。

六、结语

Varlet 的setPropsDefaults用极小的 API 表面（一个静态方法）解决了组件库全局默认值定制的通用诉求：其背后是withPropsDefaultsSetter对 props 定义对象的结构化改写，配合组件入口文件的统一装配（src/utils/components.ts、src/button/index.ts），以及配套单测（src/utils/tests/components.spec.js）的严格保障。

最后再回顾三条关键约束：只对声明式组件生效、必须在组件初始化之前调用、显式传入的属性永远优先于定制默认值。把握住这三点，你就能在任意 Varlet 项目中安全、高效地建立一套统一的组件默认行为基线。该文档在组件库站点中对应「默认值定制 / Defaults Customization」导航条目（见 varlet.config.mjs），如需查阅中文原文，可直接阅读 defaultsCustomization.zh-CN.md。

• UI组件
• 前端