前言

组件参数命名看起来是小事，实际会直接影响维护成本。HarmonyOS7 的 ArkUI 组件经常通过 @Prop、@Link 和回调传递数据，如果参数叫 data、info、value，短期能写，长期会让调用方猜含义。尤其按钮、筛选条、表单项这种复用组件，名字不清楚，复用越多越难改。

我建议组件参数尽量表达“业务角色”，而不是表达“数据形态”。例如按钮组件里，label 比 text 更接近按钮语义，disabledReason 比 desc 更明确，onSubmit 比 callback 更可维护。

好的参数名应该让调用代码自己解释自己，而不是靠注释补救。

为什么这个问题经常被写乱

组件参数命名决定可维护性 这类内容很容易被写成“代码能跑就算讲完了”，但对初学者来说，这恰恰是最不够的地方。真正让人卡住的，往往不是某个组件名记不住，而是不知道这段代码为什么要这样拆、状态为什么要这样放、以后需求变化时应该从哪里改。

所以这篇文章不只想给你一个能跑的例子，更想把背后的判断过程讲清楚。你只要把这个判断过程吃透，后面自己改页面、补需求、查问题时，心里会稳很多。

场景：可复用的操作按钮

我们实现一个订单操作按钮，支持主按钮和普通按钮两种样式，支持禁用原因，并通过回调把点击交给父组件。

这个组件的重点不是按钮样式，而是调用处能不能读懂。看到 enabled: this.paid && !this.shipped 和 disabledReason: '请先完成支付'，维护者不用打开组件内部，也能知道业务规则是什么。

命名对比

弱命名	更好的命名	原因

| text | label | 按钮上的文案更像标签 |
| type | variant | 避免和系统类型概念混淆 |
| disabled | enabled 或 isDisabled | 布尔语义更直接 |
| fn | onAction | 明确这是操作回调 |
| msg | disabledReason | 说明文案出现的条件 |

先把页面目标想清楚

在真正写代码之前，先别急着盯着 API。更有用的做法是先想清楚：这个页面到底想解决什么问题，用户最在意的反馈是什么，哪些状态必须一直保持一致。

当你先把这条主线想明白，再回头看组件和状态设计，很多选择都会顺理成章。对小白来说，这一步尤其重要，因为它能帮你从“照着抄”慢慢过渡到“看得懂、改得动”。

完整代码示例

enum ActionButtonVariant {
  Primary,
  Secondary
}

@Component
struct OrderActionButton {
  label: string
  variant: ActionButtonVariant = ActionButtonVariant.Secondary
  enabled: boolean = true
  disabledReason: string = ''
  trackingName: string = ''
  onAction: () => void = () => {}

  private backgroundColor(): string {
    if (!this.enabled) {
      return '#DADCE0'
    }
    return this.variant === ActionButtonVariant.Primary ? '#0A59F7' : '#FFFFFF'
  }

  private fontColor(): string {
    if (!this.enabled) {
      return '#8A8A8A'
    }
    return this.variant === ActionButtonVariant.Primary ? '#FFFFFF' : '#222222'
  }

  build() {
    Column({ space: 6 }) {
      Button(this.label)
        .width('100%')
        .height(42)
        .enabled(this.enabled)
        .backgroundColor(this.backgroundColor())
        .fontColor(this.fontColor())
        .onClick(() => {
          if (this.trackingName.length > 0) {
            console.info(`tap action ${this.trackingName}`)
          }
          this.onAction()
        })

      if (!this.enabled && this.disabledReason.length > 0) {
        Text(this.disabledReason)
          .fontSize(12)
          .fontColor('#777777')
          .width('100%')
      }
    }
    .width('100%')
  }
}

@Entry
@Component
struct ComponentParamNamePage {
  @State paid: boolean = false
  @State shipped: boolean = false
  @State notice: string = '请选择订单操作'

  private payOrder(): void {
    this.paid = true
    this.notice = '订单已支付，可以安排发货'
  }

  private shipOrder(): void {
    if (!this.paid) {
      this.notice = '未支付订单不能发货'
      return
    }
    this.shipped = true
    this.notice = '订单已发货'
  }

  build() {
    Column({ space: 16 }) {
      Text('订单操作')
        .fontSize(28)
        .fontWeight(FontWeight.Bold)
        .width('100%')

      Column({ space: 8 }) {
        Text('订单号：OD20260711060')
          .fontSize(15)
          .width('100%')
        Text(this.notice)
          .fontSize(14)
          .fontColor(this.shipped ? '#2E7D32' : '#666666')
          .width('100%')
      }
      .alignItems(HorizontalAlign.Start)
      .padding(16)
      .backgroundColor('#FFFFFF')
      .borderRadius(12)
      .width('100%')

      OrderActionButton({
        label: this.paid ? '已支付' : '立即支付',
        variant: ActionButtonVariant.Primary,
        enabled: !this.paid,
        disabledReason: '订单已经完成支付',
        trackingName: 'pay_order',
        onAction: () => {
          this.payOrder()
        }
      })

      OrderActionButton({
        label: this.shipped ? '已发货' : '安排发货',
        variant: ActionButtonVariant.Secondary,
        enabled: this.paid && !this.shipped,
        disabledReason: this.paid ? '订单已经发货' : '请先完成支付',
        trackingName: 'ship_order',
        onAction: () => {
          this.shipOrder()
        }
      })
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .backgroundColor('#F5F7FA')
  }
}

关键代码说明

label 比 text 更贴近组件语义。 调用处看到 label: '立即支付'，就知道这是按钮显示文案。

variant 表达视觉变体。 它不是业务状态，而是组件样式选择，配合 ActionButtonVariant 更清楚。

enabled 和 disabledReason 配套出现。 只告诉组件禁用还不够，真实业务里用户需要知道为什么不能点。

onAction 是明确回调。 它比 callback、fn 更能表达点击后的业务动作。

trackingName 表达埋点语义。 如果叫 name 或 key，调用处很难知道它是组件标题、业务 id，还是埋点事件名。参数越接近真实用途，误用概率越低。

参数命名原则

1. 用业务语义命名。 能叫 orderId 就不要叫 id。
2. 布尔值要能读成判断句。 enabled、isSelected、hasError 都比 flag 好。
3. 回调用 onXxx。 看到名字就知道它是事件出口。
4. 避免万能参数名。 data、info、item 只有在局部上下文很明确时才用。

调用处要能自解释

调用参数	读出来的含义
label: '安排发货'	按钮显示什么
variant: ActionButtonVariant.Secondary	使用哪种视觉样式
enabled: this.paid && !this.shipped	当前是否允许点击
disabledReason: '请先完成支付'	不能点时告诉用户原因
onAction: () => { this.shipOrder() }	点击后执行什么业务动作

好的组件参数名会减少注释需求。调用方看一眼就知道自己在配置什么，组件内部也不需要猜调用方的意图。

改参数名时看调用处

组件参数命名不要只在组件内部看，要回到调用处读一遍。OrderActionButton({ label, variant, enabled, disabledReason, onAction }) 这组参数放在一起，基本能读出按钮的展示、样式、可用条件、禁用原因和点击行为。

布尔参数尤其要谨慎。flag 这种名字在组件内部也许暂时能懂，到了调用处就完全失去语义。enabled: this.paid && !this.shipped 至少能读成“当前是否允许点击”，维护者不用翻组件源码。

回调也一样。onAction 表示用户触发操作，trackingName 表示埋点名称，两个名字各自承担明确语义。参数越具体，后续复用时越不容易误传。

结语

HarmonyOS7 的 ArkUI 组件复用越多，参数命名越重要。命名不是表面功夫，它决定调用代码能不能长期自解释。组件可以晚点抽象，但一旦抽象，参数名就要认真定。