@panghuang/component-library

v0.3.1

Published

10 days ago

轻量 React + TypeScript 组件库

0High
0Medium
0Low

panghuang

react component-library ui toast typescript

@panghuang/component-library

基于 React + TypeScript + Vite 的 Figma 组件库。组件样式由 src/theme/tokens.ts 和 src/theme/tokens.css 统一驱动，CSS 变量前缀为 --pcl-*。

安装

npm install @panghuang/component-library

React / React DOM 为 peer dependency，需 >=19。使用组件时引入样式：

import { Button } from '@panghuang/component-library'
import '@panghuang/component-library/styles.css'

组件总览

当前已实现的组件（按 Figma 设计稿逐步添加）：

ActionBar：操作栏（底部菜单/按钮组合）
Album：相册卡片（支持 default 纵向卡片、card 横向卡片、list 列表行三种布局，覆盖照片/视频计数、标签、管理员标识）
Avatar：头像（支持图片/首字母/图标三种类型，圆形/圆角方形两种形状，五种尺寸，红点/数字角标）
Badge：徽标（支持红点/数字角标、两种尺寸、描边轮廓）
BadgeRibbon：角标缎带（支持标签形/斜角形、两种位置、两种尺寸）
BadgeStatus：渐变状态标签（支持 NEW/AI/会员/精修变体、三种形状、两种尺寸）
BottomPopup：底部弹窗（支持标题/副标题/角标/关闭按钮、多种高度、双按钮底部栏、Home Indicator）
Image：图片比例容器（支持多种固定宽高比、圆形裁剪、cover/contain 适应方式、圆角）
ImageStatus：图片状态（支持 normal/loading/error/select/uploading/number 七种变体、删除按钮、选择圆圈、编号角标）
ImageUpload：图片上传（支持方形/圆形、空态/填充态、删除按钮）
Mask：遮罩层（全屏覆盖，fixed 定位，支持 light/medium/heavy 三种透明度等级）
MediaCard：媒体卡片（固定 176px 宽，支持 image/video 变体，标题两行省略，底部标签插槽）
Grid：宫格组件（支持 list/card 变体，3/4/5 列，1/2 行，图片/图标两种模式，红点角标）
Checkbox：复选项
ColorPicker：颜色选择器（支持色盘选色、色相滑条、HEX 输入、复制）（支持方形/圆形、反白/常规、全选/半选、禁用态、左右 placement、list 列表模式）
DateTimePicker：日期时间选择器（年/月/日/时/分/秒多种模式，滚动选择）
DialogConfirmation：确认弹窗（支持 normal/withIcon/withPic 三种变体，双按钮、输入框、图标/图片展示）
EmptyState：空状态（支持 small/large 尺寸、图片、标题、描述和操作按钮）
Button：按钮
Carousel：轮播图（支持多图轮播、dots 指示器、计数标签、自动播放）
NavBar：导航栏（支持标题/副标题、返回按钮、右侧按钮/文字/图标）
NotificationBar：通知栏（支持 default/error/success/warning 四种状态，text/iconText/iconTextAction/iconTextClose/textAction/textClose/iconTextActionClose 七种结构，图标 + 文本 + 操作按钮 + 关闭按钮组合）
NotificationBarMember：会员通知栏（支持 gold / diamond 两种变体，渐变背景、提示文字 + 操作入口）
Radio：单选框（支持 list/card/horizontalCard 变体，dot/fillCircle/line 指示器，左右 placement）
Search：搜索输入框（支持方形/圆形、左图标、居中、取消按钮、清除按钮、禁用态）
Skeleton：骨架屏（支持 paragraph / text / cell / grid / imageAndText / image / avatar 七种变体，可开启闪烁动画）
Switch：开关（支持 normal/AI 变体、三种尺寸、受控/非受控、禁用态）
Tag：标签（支持 filled/light/outline/selected/selectable 变体、尺寸、形状、图标）
TagBase：展示标签（纯展示用，支持 solid/soft/outline 主题、矩形/圆形、五种尺寸、图标）
TagIdentity：身份标签（会员等级标识，支持 gold/platinum/diamond 三种等级，带渐变背景与图标）
TagMedal：勋章标签（支持 aiRetouch/photoLive/cloudEdit/videoLive 变体，active/disabled 状态，beginner/expert/master 等级）
TagTransmitter：传输状态标签（支持 online/uploading/pending_edit/displayed/not_uploaded 五种主题）
VideoPlayer：视频播放器（播放/暂停、进度条、全屏、封面图）
Textarea：多行输入框（支持 list/card 变体、字数统计、清除按钮、错误/禁用态）
TabBar：底部标签栏（支持图标、红点角标、受控/非受控）
Tabs：标签页（支持 textIcon / textDescription / iconText / capsule / roundedContained 五种变体）
Toast：轻提示（支持 default / success / warning / error / loading 五种类型，黑底白字，loading 为居中方形）

快速示例

import {
  ActionBar,
  Album,
  Avatar,
  Badge,
  BadgeRibbon,
  BadgeStatus,
  BottomPopup,
  Button,
  Carousel,
  Checkbox,
  DialogConfirmation,
  EmptyState,
  Image,
  ImageStatus,
  ImageUpload,
  Mask,
  MediaCard,
  Grid,
  NavBar,
  NotificationBar,
  NotificationBarMember,
  Radio,
  Search,
  Skeleton,
  Switch,
  TabBar,
  Tabs,
  Tag,
  TagBase,
  TagIdentity,
  TagMedal,
  TagTransmitter,
  Textarea,
  Toast,
} from '@panghuang/component-library'
import '@panghuang/component-library/styles.css'

export function Demo() {
  return (
    <>
      <ActionBar variant="buttonOnly" buttons={[{ text: '下一步' }]} />
      <ActionBar variant="menuOnly" menus={[{ label: '首页' }, { label: '作品' }]} />
      <ActionBar variant="menuButton" menus={[{ label: '首页' }]} buttons={[{ text: '操作' }]} />
      <Button theme="primary">Button</Button>
      <NavBar title="NavBar Title" subtitle="Subtitle" right="text" rightText="完成" />
      <NotificationBar text="默认通知" />
      <NotificationBar state="success" structure="iconText" text="操作成功" />
      <NotificationBar state="error" structure="iconTextActionClose" text="操作失败" actionText="重试" />
      <TabBar items={[{ label: '首页' }, { label: '消息', badge: true }]} />
      <Tabs items={[{ label: 'Tab A' }, { label: 'Tab B' }]} />
      <Textarea label="备注" placeholder="请输入" showCount maxLength={120} />
      <Toast type="success" toastText="操作成功" />
      <Toast type="loading" />
      <Skeleton variant="paragraph" />
      <Skeleton variant="imageAndText" animation />
    </>
  )
}

组件 API

ActionBar

操作栏组件，支持纯按钮、纯菜单、菜单+按钮混合三种布局模式。

<ActionBar variant="buttonOnly" buttons={[{ text: '下一步', onClick: handleNext }]} />
<ActionBar variant="menuOnly" menus={[{ icon: <SomeIcon />, label: '首页', badge: '会员' }, { icon: <SomeIcon />, label: '设置' }]} />
<ActionBar variant="menuButton" menus={[{ label: '首页' }]} buttons={[{ text: '操作', theme: 'primary' }]} />

常用 props：variant、menus、buttons、className。

类型取值：variant: 'buttonOnly' | 'menuOnly' | 'menuButton'。

menus 配置项：icon（ReactNode）、label（string）、badge（可选角标文字）、onClick。

buttons 配置项：text（string）、theme（可选，'primary' | 'default'，最后一项默认为 primary）、onClick。

Album

相册卡片组件，支持 default（纵向卡片）、card（横向卡片）、list（列表行）三种布局变体。适用于不同场景下的相册/图集展示。

<Album
  variant="default"
  title="三亚旅行"
  date="2024-12-01"
  location="海南三亚"
  imageCount={12}
  videoCount={3}
  imageSrc="https://example.com/cover.jpg"
/>
<Album
  variant="card"
  title="婚礼现场"
  date="2024-11-15"
  location="杭州"
  imageCount={48}
  imageSrc="https://example.com/wedding.jpg"
  tags={<Tag variant="filled" size="small">婚礼</Tag>}
/>
<Album
  variant="list"
  title="公司团建"
  date="2024-10-20"
  location="莫干山"
  imageCount={36}
  imageSrc="https://example.com/team.jpg"
  tags={<Tag variant="outline" size="small">活动</Tag>}
/>

常用 props：variant、title、date、location、imageCount、videoCount、imageSrc、tags、managerTag、className。

类型取值：variant: 'default' | 'card' | 'list'。

default：纵向卡片，固定宽 167px，图片 167x111px（4px 圆角），右上角更多操作按钮，左下角照片/视频计数遮罩。
card：横向卡片，固定宽 343px，白底 8px 圆角，内边距 10px 12px，左侧图片 121x82px（4px 圆角），右侧标题（16px Medium）及日期地点（10px），标签区域含管理员标签。
list：列表行，固定宽 375px，左侧图片 121x82px（4px 圆角），右侧标题（16px Medium）、日期地点（10px）、标签及"更多"链接按钮（12px #2970ff）。
managerTag：管理员标签文字，默认值为"管理员"（仅在 card variant 展示）。
tags：标签区域 slot，接受 ReactNode 类型（card/list variant 展示）。

Avatar

头像组件，支持图片、首字母、图标三种内容类型，圆形和圆角方形两种形状，五种尺寸，以及红点和数字角标。

<Avatar contentType="image" src="https://example.com/avatar.jpg" alt="用户头像" />
<Avatar contentType="initials" initials="AB" size="large" />
<Avatar contentType="icon" icon={<SomeIcon />} size="medium" />
<Avatar contentType="initials" initials="CD" badge badgeVariant="dot" />
<Avatar contentType="initials" initials="EF" badge badgeVariant="count" badgeContent={5} />
<Avatar contentType="initials" initials="GH" shape="square" size="extraSmall" />

常用 props：contentType、shape、size、src、alt、initials、icon、badge、badgeContent、badgeVariant、className。

尺寸对应：extraLarge=64px、large=48px、medium=40px、small=24px、extraSmall=16px。badge 为 true 时在右上角展示角标，badgeContent 超过 99 时自动显示为 99+。

Badge

徽标组件，支持红点（dot）和数字角标（count）两种变体、两种尺寸、可选白色描边轮廓。

<Badge variant="dot" />
<Badge variant="dot" size="large" outline />
<Badge variant="count" count={5} />
<Badge variant="count" size="large" count={99} outline />

常用 props：variant、size、outline、count、className。

类型取值：variant: 'dot' | 'count'，size: 'small' | 'large'。

count 数字超过 99 时自动显示为 99+。

BadgeRibbon

角标缎带组件，支持标签形（tag）和斜角形（diagonal）两种形状，左上/右上两种位置，small/medium 两种尺寸。使用父容器 position: relative 定位。

<BadgeRibbon />
<BadgeRibbon shape="diagonal" position="topRight" />
<BadgeRibbon shape="tag" size="small" position="topRight" />
<BadgeRibbon shape="diagonal" size="small" />

常用 props：shape、position、size、children、className。

类型取值：shape: 'tag' | 'diagonal'，position: 'topLeft' | 'topRight'，size: 'small' | 'medium'。

默认文字：tag 形状显示 "NEW"，diagonal 形状显示 "已过期"。可通过 children 自定义文字。

BadgeStatus

渐变状态标签组件，支持 NEW/AI/会员等级/精修等业务标签，rect/rounded/bubble 三种形状，small/medium 两种尺寸。

<BadgeStatus variant="new" />
<BadgeStatus variant="AI" shape="rounded" />
<BadgeStatus variant="AI" shape="bubble" />
<BadgeStatus variant="gold" size="small" />
<BadgeStatus variant="platinum" shape="rounded" />
<BadgeStatus variant="diamond" shape="rounded" size="small" />
<BadgeStatus variant="retouch" shape="rounded" />

常用 props：variant、shape、size、className。

各 variant 自动展示对应文字：new ("NEW")、AI ("AI")、gold/platinum/diamond ("会员")、retouch ("精修")。

BottomPopup

底部弹窗组件，支持标题/副标题/角标、关闭按钮、双按钮底部栏、Home Indicator 和多种高度。

<BottomPopup title="弹窗标题" subtitle="副标题" badge="会员" showClose showFooter showHomeIndicator>
  <p>自定义内容区域</p>
</BottomPopup>

<BottomPopup title="简洁弹窗" showClose onClose={() => {}}>
  <p>无底部按钮</p>
</BottomPopup>

<BottomPopup
  title="协议弹窗"
  height="agreement"
  showFooter
  primaryText="同意"
  secondaryText="拒绝"
  onPrimary={() => console.log('同意')}
  onSecondary={() => console.log('拒绝')}
>
  <p>协议内容...</p>
</BottomPopup>

常用 props：title、subtitle、badge、showClose、showFooter、showHomeIndicator、contentTone、height、primaryText、secondaryText、onPrimary、onSecondary、onClose、children、className。

title（必填）：弹窗标题，16px Medium，颜色 #1a1a1c。
subtitle（可选）：副标题，12px，位于标题下方。
badge（可选）：标题旁边的小角标文字，如"会员"。
showClose / onClose：控制右上角关闭按钮（28x28）的显示与回调。
showFooter / primaryText / secondaryText / onPrimary / onSecondary：底部双按钮区域，次按钮 128px 宽 #f0f2f5 背景，主按钮 128px 宽 #2970ff 背景白色文字，按钮高度 42px，圆角 8px。
showHomeIndicator：底部 Home Indicator 横条，34px 高度，居中黑色圆角条。
contentTone：内容区域背景色调，dark 为深色、light 为浅灰、text 为白色（默认）。
height：内容区域最大高度档位，compact=200px、standard=340px（默认）、large=480px、agreement=560px。
children：自定义内容，渲染在内容区。
组件固定宽度 375px，顶部左右圆角 16px，白色背景。

Image

图片比例容器组件，按指定宽高比展示图片，支持多种固定比例、圆形裁剪、cover/contain 适应方式、圆角和原生 img 属性透传。

<Image ratio="16:9" src="https://example.com/photo.jpg" alt="示例图片" />
<Image ratio="circle" src="https://example.com/avatar.jpg" alt="头像" />
<Image ratio="1:1" fit="contain" rounded src="https://example.com/photo.jpg" alt="图片" />
<Image ratio="auto" src="https://example.com/banner.jpg" alt="横幅" loading="lazy" />

常用 props：src、alt、ratio、fit、rounded、className，以及所有原生 img 属性（loading、crossOrigin、onLoad、onError 等）。

类型取值：ratio: '1:1' | '4:3' | '3:2' | '16:9' | '3:4' | '2:3' | '9:16' | '3:1' | 'auto' | 'circle'，fit: 'cover' | 'contain'。

ratio 为 circle 时自动设为 1:1 比例并裁剪为圆形（border-radius: 50%）。
ratio 为 auto 时不设固定比例，图片高度跟随自然宽高比。
rounded 为 true 时添加默认圆角（8px），与 circle 互斥。
fit 默认为 cover，容器 overflow hidden，图片居中裁剪。

ImageUpload

图片上传组件，支持方形/圆形、空态/填充态，填充态可展示图片并提供删除按钮。

<ImageUpload /> // 默认方形空态
<ImageUpload shape="circle" /> // 圆形空态
<ImageUpload state="filled" imageSrc="https://example.com/photo.jpg" onDelete={handleDelete} /> // 填充态

常用 props：shape、showText、state、imageSrc、onClick、onDelete、className。

类型取值：shape: 'square' | 'circle'，state: 'empty' | 'filled'。

Mask

遮罩层组件，全屏覆盖，使用 fixed 定位。支持 light / medium / heavy 三种透明度等级。

<Mask />                             // 默认 medium，rgba(0,0,0,0.6)
<Mask theme="light" />               // rgba(0,0,0,0.4)
<Mask theme="heavy" />               // rgba(0,0,0,0.8)
<Mask theme="medium" className="custom" />

常用 props：theme、className。

类型取值：theme: 'light' | 'medium' | 'heavy'，默认 'medium'。

light：浅遮罩（rgba(0,0,0,0.4)），适用于轻量遮罩场景。
medium：中等遮罩（rgba(0,0,0,0.6)），默认值，适用于常规弹窗背景。
heavy：深遮罩（rgba(0,0,0,0.8)），适用于需要强烈聚焦的场景。
组件使用 aria-hidden="true" 标记为装饰性元素，不影响无障碍访问。
遮罩覆盖层可通过在父容器设置 position: relative 和 overflow: hidden 来限制作用范围。

MediaCard

媒体卡片组件，固定宽度 176px，支持 image / video 两种变体，标题最多两行省略，底部标签区域可插入任意标签组件。

<MediaCard variant="image" title="图片标题" imageSrc="https://example.com/photo.jpg" />
<MediaCard variant="video" title="视频标题" imageSrc="https://example.com/video-cover.jpg" />
<MediaCard variant="image" title="带标签" imageSrc="https://example.com/photo.jpg" tags={<><Tag variant="filled">标签</Tag></>} />

常用 props：variant、title、imageSrc、tags、className。

类型取值：variant: 'image' | 'video'。

variant 为 image 时图片区域为 4:3 比例，为 video 时图片区域为 16:9 比例并在右上角显示播放按钮。
title 最多显示两行，超出部分用省略号截断。
tags 为 ReactNode 插槽，渲染在标题下方 54px 高度区域内。

Grid

宫格组件，支持 list（375px 宽）和 card（343px 宽 + 8px 圆角）两种变体，3/4/5 列、1/2 行，每个宫格支持图片/图标两种模式、三种尺寸和红点角标。

<Grid
  variant="list"
  columns={3}
  rows={1}
  items={[
    { variant: 'withImage', size: 'small', titleText: '相机', src: '/photo.jpg' },
    { variant: 'withImage', size: 'small', titleText: '风景', src: '/nature.jpg' },
    { variant: 'withImage', size: 'small', titleText: '人像', src: '/portrait.jpg' },
  ]}
/>
<Grid
  variant="card"
  columns={4}
  rows={2}
  items={[
    { variant: 'withImage', size: 'medium', titleText: '全部', src: '/all.jpg' },
    { variant: 'withIcon', size: 'large', titleText: '搜索', showBadge: true, icon: <SearchIcon /> },
  ]}
/>

常用 props：variant、columns、rows、items、className。

类型取值：variant: 'list' | 'card'，columns: 3 | 4 | 5，rows: 1 | 2。

items 配置项（GridItemConfig）：

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | variant | 'withImage' \| 'withIcon' | 'withImage' | 宫格项变体 | | size | 'small' \| 'medium' \| 'large' | 'medium' | 图片/图标尺寸 | | titleText | string | — | 标题文字 | | showBadge | boolean | false | 是否显示红点角标 | | src | string | — | 图片地址（withImage 模式） | | icon | ReactNode | — | 自定义图标内容（withIcon 模式） |

尺寸对应：

small：图片/图标 32x32px（4px 圆角），标题 12px
medium：图片/图标 40x40px（4px 圆角），标题 13px
large：图片/图标 48x48px（8px 圆角），标题 13px

GridItem 组件也可独立使用：

<GridItem variant="withIcon" size="large" titleText="消息" showBadge>
  <MessageIcon />
</GridItem>

ImageStatus

图片状态组件，展示图片的不同状态：正常/加载中/错误/可选择/上传中/编号，尺寸固定 112x112px。

<ImageStatus variant="normal" src="https://example.com/photo.jpg" showDelete onDelete={handleDelete} />
<ImageStatus variant="loading" />
<ImageStatus variant="error" />
<ImageStatus variant="selectLeft" src="https://example.com/photo.jpg" selected showDelete onDelete={handleDelete} />
<ImageStatus variant="selectRight" src="https://example.com/photo.jpg" />
<ImageStatus variant="uploading" src="https://example.com/photo.jpg" />
<ImageStatus variant="number" src="https://example.com/photo.jpg" count={3} />

常用 props：variant、showDelete、src、onDelete、selected、count、className、style。

normal：展示图片 + 右上角删除按钮（showDelete 为 true 时）。
loading：灰色背景 + 旋转加载图标 + "上传中..." 文字。
error：灰色背景 + 错误图标。
selectLeft / selectRight：展示图片 + 左下或右下选择圆圈（24px）+ 右上删除按钮。selected 为 true 时圆圈变蓝并打勾。
uploading：展示图片 + 半透明遮罩 + 加载图标 + "上传中..." 文字。
number：展示图片 + 右上角数字角标（24x24，半透明背景）。count 超过 99 显示 "99+"。

Button

按钮组件，支持实心、描边、文字按钮，以及不同主题、尺寸、圆角和图标布局。

<Button variant="solid" theme="primary" size="large">Button</Button>
<Button variant="outline" theme="danger" shape="round">Delete</Button>
<Button labelLayout="iconOnly" aria-label="更多" />

常用 props：variant、theme、size、shape、labelLayout、prefixIcon、suffixIcon、secondaryLabel、原生 button 属性。

Carousel

轮播图组件，支持多图轮播、dots 指示器、右上角计数标签和自动播放。支持受控/非受控两种模式。

<Carousel images={['/img1.jpg', '/img2.jpg', '/img3.jpg']} />
<Carousel images={images} size="16:9" variant="overlay" showCount />
<Carousel images={images} autoplay autoplayInterval={5000} />
<Carousel images={images} activeIndex={1} onChange={(i) => console.log(i)} />

常用 props：images、size、variant、showDots、showCount、autoplay、autoplayInterval、activeIndex、defaultActiveIndex、onChange、className。

类型取值：size: '4:1' | '16:9' | '4:3' | '3:4' | 'auto'，variant: 'outside' | 'overlay'。

size 默认 '16:9'，组件宽度固定 375px，高度按比例自适应（auto 为图片原始高度）。
variant 默认 'outside'：dots 在图片下方（padding 12px 24px），overlay 时 dots 覆盖在图片底部。
showDots 默认 true：单图模式下自动隐藏指示点。
showCount 默认 false：开启后在右上角显示当前序号（如 "1/5"），半透明毛玻璃背景。
autoplay / autoplayInterval：开启自动轮播，默认间隔 3000ms。
activeIndex（受控）/ defaultActiveIndex（非受控，默认 0）控制当前显示图片。
onChange(index)：切换图片时回调。

NavBar

移动端导航栏，支持标题、副标题、返回按钮、右侧按钮/文字/图标。

<NavBar title="NavBar Title" />
<NavBar title="Title" subtitle="Subtitle" right="text" rightText="完成" onRightClick={handleDone} />
<NavBar right="icon" rightIcon={<SomeIcon />} onBack={() => history.back()} />

常用 props：title、subtitle、border、right、rightText、buttonText、rightIcon、onBack、onRightClick。

类型取值：right: 'button' | 'text' | 'icon' | 'none'。

NotificationBar

内联通知栏组件，支持四种状态颜色和七种结构组合。可显示信息图标、通知文本、操作按钮和关闭按钮。

<NotificationBar text="默认通知" />
<NotificationBar state="default" structure="iconText" text="提示信息" />
<NotificationBar state="success" structure="iconText" text="操作成功" />
<NotificationBar state="error" structure="iconTextActionClose" text="操作失败" actionText="重试" onAction={handleRetry} onClose={handleClose} />
<NotificationBar state="warning" structure="textAction" text="请检查输入" actionText="查看" onAction={handleAction} />
<NotificationBar state="default" structure="textClose" text="可关闭通知" onClose={handleClose} />
<NotificationBar state="success" structure="iconTextActionClose" text="上传成功" actionText="查看详情" onAction={handleView} onClose={handleClose} />

常用 props：state、structure、text、actionText、onAction、onClose、className。

组件固定宽度 375px、高度 40px，内边距 0 12px，flex 水平居中对齐。各 state 背景色与图标/操作按钮颜色：

| state | 背景色 | 图标/按钮颜色 | |-------|--------|---------------| | default | #edf3ff | 蓝色 (#327aff) | | success | #f6ffed | 绿色 (#73d13d) | | error | #ffeeed | 红色 (#ff453a) | | warning | #fff5eb | 橙色 (#ffa24e) |

结构变体控制显示元素：

text：仅文本
iconText：图标 + 文本
iconTextAction：图标 + 文本 + 操作按钮
iconTextClose：图标 + 文本 + 关闭按钮
textAction：文本 + 操作按钮
textClose：文本 + 关闭按钮
iconTextActionClose：图标 + 文本 + 操作按钮 + 关闭按钮

NotificationBarMember

会员通知栏组件，支持 gold（黄金会员）/ diamond（钻石会员）两种变体，使用对应渐变背景，展示提示文字和右侧操作入口。

<NotificationBarMember variant="gold" />
<NotificationBarMember variant="diamond" />
<NotificationBarMember
  variant="gold"
  text="会员限时特惠，立享8折优惠"
  actionText="立即开通"
  onAction={() => console.log('开通')}
/>

常用 props：variant、text、actionText、onAction、className。

类型取值：variant: 'gold' | 'diamond'。

组件固定高度 36px，flex row 布局，padding 0 16px，overflow hidden。
variant="gold"：金色渐变背景（--pcl-gradient-member-gold-background），文字色 --pcl-text-member-gold。左侧默认文案「开通会员免费用，预计节省¥1360」，右侧默认文案「去开通」+ chevron_right 图标。
variant="diamond"：深色渐变背景（--pcl-gradient-member-diamond-background），文字色 --pcl-text-member-diamond。左侧默认文案「钻石/皇冠会员专享功能」，右侧默认文案「了解会员权益」+ chevron_right 图标。
text / actionText：可通过 props 覆盖左右两侧的默认文案。
onAction：点击右侧操作区域的回调，不传则无交互。
左侧文案区域 flex:1，超长省略号截断；右侧操作区域 flex-shrink:0，保持完整显示。

Tag

标签组件，支持 filled/light/outline/selected/selectable 五种变体，default/round 两种形状，三种尺寸和图标。

<Tag variant="filled">标签</Tag>
<Tag variant="selected" shape="round">标签</Tag>
<Tag variant="outline" size="large" showIcon>标签</Tag>
<Tag variant="selectable" onClick={() => {}}>可点击</Tag>
<Tag variant="selectable" disabled>禁用</Tag>

常用 props：variant、shape、size、children、showIcon、icon、disabled、onClick。

TagBase

展示标签组件（纯展示用，与可交互的 Tag 组件不同），支持 solid/soft/outline 三种主题、rectangle/round 两种形状、五种尺寸和可选图标。

<TagBase theme="solid">标签名称</TagBase>
<TagBase theme="soft" shape="round">标签名称</TagBase>
<TagBase theme="outline" size="large">荣誉标签</TagBase>
<TagBase theme="solid" size="extraLarge" showIcon>标签名称</TagBase>

常用 props：theme、shape、size、children、showIcon。

各尺寸默认文字：large 显示「荣誉标签」，其余尺寸显示「标签名称」。可通过 children 自定义。

TagIdentity

身份标签组件，用于展示会员等级标识，支持 gold（黄金会员）、platinum（铂金会员）、diamond（钻石会员）三种等级，每种等级使用对应的渐变背景和等级图标。

<TagIdentity variant="gold" />
<TagIdentity variant="platinum" />
<TagIdentity variant="diamond" />

常用 props：variant、className。

类型取值：variant: 'gold' | 'platinum' | 'diamond'。

组件固定尺寸 70x20px，使用 --pcl-gradient-member-*-background 渐变背景与 --pcl-text-member-* 文字颜色。gold / platinum 等级展示皇冠图标，diamond 等级展示钻石图标。

TagMedal

勋章标签组件，展示用户在 AI 修图 / 图片直播 / 云端剪辑 / 短视频直播等场景下的成就等级。

<TagMedal variant="aiRetouch" badgeStatus="active" level="master" />
<TagMedal variant="photoLive" badgeStatus="active" level="expert" />
<TagMedal variant="cloudEdit" badgeStatus="disabled" />
<TagMedal variant="videoLive" badgeStatus="active" level="beginner" />

常用 props：variant、badgeStatus、level、className。

各 variant 与 level 组合的文案：

| variant | beginner | expert | master | disabled | |---|---|---|---|---| | aiRetouch | AI修图能手 | AI修图专家 | AI修图大师 | AI修图勋章 | | photoLive | 图片直播能手 | 图片直播专家 | 图片直播大师 | 图片直播勋章 | | cloudEdit | 云端剪辑能手 | 云端剪辑专家 | 云端剪辑大师 | 云端剪辑勋章 | | videoLive | 短视频直播能手 | 短视频直播专家 | 短视频直播大师 | 短视频直播勋章 |

等级配色：beginner 边框与文字为青色 (#5cc0be)、expert 边框为蓝色 (#335bff) 文字为蓝色 (#4577ff)、master 边框为金色 (#cd8032) 文字为金色渐变。disabled 状态下边框与文字为灰色 (#ccc)。

TagTransmitter

传输状态标签组件，展示文件/照片的传输状态。

<TagTransmitter theme="online" />
<TagTransmitter theme="uploading" />
<TagTransmitter theme="pending_edit" />
<TagTransmitter theme="displayed" />
<TagTransmitter theme="not_uploaded" />

常用 props：theme、className。

类型取值：theme: 'online' | 'uploading' | 'pending_edit' | 'displayed' | 'not_uploaded'。

各 theme 自动展示对应文字：online/displayed ("已显示")、uploading ("上传中")、pending_edit ("待修图")、not_uploaded ("未上传")。

Checkbox

复选项组件，支持方形/圆形、反白/常规、全选/半选、禁用态和左右 placement。

<Checkbox label="Option" />
<Checkbox iconTheme="circleNormal" checked label="Option" />
<Checkbox indeterminate label="Option" />
<Checkbox iconTheme="circleInverse" disabled label="Disabled" />
<Checkbox placement="left" label="Left label" />

常用 props：iconTheme、checked、defaultChecked、indeterminate、disabled、label、placement、onChange。

DialogConfirmation

确认弹窗组件，支持 normal/withIcon/withPic 三种变体。normal 展示纯文本+双按钮，withIcon 在顶部展示成功/失败图标，withPic 在顶部或中间展示 16:9 图片。

<DialogConfirmation title="确认删除？" description="删除后无法恢复" />
<DialogConfirmation variant="withIcon" iconType="success" title="操作成功" description="文件已保存" />
<DialogConfirmation variant="withPic" imageSrc="https://example.com/img.jpg" imagePosition="top" title="标题" />
<DialogConfirmation variant="withPic" imageSrc="https://example.com/img.jpg" imagePosition="mid" title="标题" />
<DialogConfirmation showInput inputPlaceholder="请输入原因" onPrimary={handleConfirm} onSecondary={handleCancel} />

常用 props：variant、title、description、showIcon、iconType、imageSrc、imagePosition、showInput、inputPlaceholder、primaryText、secondaryText、onPrimary、onSecondary。

类型取值：variant: 'normal' | 'withIcon' | 'withPic'，iconType: 'success' | 'failed'，imagePosition: 'top' | 'mid'。

normal：标题（16px Medium）+ 描述（13px）+ 双按钮（8px 间距），白色卡片 286x 宽、12px 圆角。
withIcon：顶部 50x50 状态图标（成功绿色对勾/失败红色叉号）+ 标题描述 + 双按钮。showIcon 控制图标显隐。
withPic top：顶部 16:9 图片（与卡片上圆角对齐）+ 标题描述 + 双按钮。
withPic mid：标题描述 + 中间 16:9 图片（8px 圆角）+ 双按钮。
按钮：主按钮蓝色 (#2970ff) 白字、次按钮灰色 (#f0f2f5) 黑字，高度 38px，8px 圆角，flex 等宽。
输入框：238x38px，灰色底 (#f0f2f5)，8px 圆角，placeholder 文字 #c9cdd4。

EmptyState

空状态组件，用于无数据/无内容的占位展示，支持 small / large 两种尺寸变体，可选展示图片、标题、描述和操作按钮。

<EmptyState
  size="large"
  imageSrc="https://example.com/empty.png"
  title="暂无内容"
  description="当前还没有任何内容"
  showButton
  buttonText="立即创建"
  onButtonClick={() => {}}
/>
<EmptyState size="small" title="暂无消息" description="你还没有收到任何消息" />

常用 props：size、title、description、imageSrc、showButton、buttonText、onButtonClick、className。

类型取值：size: 'small' | 'large'，默认 'large'。

组件固定宽度 375px，padding 24px（上下）16px（左右），flex column 居中，gap 24px。
small 尺寸：图片 120x120px，标题 16px Medium（#2b2b2d），描述 13px（#999ca2）。
large 尺寸：图片 160x160px，标题/描述同上。
imageSrc：图片使用 object-fit: contain 适应容器。
showButton / buttonText / onButtonClick：控制底部操作按钮的显隐、文字和回调。按钮高度 42px，蓝色背景 (#2970ff) 白色文字，8px 圆角，右侧带 chevron_right 图标。
title / description 可选，不传时不渲染对应元素。

Radio

单选框组件，支持 list/card/horizontalCard 三种布局变体，dot/fillCircle/line 三种指示器样式，左右 placement。

<Radio options={[{ value: 'a', label: 'Option A' }, { value: 'b', label: 'Option B' }]} />
<Radio variant="card" indicator="fillCircle" options={[{ value: '1', label: '选项一' }, { value: '2', label: '选项二' }]} />
<Radio variant="horizontalCard" options={[{ value: 'x', label: 'Title', description: 'Description text' }]} />
<Radio placement="left" showIcon options={options} />

常用 props：variant、indicator、placement、options、value、defaultValue、showIcon、showDivider、onChange。

options 配置项：value（string）、label（string）、description（可选）、subLabel（可选）、badge（可选，角标文字）、disabled。

Search

搜索输入框，支持方形/圆形、左图标、居中对齐、取消按钮、清除按钮和禁用态。

<Search placeholder="搜索" />
<Search shape="round" defaultValue="keyword" action cancelText="取消" onCancel={() => {}} />
<Search clearable center disabled />

常用 props：shape、placeholder、value、defaultValue、leftIcon、action、cancelText、center、clearable、disabled、onChange、onCancel、onClear。

类型取值：shape: 'square' | 'round'。

Skeleton

骨架屏组件，支持 paragraph / text / cell / grid / imageAndText / image / avatar 七种变体，可开启闪烁动画。

<Skeleton variant="paragraph" />
<Skeleton variant="text" animation />
<Skeleton variant="cell" />
<Skeleton variant="grid" />
<Skeleton variant="imageAndText" />
<Skeleton variant="image" />
<Skeleton variant="avatar" animation />

常用 props：variant、animation、width、className。

paragraph：4 行骨架线（3 行满宽 + 1 行 240px），每行 16px 高，间距 16px，默认 343x112px。
text：3 行短骨架线，变幅宽度（60%、80%、40%），间距 12px，默认 343x56px。
cell：2 行骨架线（1 行满宽 + 1 行 60%），每行 20px 高，间距 8px，默认 343x48px。
grid：2x2 宫格，8px 间距，默认 343x74px。
imageAndText：两列布局，每列含圆角图片占位（9px 圆角，120px 高）+ 2 行文字占位，默认 343x220px。
image：72x72 方形占位，4px 圆角。
avatar：48x48 圆形占位。
animation：是否启用闪烁动画（shimmer 效果），默认 false。
width：自定义宽度（paragraph / text / cell / grid / imageAndText 变体生效），默认 '343px'。

Switch

开关组件，支持 normal / AI 两种变体、三种尺寸、受控与非受控模式、可选文字和图标。

<Switch />
<Switch checked disabled />
<Switch size="large" variant="AI" />
<Switch text defaultChecked />
<Switch icon checked />
<Switch variant="AI" icon defaultChecked />

常用 props：variant、size、checked、defaultChecked、disabled、text、icon、onChange、className。

类型取值：variant: 'normal' | 'AI'，size: 'large' | 'medium' | 'small'。

当 text=true 时，选中显示「开」，未选中显示「关」。当 icon=true 时，检选中状态在滑钮内展示图标（normal 为勾选图标，AI 为星形图标）。

TabBar

底部标签栏组件，支持图标、红点角标、受控/非受控模式。

<TabBar items={[{ icon: <SomeIcon />, label: '首页' }, { label: '消息', badge: true }]} />
<TabBar items={items} activeIndex={1} onChange={(i) => setActive(i)} />

常用 props：items、activeIndex、defaultActiveIndex、onChange。

items 配置项：icon（ReactNode）、label（string）、badge（boolean，红点角标）。

Tabs

标签页组件，支持五种变体：textIcon（经典下划线）、textDescription（标题+描述）、iconText（图标+文字）、capsule（胶囊）、roundedContained（含容器圆角）。

<Tabs items={[{ label: 'Tab A' }, { label: 'Tab B' }]} />
<Tabs variant="roundedContained" items={[{ label: '全部' }, { label: '待处理' }]} activeIndex={1} />
<Tabs variant="capsule" size="small" items={items} />

常用 props：variant、size、equalWidth、items、activeIndex、defaultActiveIndex、onChange。

items 配置项：label（string）、description（可选，textDescription 变体）、icon（可选 ReactNode）、badge（boolean，红点角标）。

Toast

轻提示组件，支持 default / success / warning / error / loading 五种类型。default 仅展示文字；success / warning / error 为图标+文字横向排列；loading 为 109x109 居中方形，上方旋转图标下方文字。

<Toast type="default" toastText="这是一条提示" />
<Toast type="success" toastText="操作成功" />
<Toast type="warning" toastText="请注意" />
<Toast type="error" toastText="操作失败" />
<Toast type="loading" />
<Toast type="loading" toastText="上传中..." />

常用 props：type、toastText、children、className。

类型取值：type: 'default' | 'success' | 'warning' | 'error' | 'loading'。

type 为 loading 时默认显示 "Loading" 文字，可通过 toastText 自定义。
children 用于替代默认文字区域的 ReactNode 插槽。
组件使用 role="status" 和 aria-live="polite" 以支持无障碍访问。

Textarea

多行输入框，支持 list/card 两种布局变体，normal/error/disabled/success 状态，字数统计和清除按钮。

<Textarea label="备注" placeholder="请输入" />
<Textarea variant="card" label="描述" defaultValue="内容" showCount maxLength={200} />
<Textarea label="反馈" state="error" helperText="请填写反馈内容" showCount maxLength={120} clearable />

常用 props：variant、label、placeholder、value、defaultValue、state、maxLength、showCount、countText、helperText、clearable、rows、onChange。

类型取值：variant: 'list' | 'card'，state: 'normal' | 'error' | 'disabled' | 'success'。

Theme Tokens

可以直接读取库内导出的 Figma 主题配置：

import { figmaTheme } from '@panghuang/component-library'

console.log(figmaTheme.colors.brand.blue[4]) // #2970FF
console.log(figmaTheme.components.button)

如需覆盖默认主题，可在宿主项目中重写 CSS 变量：

:root {
  --pcl-button-primary-solid-bg: #1d4ed8;
}

本地开发

npm install
npm run dev
npm run build
npm run lint

发布到 npm

这个组件库会提供给 Figma Make 使用，因此需要发布到 npm 官方源。

首次登录

首次发布前需先登录 npm。在终端执行以下命令，会拉起浏览器窗口完成身份验证（支持 Mac 通行密钥 / Touch ID）：

npm login --registry=https://registry.npmjs.org/

发布步骤

更新 package.json 中的 version 字段（如 0.3.0）
执行发布命令：

npm publish --access public --registry=https://registry.npmjs.org/

关于 2FA：如果 npm 账号启用了两步验证，推荐配置 Automation Token 避免每次输入 OTP：
访问 https://www.npmjs.com/settings/~/tokens
点击 Generate New Token → 选择 Automation 类型
将 token 写入 ~/.npmrc：//registry.npmjs.org/:_authToken=<你的token> 配置后发布无需每次输入验证码。

构建产物：

dist/index.js（ESM）
dist/index.cjs（CJS）
dist/index.d.ts
dist/component-library.css

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@panghuang/component-library

安装

组件总览

快速示例

组件 API

ActionBar

Album

Avatar

Badge

BadgeRibbon

BadgeStatus

BottomPopup

Image

ImageUpload

Mask

MediaCard

Grid

ImageStatus

Button

Carousel

NavBar

NotificationBar

NotificationBarMember

Tag

TagBase

TagIdentity

TagMedal

TagTransmitter

Checkbox

DialogConfirmation

EmptyState

Radio

Search

Skeleton

Switch

TabBar

Tabs

Toast

Textarea

Theme Tokens

本地开发

发布到 npm

首次登录

发布步骤

License