透传 API (pt)

PassThrough（透传）是一种用于访问组件内部结构的 API，它允许开发者将样式属性直接应用于组件内部的各个部位（如按钮的文本、图标、加载指示器），突破组件主 API 的限制，提供更灵活的定制能力。

概念

每个组件的 props.uts 中除了 Props 外，还会声明一个 PassThrough 类型。组件根属性 pt 即对应该类型。pt 通常包含：

• className：作用于组件根元素的自定义类名
• 若干部位键：如按钮的 label / icon / loading，各自接受对应子组件的 Props 或 PassThroughProps

所有 PassThrough 部位都至少支持 className（PassThroughProps）。若某部位本身是一个子组件（如 icon 是 JzIconProps），则可直接透传该子组件的全部属性（size / color / name 等）。

基本用法

<jz-button
  :pt="{
    className: '!rounded-2xl',
    icon: {
      size: 50,
      className: 'mr-5'
    },
    label: {
      color: 'red',
      className: 'font-bold'
    },
    loading: {
      size: 50
    }
  }"
>
  点击
</jz-button>

上例中：

• className: '!rounded-2xl' 作用于按钮根元素
• icon.size / icon.className 作用于内部图标
• label.color / label.className 作用于内部文本
• loading.size 作用于加载指示器

各组件的部位键

不同组件暴露的部位键不同，均在其 props.uts 的 XxxPassThrough 类型中声明。常见示例：

组件	pt 部位键
jz-button	className、label(JzTextProps)、icon(JzIconProps)、loading(JzLoadingProps)
jz-image	className、inner、error(JzIconProps)、loading
jz-input	className、inner、prefixIcon、suffixIcon
jz-form-item	className、inner、label(JzTextProps)、content、error(JzTextProps)
jz-popup	className、inner、header、container、mask、draw
jz-tabs	className、text、item、line、slider
jz-list-item	className、wrapper、inner、label、content、icon、image、collapse
jz-slider	className、track、progress、thumb、value(JzTextProps)
jz-tree-item	item、itemChecked、itemWrapper、expand、expandIcon、checkbox、checkedIcon、halfCheckedIcon、uncheckedIcon、label

每个组件文档页的「透传 (pt)」小节列出了该组件完整的部位键。

与 className 的关系

组件根属性同时提供 className 与 pt.className，两者都会作用于根元素（内部经 parseClass 合并）。简单场景直接用 className；需要穿透到内部部位时才使用 pt。

类名操作符

className 支持 Tailwind 风格的操作符写法（如 ! 提升优先级、dark: 暗色变体），由内部 parseClass 解析：

<view class="bg-surface-100 dark:!bg-surface-900">
  <jz-text :pt="{ className: 'text-surface-700 dark:!text-white' }" value="文本"></jz-text>
</view>

注意事项

• pt 是一个对象，模板中建议用 :pt="{ ... }" 内联绑定，或在脚本中构造 UTSJSONObject。
• 部位键拼写需与 props.uts 中声明一致，否则不生效。
• 透传的是样式属性，不改变组件行为逻辑。