---
title: 开发文档
order: 3
category: atom
---

# PisellBaseCard 开发文档

## 1. 组件信息

- **组件名称**: PisellBaseCard
- **组件版本**: 1.0.0
- **组件分类**: Atom Components / Data Display
- **描述**: 基础卡片容器组件，提供高度可定制的容器用于承载和组织任意类型的子内容；支持默认/悬停/按下/禁用四种状态的样式配置，可作为更复杂 Pro 组件的构建基础。

## 2. 需求点罗列

1. **结构**
   - 外层容器：可配置背景、圆角、边框、阴影、padding、宽高。
   - 内层插槽：仅渲染 `children`，不展示占位（占位由低代码插槽处理）。
2. **状态与样式**
   - 四态样式可配置：默认、悬停、按下、禁用（选中态由低代码包裹类名等实现，组件无选中逻辑）。
   - 默认态视觉：背景 #FFFFFF，边框 1px #EAECF0，圆角 12px，padding 16px，阴影 0px 1px 2px rgba(16,24,40,0.05)；先写死，后续接主题。
3. **交互**
   - 可配置是否可点击，默认可点击。
   - 可点击时：支持 onClick；可 focus（Tab 聚焦，Enter/Space 触发点击）；悬停/按下应用对应样式。
   - 禁用时应用 disabledStyle，不响应点击与焦点。
4. **自适应**
   - 宽度默认跟随父容器；支持通过 style 设置固定宽高或由内容撑开。
   - 最小 padding 2px，避免内容与边框重合。

## 3. 组件 API

### Props 定义

见 `types.ts`。核心包括：

- **内容**: `children`
- **样式**: `className`, `style`, `hoverStyle?`, `activeStyle?`, `disabledStyle?`
- **行为**: `clickable`（默认 true）, `disabled`, `onClick`
- 无 `hoverEffect`（本期不实现）；无 `selected`（选中由低代码处理）。

## 4. 组件模块拆解

1. **PisellBaseCard（主组件）**
   - 解析 Props、合并四态样式（default / hover / active / disabled）。
   - 使用单根 div：可点击时为 button 语义或 div + role="button" + tabIndex + 键盘事件；不可点击时为普通 div。
   - 内层仅渲染 `children`，无占位内容。

2. **样式（Less）**
   - 默认样式写死设计稿数值；类名带 `pisell-base-card-` 前缀。
   - 最小 padding 2px 通过 CSS 约束；状态样式优先使用 props 传入的 style/hoverStyle/activeStyle/disabledStyle 合并。

## 5. 实现方案

### 5.1 根节点与可访问性

- 使用 `<div>` 作为根节点；当 `clickable && !disabled` 时设置 `role="button"`、`tabIndex={0}`，并在 `onKeyDown` 中对 Enter/Space 调用 `onClick`，阻止默认以避免页面滚动。
- `disabled` 时设置 `aria-disabled="true"`，且不设置 tabIndex，不触发 onClick。

### 5.2 状态样式合并

- 默认应用 `style`。
- 使用 React 状态 `isHover`、`isActive`（mousedown/pointerdown 置 true，mouseup/pointerup/leave 置 false）。
- 当 `disabled` 时优先应用 `disabledStyle`（覆盖 style）；否则在 isActive 时合并 `activeStyle`，在 isHover 时合并 `hoverStyle`（合并顺序：style + hoverStyle + activeStyle，或 disabled 时 style + disabledStyle）。

### 5.3 尺寸与自适应

- 不设置默认 width/height，由父容器或 style 控制；通过 style 支持 `width: '100%'`、固定宽高或 `fit-content`。
- 使用 Less 变量或 min padding 保证最小 2px padding（若 style 传入 padding，用 min() 或文档说明由调用方保证）。

## 6. 组成部分与引用

- **现有组件**: 不依赖其他 Pisell 业务组件；仅使用原生 div 与 React。
- **样式**: 独立 Less，不依赖 antd Card；若需与 antd 区分，类名使用 `pisell-base-card-*`，覆盖 antd 时使用 `pisell-lowcode-*`。
- **结构图**:

```
PisellBaseCard
  └── div.pisell-base-card-root (role="button" | 无)
        └── children
```

## 7. 扩展性

- 通过 `className`、`style`、`hoverStyle`、`activeStyle`、`disabledStyle` 扩展外观。
- 通过 `children` 承载任意内容；低代码通过插槽注入内容，组件内不渲染占位。

## 8. 依赖

- react
- 无额外 npm 依赖；样式为 Less。
