可点击卡片 · ClickableCard

让整张卡片成为可访问的操作入口，并正确处理嵌套按钮。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

可点击卡片 · 综合展示 1：首先体验这个示例，再查看代码理解组件的组合方式。
可点击卡片 · 交互示例 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
可点击卡片 · 交互示例 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

Clickable Card

An interactive card for navigation or action targets. Nested interactive elements work independently.

属性	类型	默认值	说明
label *	string		Accessibility label.
onClick	(event: MouseEvent) => void		Click handler: fires on card surface only.
href	string		Navigation URL. Plain, new-tab, Cmd/Ctrl-click, and middle-click activation all follow the shared navigation rule described on the Link `href` prop.
target	string	'_self'	Link target.
isDisabled	boolean	false	Disables the card, removes a link destination, and leaves the card out of the tab order.
children	ReactNode		Card content.
padding	0 \| 0.5 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 10	4	Inner padding.
variant	'default' \| 'transparent' \| 'muted' \| 'blue' \| 'cyan' \| 'gray' \| 'green' \| 'orange' \| 'pink' \| 'purple' \| 'red' \| 'teal' \| 'yellow'	'default'	Background color variant.
elevation	'none' \| 'low' \| 'med' \| 'high'	'none'	Resting shadow depth. Often raised to signal the whole card is clickable.
width	SizeValue		Card width.
height	SizeValue		Card height.
maxWidth	SizeValue		Maximum card width.
xstyle	StyleXStyles		StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.

使用建议

Use for cards that navigate to a detail page or trigger a single action.
Nest buttons or links freely inside; they handle their own events.
避免：Use for toggling selection; use SelectableCard for that.

主题 API

{
  "container": true,
  "targets": [
    {
      "className": "astryx-clickable-card",
      "visualProps": [
        "variant"
      ]
    }
  ],
  "vars": [
    {
      "name": "--_press-overlay",
      "description": "Fill of the ::after interaction overlay: transparent at rest, the hover overlay token on hover (hover-capable pointers), the pressed overlay token while pressed (`:active` on a mouse; `data-astryx-press=\"on\"` written by the touch press controller under a finger) and the hover token for the release fade. Set on the card element by its own interaction arms.",
      "default": "transparent",
      "private": true
    },
    {
      "name": "--_press-overlay-transition",
      "description": "Duration of the overlay's background-color transition: the fast duration token, except 0s while a believed touch press paints so it lands on the first frame.",
      "default": "var(--duration-fast)",
      "private": true
    }
  ]
}

组件结构

Container: Interactive div with hover/focus/active states.
Content: Children, which may include nested interactive elements.