FlorUIBeta

Component reference · 27 components · 7 categories

组件参考

每个条目均从 @zaihuanews/flor-ui 公共入口导入，并按 Preview、Usage、API 的顺序展示。示例代码可以直接复制到 Astro 项目。

01 · Foundations

基础与材质

全站共用的颜色 token、主题语义和材质层。组件不绑定业务模型。

Foundationsstable

Material

自适应浅深主题的材质层。Toolbar 用于顶栏，Glass 用于浮层，Surface 用于不透明或减少透明度场景。

Preview实时渲染
Toolbarblur + saturationFL
Glass浮层材质

保留背景色彩和文字对比度。

Surface实色材质

适合减少透明度与高对比度场景。

UsageAstro
---
import { Material } from '@zaihuanews/flor-ui';
---

<Material as="header" variant="toolbar" border="bottom">
  <nav>...</nav>
</Material>
API核心接口
Prop / EventTypeDefault说明
variant'toolbar' | 'glass' | 'surface''glass'材质类型。
border'none' | 'top' | 'bottom' | 'all''none'边框位置。
radius'none' | 'medium' | 'large' | 'full''none'圆角尺寸。
asHTML tag'div'输出的语义元素。

02 · Layout

布局

只负责宽度、间距和标题层级的结构组件，可以自由组合，不封装整站。

Layoutstable

Container

提供 site、content、reading 和 full 四档内容宽度，并可独立关闭水平 gutters。

Preview实时渲染
site · 84rem
content · 72rem
reading · 48rem
UsageAstro
---
import { Container } from '@zaihuanews/flor-ui';
---

<Container size="reading">
  <article>阅读内容</article>
</Container>
API核心接口
Prop / EventTypeDefault说明
size'site' | 'content' | 'reading' | 'full''content'最大内容宽度。
guttersbooleantrue是否保留响应式水平内边距。
as'div' | 'section' | 'article' | 'main''div'输出的语义元素。

Layoutstable

Surface

通用内容表面，统一背景、边框、圆角、内边距和轻量层级。

Preview实时渲染
Compact工具栏与状态。
Default常规内容分组。
Elevated重要内容层级。
UsageAstro
---
import { Surface } from '@zaihuanews/flor-ui';
---

<Surface padding="large" elevated>
  <h2>内容分组</h2>
</Surface>
API核心接口
Prop / EventTypeDefault说明
padding'none' | 'small' | 'medium' | 'large''medium'内容内边距密度。
elevatedbooleanfalse启用轻量阴影。
asHTML tag'div'输出的容器元素。

Layoutstable

PageHeader

标准页面标题结构，提供 eyebrow、标题、说明和 actions 插槽。

Preview实时渲染

Editorial archive

页面结构由小组件自由组合。

PageHeader 只管理标题层级和动作区，不接管页面导航。

UsageAstro
---
import { PageHeader, Button } from '@zaihuanews/flor-ui';
---

<PageHeader
  eyebrow="Archive"
  title="内容归档"
  description="按月份浏览历史内容。"
>
  <Button slot="actions">订阅</Button>
</PageHeader>
API核心接口
Prop / EventTypeDefault说明
titlestring—页面主标题。
eyebrowstring—标题上方的分类标识。
headingLevel1 | 21标题语义层级。
actionsnamed slot—页面级操作区域。

03 · Actions

操作

表达明确意图的交互控件，支持键盘、触摸和链接语义。

Actionsstable

Button

三种视觉权重、三种尺寸；提供 leading/trailing 插槽，并自动区分按钮与链接语义。

Preview实时渲染
UsageAstro
---
import { Button } from '@zaihuanews/flor-ui';
---

<Button variant="primary">主要操作</Button>
<Button variant="secondary" href="/archive/">浏览归档</Button>
<Button variant="ghost" disabled>不可用</Button>
API核心接口
Prop / EventTypeDefault说明
variant'primary' | 'secondary' | 'ghost''primary'操作视觉权重。
size'small' | 'medium' | 'large''medium'按钮尺寸。
hrefstring—传入后输出链接，否则输出 button。
disabledbooleanfalse禁用按钮或链接。

04 · Data Display

数据展示

呈现人物、状态、文章、列表、投票和媒体内容的组件。

Data Displaystable

Avatar

表示人物、作者或内容来源；没有图片时使用 initials 回退。

Preview实时渲染
UsageAstro
---
import { Avatar } from '@zaihuanews/flor-ui';
---

<Avatar initials="FL" status="online" />
API核心接口
Prop / EventTypeDefault说明
srcstring—头像图片地址。
initialsstring—无图片时显示的文字。
sizesmall | medium | largemedium头像尺寸。
statusonline | away—可选状态标记。

Data Displaystable

Badge

表示状态、分类和轻量计数，不承担主要操作。

Preview实时渲染
EditorialPublishedDraft
UsageAstro
---
import { Badge } from '@zaihuanews/flor-ui';
---

<Badge dot tone="success">Published</Badge>
API核心接口
Prop / EventTypeDefault说明
toneneutral | success | warningneutral状态色调。
dotbooleanfalse显示状态圆点。
default slotAstro slot—标签文字。

Data Displaystable

ArticleTransitionTitle

文章标题语义与 View Transition 名称集中管理，支持 source/target 配对。

Preview实时渲染

让标题在列表与详情之间自然衔接

UsageAstro
---
import { ArticleTransitionTitle } from '@zaihuanews/flor-ui';
---

<ArticleTransitionTitle
  title="文章标题"
  messageId={318}
  role="source"
  href="/article/318"
/>
API核心接口
Prop / EventTypeDefault说明
titlestring—标题内容。
role'source' | 'target' | 'none''none'跨页面过渡角色。
messageIdstring | number—生成稳定过渡名称的标识。
transitionNamestring—覆盖自动生成的 view-transition-name。

Data Displaystable

NewsCard

编辑式消息卡片，组合标题、摘要、时间、来源、动作和媒体插槽。

Preview实时渲染
已编辑26 条讨论#208
分享

转自 在花设计组

让内容成为界面的主角，而不是被界面淹没

舒展的行高、克制的色彩与明确的元信息层级，让长短不同的内容自然落入同一条时间线。

UsageAstro
---
import { NewsCard, ShareMenu } from '@zaihuanews/flor-ui';
---

<NewsCard
  title="让内容成为界面的主角"
  excerpt="清晰、响应式，并支持主题切换。"
  publishedAt="2026-08-08T09:20:00Z"
  id={208}
>
  <ShareMenu slot="actions" url={Astro.url.href} />
</NewsCard>
API核心接口
Prop / EventTypeDefault说明
titlestring—文章标题。
publishedAtstring | Date—发布时间。
excerptstring—摘要内容。
actions / medianamed slots—元信息动作与媒体区域。

Data Displaystable

PollCard

按票数计算比例，支持结束状态和紧凑密度。

Preview实时渲染

Community poll

内容产品里，你最重视哪一种体验？

已结束
  1. 清晰的阅读层级53.4%684 票
  2. 快速、稳定的加载30.5%391 票
  3. 自然的主题切换16%205 票
1,280 人参与投票匿名单选
UsageAstro
---
import { PollCard } from '@zaihuanews/flor-ui';
---

<PollCard
  question="你更关注什么？"
  options={[{ label: '排版', votes: 680 }]}
  totalVoterCount={1280}
/>
API核心接口
Prop / EventTypeDefault说明
questionstring—投票问题。
optionsPollOption[]—选项与票数。
totalVoterCountnumber—总投票人数。
closedbooleanfalse显示已结束状态。

Data Displaystable

List & ListItem

用于归档、专题、设置和选择列表；ListItem 可作为链接、选择按钮或静态行。

Preview实时渲染
UsageAstro
---
import { List, ListItem } from '@zaihuanews/flor-ui';
---

<List label="内容归档">
  <ListItem title="2026 年 8 月" count={128} href="/archive/2026-08" />
  <ListItem title="产品与设计" value="design" />
</List>
API核心接口
Prop / EventTypeDefault说明
List.variant'divided' | 'plain' | 'cards''divided'列表外观。
ListItem.hrefstring—传入后输出链接行。
ListItem.valuestring—传入后输出选择按钮。
event: flor:list-select{ value }—按钮行被选择时触发。

Data Displaystable

MediaGrid

一到四个视觉媒体项目自适应构图，多余项目在最后一格显示数量。

Preview实时渲染
晨间自然抽象构图晨间编辑台
夜色城市抽象构图城市夜读
工作室纸张抽象构图组件草图
叶片与纸张设计记录+1
UsageAstro
---
import { MediaGrid } from '@zaihuanews/flor-ui';
---

<MediaGrid items={[
  { src: '/photo.jpg', alt: '图片说明' },
  { src: '/video.mp4', type: 'video' },
]} />
API核心接口
Prop / EventTypeDefault说明
itemsMediaItem[]—图片或视频数据。
maxVisiblenumber4网格最大可见项目数。
roundedbooleantrue启用圆角裁切。

Data Displaystable

MediaGallery

组合图片、视频和附件，并内置键盘可操作的全屏灯箱。

Preview实时渲染
UsageAstro
---
import { MediaGallery } from '@zaihuanews/flor-ui';
---

<MediaGallery
  items={media}
  maxVisible={4}
  lightbox
/>
API核心接口
Prop / EventTypeDefault说明
itemsGalleryItem[]—图片、视频与附件数据。
lightboxbooleantrue为图片启用全屏预览。
maxVisiblenumber4首屏媒体数量。
groupIdstring—灯箱分组标识。

Data Displaystable

FeaturedCarousel

支持手势、前后按钮、自动播放、悬停/焦点暂停和减少动态效果偏好。

Preview实时渲染
UsageAstro
---
import { FeaturedCarousel } from '@zaihuanews/flor-ui';
---

<FeaturedCarousel
  items={stories}
  autoplay={6000}
/>
API核心接口
Prop / EventTypeDefault说明
itemsFeaturedItem[]—轮播内容。
autoplaynumber | false6000自动切换间隔；false 表示关闭。
labelstring'重点内容'辅助技术标签。

Data Displaystable

TimelineDayList & TimelineDaySection

内容流容器和日期分组标题，内部自由组合 NewsCard 等内容组件。

Preview实时渲染

今天

12
#318

内容页由日期分组与卡片自由组合

页面管理数据，组件管理语义、视觉与交互。

UsageAstro
---
import { TimelineDayList, TimelineDaySection, NewsCard } from '@zaihuanews/flor-ui';
---

<TimelineDayList>
  <TimelineDaySection day="2026-08-08" label="今天" count={12}>
    <NewsCard {...article} />
  </TimelineDaySection>
</TimelineDayList>
API核心接口
Prop / EventTypeDefault说明
TimelineDayList.busybooleanfalse设置内容流 aria-busy。
TimelineDaySection.daystring—YYYY-MM-DD 日期键。
TimelineDaySection.countnumber—本分组内容数。
default slotAstro slot—放置 NewsCard 或其他内容。

05 · Navigation

导航

帮助用户在日期、分页和长页面之间移动。

Navigationstable

TimelineRail

响应式日期轨道；每项既可直接链接，也可发出选择事件交给应用处理。

Preview实时渲染
UsageAstro
---
import { TimelineRail } from '@zaihuanews/flor-ui';
---

<TimelineRail
  items={days}
  current="2026-08-08"
  sticky
/>
API核心接口
Prop / EventTypeDefault说明
itemsTimelineItem[]—日期轨道数据。
currentstring—当前日期键。
stickybooleanfalse启用粘性定位。
event: flor:timeline-select{ key }—按钮模式选择日期时触发。

Navigationstable

StreamNextLink

内容流下一页入口，同时支持链接导航和事件驱动加载。

Preview实时渲染
浏览更早内容
UsageAstro
---
import { StreamNextLink } from '@zaihuanews/flor-ui';
---

<StreamNextLink href="/stream?cursor=next" label="浏览更早内容" />
API核心接口
Prop / EventTypeDefault说明
hrefstring—下一页地址；未传入时输出按钮。
loadingbooleanfalse显示加载状态。
event: flor:stream-next{ scope }—按钮模式被点击时触发。

Navigationstable

BackToTop

长页面达到阈值后显示固定返回顶部按钮；本页面右下角即为实时组件。

Preview实时渲染

向下滚动超过 480px 后，按钮固定显示在视口右下角。

UsageAstro
---
import { BackToTop } from '@zaihuanews/flor-ui';
---

<BackToTop threshold={480} smooth />
API核心接口
Prop / EventTypeDefault说明
thresholdnumber480显示按钮的滚动距离。
smoothbooleantrue允许时使用平滑滚动。
labelstring'返回顶部'无障碍标签。

06 · Feedback

反馈

表达加载、失败和结束状态，同时遵循减少动态效果偏好。

Feedbackstable

Skeleton

内容加载占位，可控制文本行数与媒体区域。

Preview实时渲染
UsageAstro
---
import { Skeleton } from '@zaihuanews/flor-ui';
---

<Skeleton lines={3} media />
API核心接口
Prop / EventTypeDefault说明
linesnumber3文本占位行数。
mediabooleanfalse显示媒体占位区。
labelstring'内容加载中'无障碍状态标签。

Feedbackstable

FeedLoadIndicator

内容流加载、错误重试和完成状态的统一反馈。

Preview实时渲染
UsageAstro
---
import { FeedLoadIndicator } from '@zaihuanews/flor-ui';
---

<FeedLoadIndicator state="loading" scope="news" />
API核心接口
Prop / EventTypeDefault说明
state'idle' | 'loading' | 'error' | 'complete''loading'反馈状态。
scopestring'news'内容流作用域。
event: flor:feed-retryCustomEvent—用户点击重试时触发。

07 · Overlays

浮层与选择器

菜单、日期、搜索、分享和主题等临时交互层，兼顾指针、键盘与移动端。

Overlaysstable

Popover

通用浮层；点击始终可用，桌面端 hover 自动打开由调用方显式开启。

Preview实时渲染
UsageAstro
---
import { Popover, Button } from '@zaihuanews/flor-ui';
---

<Popover
  label="快速入口"
  role="menu"
  openOnHover
  hoverOpenDelay={80}
>
  <Button slot="trigger">打开菜单</Button>
  <nav role="menu">...</nav>
</Popover>
API核心接口
Prop / EventTypeDefault说明
openOnHoverbooleanfalse桌面精细指针悬浮时自动打开。
placement'bottom-start' | 'bottom-end' | 'top-start' | 'top-end''bottom-end'桌面端首选位置。
modalOnMobilebooleantrue移动端改为底部弹层。
triggernamed slot—触发控件。

Overlaysstable

DatePicker

原生 Popover 日期选择器；点击年份或月份可进入 3×4 平铺选择，并支持范围、取消和表单提交。

Preview实时渲染
UsageAstro
---
import { DatePicker } from '@zaihuanews/flor-ui';
---

<DatePicker
  action="/archive/"
  value="2026-08-08"
  min="2026-01-01"
  max="2026-08-08"
/>
API核心接口
Prop / EventTypeDefault说明
valueYYYY-MM-DD—当前选择值。
min / maxYYYY-MM-DD—可选范围。
actionstring—提交日期的表单地址。
event: flor:date-select{ value }—日期被选择时触发。

Overlaysstable

SearchDialog

原生 dialog 搜索面板，支持 / 与 Ctrl/⌘+K 快捷键和自定义结果插槽。

Preview实时渲染
搜索
按 Esc 关闭
UsageAstro
---
import { SearchDialog } from '@zaihuanews/flor-ui';
---

<SearchDialog
  action="/search"
  queryName="q"
  placeholder="搜索内容"
/>
API核心接口
Prop / EventTypeDefault说明
actionstring'/search'搜索表单地址。
queryNamestring'q'查询参数名。
shortcutbooleantrue启用全局键盘快捷键。
resultsnamed slot—自定义搜索结果区域。

Overlaysstable

ShareMenu

提供系统分享、复制链接、复制 Markdown 和 Telegram 转发，并显示操作反馈。

Preview实时渲染
分享
UsageAstro
---
import { ShareMenu } from '@zaihuanews/flor-ui';
---

<ShareMenu
  url={Astro.url.href}
  title="文章标题"
  openOnHover
/>
API核心接口
Prop / EventTypeDefault说明
urlstring—分享目标地址。
titlestring—分享标题。
markdownstring—覆盖默认 Markdown 文本。
openOnHoverbooleanfalse桌面端 hover 自动打开。

Overlaysstable

ThemeMenu

管理跟随系统、浅色和深色三种主题偏好，并同步根元素状态。

Preview实时渲染
选择主题
UsageAstro
---
import { ThemeMenu } from '@zaihuanews/flor-ui';
---

<ThemeMenu
  storageKey="flor-theme"
  openOnHover
/>
API核心接口
Prop / EventTypeDefault说明
storageKeystringflor-theme主题偏好存储键。
openOnHoverbooleanfalse桌面端 hover 自动打开。
hoverOpenDelaynumber80hover 打开延迟，单位毫秒。
event: flor:theme-change{ choice, resolved }—主题变化时触发。