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

# PisellScrollView 开发文档

## 1. 组件信息

- **组件名称**: PisellScrollView
- **组件版本**: 1.0.0
- **组件分类**: Pro Components
- **描述**: 一个功能强大的增强型滚动容器组件，提供自动滚动检测、自定义滚动条样式、滚动控制按钮、受控滚动模式、丰富的滚动事件系统以及视图交叉检测能力。

## 2. 需求点罗列

1.  **滚动基础能力**
    - 支持横向 (x)、竖向 (y)、双向 (both) 滚动控制。
    - 支持自动 (auto)、强制 (scroll)、隐藏 (hidden) 滚动条模式。
2.  **滚动条样式定制**
    - 内置样式：default (原生), thin (细), minimal (极简), rounded (圆角), overlay (悬浮/macOS 风格)。
    - 支持隐藏滚动条 (`hideScrollbar`) 但保留滚动功能。
    - 支持自定义滚动条类名。
3.  **滚动控制按钮**
    - 支持在容器内/外显示滚动箭头按钮。
    - 支持自定义按钮位置 (start, end, both)。
    - 支持自定义按钮样式 (default, circle, square, minimal, floating)。
    - **默认滚动距离为 100px**，支持自定义。
    - 边界自动隐藏按钮。
4.  **受控滚动模式**
    - **数值控制**: `scrollPosition` (scrollTop/Left)。
    - **元素控制**: `scrollToElement` (targetId, align, offset)。
    - **百分比控制**: `scrollPercentage`。
    - 优先级: 元素 > 百分比 > 数值。
5.  **吸附滚动 (Snap Scroll)**
    - 支持 CSS Scroll Snap (优先)。
    - 支持 `mandatory` (强制) 和 `proximity` (接近) 模式。
    - 支持对齐方式 (start, center, end)。
    - 支持自定义吸附点。
6.  **事件系统**
    - 生命周期: `onScrollStart`, `onScroll`, `onScrollEnd` (防抖)。
    - 边界检测: `onReachTop/Bottom/Left/Right`，支持 `reachThreshold`。
7.  **视图监听**
    - 集成 IntersectionObserver。
    - 支持进入/离开视口回调。
8.  **Ref API**
    - 暴露 `scrollTo`, `scrollToElement`, `scrollToTop/Bottom/Left/Right` 等命令式方法。

## 3. 组件 API

### Props 定义

```
// 见 types.ts (将在后续步骤详细定义)
// 核心包括: overflow, scrollbarStyle, scrollButtons, scrollPosition, scrollToElement,
// snapScroll, intersection, onScroll*, onReach* 等
```

## 4. 组件模块拆解

为了降低复杂度，将组件拆分为以下子模块：

1.  **PisellScrollView (主入口)**

    - 处理 Props 解析与默认值。
    - 维护核心 Ref (`containerRef`)。
    - 整合各个 Hooks 逻辑。
    - 渲染最终 DOM 结构。

2.  **Hooks (逻辑层)**

    - `useScrollState`: 处理滚动状态（scrollTop, scrollLeft, directions 等）。
    - `useScrollControl`: 处理受控滚动逻辑（响应 props 变化进行滚动）。
    - `useScrollEvents`: 处理原生 onScroll 事件，派发 Start/End/Reach 事件。
    - `useIntersection`: 封装 IntersectionObserver 逻辑。
    - `useSnapScroll`: 处理吸附滚动逻辑（主要生成 CSS 样式或处理 JS 降级）。
    - `useScrollButtons`: 处理滚动按钮的点击逻辑与显隐状态。

3.  **SubComponents (视图层)**
    - `ScrollbarStyle`: 负责注入自定义滚动条的 CSS (Style 标签或 CSS-in-JS 方案，或通过 class 控制)。
    - `ScrollButton`: 渲染单个滚动控制按钮。

## 5. 实现方案

### 5.1 滚动条样式实现

- 使用 Less 编写不同 `data-scrollbar-style` 属性对应的样式。
- 通过给容器添加 `data-scrollbar-style="thin"` 等属性来应用内置样式。
- 对于 `overlay` 样式，可能需要特殊处理（如 `overflow: overlay` 兼容性或模拟）。_注：暂优先使用 CSS 伪类方案定制 Webkit 滚动条。_

### 5.2 受控滚动与动画

- 使用 `element.scrollTo({ top, left, behavior })` 原生 API。
- `smooth` 滚动依赖原生支持，对于不支持的环境可考虑 polyfill (但本项目暂不引入 heavy polyfill，依赖现代浏览器)。
- `onScrollEnd` 使用 `lodash/debounce` 或手写 debounce 实现。

### 5.3 吸附滚动 (Snap Scroll)

- 优先映射到 CSS 属性:
  - `scroll-snap-type`: 根据 `direction` 和 `type` 生成。
  - `scroll-snap-align`: 需要透传给子元素，或者通过 `childSelector` 在父容器样式中定义（如果支持）。
  - _注意_: CSS Snap 需要子元素配合。对于 `snapTo: 'children'`，我们可以尝试通过 `childSelector` 给子元素加样式，或者文档引导用户给子元素加类名。

### 5.4 滚动按钮

- 按钮绝对定位 (inside) 或 弹性布局 (outside)。
- 点击按钮时，计算目标位置 `current + distance`，调用 `scrollTo`。

## 6. 扩展性

- 所有样式类名可通过 `className` 覆盖。
- 滚动按钮支持 `render` 属性自定义渲染。
- Ref 暴露底层 DOM 节点 (`getScrollContainer`) 供完全控制。

## 7. 依赖

- `react`
- `classnames`
- `resize-observer-polyfill` (可选，如果需要监听容器大小变化)
- IntersectionObserver API (原生)
