关键字参数 / 命名参数

约 726 字大约 2 分钟

2025-04-18

在 Stylus 中，关键字参数（命名参数）是一种通过参数名（而非参数位置）传递值的函数调用方式，它能显著提升代码可读性和灵活性。

提示

关键字参数等于命名参数。二者其实是同一个概念，只是在 Stylus 中，官方文档更喜欢使用关键字参数（Keyword Arguments）这一术语。

一、基本语法

定义带命名参数的函数

// 声明参数默认值（命名参数）
button-style(color, size: 16px, rounded: false)
  color color
  font-size size
  if rounded
    border-radius (size / 2)

调用时指定参数名

.btn
  button-size(color: #f00, rounded: true)  // 跳过 size 参数

二、核心特性

支持默认值：定义时可指定默认值。func(param: default)
位置参数优先：位置参数必须在前，命名参数在后。func(a, b, opt: val)
支持任意顺序：命名参数之间可以任意顺序传递。func(b: 2, a: 1)
可选参数：通过默认值 null 实现可选参数。func(param: null)
参数顺序自由：命名参数的顺序可以任意排列。func(a, b, opt: val)

三、高级用法

1. 强制命名参数

通过默认值 null 强制调用时必须命名：

position(pos=static, top: null, left: null)
  if top != null
    top top
  if left != null
    left left

// 必须使用命名参数
.modal
  position(absolute, top: 10px)

2. 动态参数收集

使用 ... 收集剩余命名参数：

debug-args(args...)
  for key, val in args
    p(key + ': ' + val)

debug-args(color: red, size: 16px)
// 输出: color: red, size: 16px

四、最佳实践

1. 命名规范

推荐使用短横线、下划线命名，更简单直观，避免驼峰式。

// 推荐短横线命名
font-settings(base-size: 16px, font-family: Arial)

// 避免驼峰式
fontSettings(baseSize: 16px, fontFamily: Arial)  // 不推荐

2. 参数分组

当参数较多时，可将相关参数按照顺序放在一起，提高可读性。

// 相关参数放一起
shadow-config(x: 0, y: 0, blur: 5px, color: #000)

3. 文档注释

使用文档注释描述函数用途和参数含义，便于他人理解和维护。

/*
 * @param {Color} color - 主色
 * @param {Length} [size: 16px] - 字号
 */
text-style(color, size: 16px)
  ...

五、常见错误

// ❌ 错误：命名参数在前
func(param: 1, 2)

// ❌ 错误：重复赋值
func(1, param: 2, param: 3)

// ✅ 正确
func(1, param: 2)

六、总结

场景	推荐写法	优势
可选参数多	`func(required, opt: val)`	避免 `null` 占位
布尔型参数	`toggle(active: true)`	含义清晰
参数含义不直观时	`animate(duration: 200ms)`	无需查文档理解参数顺序

Stylus 的命名参数能大幅提升代码可维护性，特别适合：

组件库的 API 设计
含多个可选参数的复杂函数
需要明确参数用途的公共方法

更新日志

2025/8/24 08:17

查看所有更新日志

e7112-1于 2025/8/24