tango-horizon-cw

版本：1.0.3
支持：React 18.x/19.x & Next 14-16.x
作者：ClayW
创建时间：2026-02-05
更新时间：2026-04-29

简介

tango-horizon-cw 是一个用于 React / Next.js 的的横向滚动组件库，支持：

• 快速实现横向滚动布局
• 高度自定义配置

安装

npm install tango-horizon-cw

快速开始

import { Horizon } from "tango-horizon-cw";

export default function Demo() {
  return (
	<div style={{ width: "100vw", height: "100vh" }}>
	   <Horizon
		  topContent="HORIZON DEMO"
          bottomContent="SCROLL END"
		  middleHeight="100%"
	   />
	</div>
  );
}

组件会在自身容器内滚动，请给外层容器明确高度（如 100vh、70vh、600px）。

样式引入

通常构建工具会自动处理样式。如果你遇到样式未生效，可手动引入：

import "tango-horizon-cw/style.css";

使用范式

1) 顶部/底部传文本

<Horizon
  topContent="TOP TITLE AREA"
  bottomContent="BOTTOM TITLE AREA"
  damping={0.12}
  middleHeight="100%"
/>

2) 顶部/底部传组件（推荐业务场景）

const TopSection = () => <div style={{ padding: 24 }}>自定义顶部模块</div>;
const BottomSection = () => <div style={{ padding: 24 }}>自定义底部模块</div>;

<Horizon
  topContent={<TopSection />}
  bottomContent={<BottomSection />}
  topHeight={1200}
  bottomHeight={900}
  middleHeight="70vh"
/>

3) 自定义卡片内容

<Horizon
  boxCount={12}
  renderBox={(index) => <span>Card {index + 1}</span>}
/>

常用参数

• topContent / bottomContent: ReactNode，支持字符串、JSX、组件。
• topHeight / bottomHeight: 顶部与底部区域高度（number=px，string=CSS 长度）。
• middleHeight: 中间区域可视高度（推荐使用）；百分比基于 Horizon 容器高度，vh 基于浏览器视口。
• damping: 滚动阻尼系数（0~1，越小越柔和，越大越跟手）。
• stopThreshold: 动画停止阈值。
• wheelIdleDelay: 滚轮停止判定延迟（ms）。
• boxCount / boxWidth / boxHeight / boxGap: 横向卡片数量与尺寸间距。
• middleBackground / middleOverlay / middleBorderColor: 中间区域视觉样式。
• pageBackground / pageTextColor: 外层背景与文本色。
• boxBackground / boxShadow / boxTextColor: 卡片视觉样式。
• renderBox: 自定义卡片渲染函数，入参 index 从 0 开始。

TypeScript

组件库已导出类型：

import { Horizon } from "tango-horizon-cw";
import type { HorizonProps } from "tango-horizon-cw";

兼容性说明

• React：18.x / 19.x
• 适用于 React、Next.js（App Router / Pages Router）等常见前端工程