Component reference
从真实预览，到调用方法，再到核心 API。31 个组件与工具，7 组设计语言，组成一套可自由组合的编辑式界面。
Alpha / Beta 表示接口成熟度。此站展示开发中的 Web Components 版本；包发布后可使用全部公开入口。
01 · Foundations
模糊材质、表面与边框层级。
轻微模糊与柔和边界，让背景保留呼吸。
纯色表面承载阅读，信息自然形成层级。
<div class="flor-material is-glass border-all radius-large">
内容表面
</div>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
is-toolbar / is-glass / is-surface | class | 顶栏、玻璃与纯色材质。 |
border-* / radius-* | class | 边框 all / top / bottom；圆角 medium / large / full。 |
系统偏好 | CSS media queries | 降低透明度与增强对比度时使用清晰的实色表面。 |
02 · Layout
响应式逻辑内容宽度与分档水平留白。
<main class="flor-container is-reading has-gutters gutters-responsive">
阅读内容
</main>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
is-site / is-content / is-reading / is-full | class | 84rem、72rem、48rem 与不限制宽度。 |
has-gutters + gutters-* | class | compact / responsive / spacious 逻辑水平内边距。 |
--flor-container-max-inline-size | CSS variable | 实例级内容宽度覆盖。 |
可组合 tone、边框、圆角、间距与层级的内容表面。
<section class="flor-surface tone-subtle is-bordered radius-large pad-large is-elevated">
内容分组
</section>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
tone-default / tone-subtle / tone-transparent | class | 独立选择背景语义。 |
pad-* / radius-* | class | none / small / medium / large 间距与圆角。 |
is-bordered / is-elevated | class | 边框与轻量阴影。 |
原生富文本标题、说明与动作区域。
Editorial archive
PageHeader 只管理标题层级和动作区，不接管页面导航。
<script type="module">
import '@zaihuanews/florui/register';
</script>
<header class="flor-page-header is-compact"><p class="flor-page-eyebrow">Editorial archive</p><h4 class="flor-page-title">页面结构由小组件自由组合。</h4><p class="flor-page-description">PageHeader 只管理标题层级和动作区，不接管页面导航。</p><div class="flor-page-actions"><a class="flor-button is-primary is-medium" href="/about/">开始阅读</a></div></header>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
flor-page-header | header | 使用符合文档层级的真实标题。 |
flor-page-eyebrow / flor-page-title / flor-page-description / flor-page-actions | class | 眉题、富文本标题、说明与操作区。 |
is-compact / is-center | class | 紧凑间距与居中布局。 |
一条主稿与三张小卡循环的媒体型编辑网格。
<script type="module">
import '@zaihuanews/florui/register';
</script>
<div class="flor-editorial-grid" data-pattern="lead-three"><article class="flor-editorial-card"><a class="flor-editorial-media" href="/about/"><img src="/demo-morning.svg" alt="晨间自然抽象构图" loading="lazy" width="800" height="600"></a><div class="flor-editorial-copy"><p class="flor-editorial-meta">设计系统 · 3 分钟</p><h4 class="flor-editorial-title"><a href="/about/">用编辑节奏组织复杂内容</a></h4><p class="flor-editorial-excerpt">主稿保留更大的叙事空间，后续内容回到适合快速扫读的三列卡片。</p></div></article><article class="flor-editorial-card"><a class="flor-editorial-media" href="/about/"><img src="/demo-city.svg" alt="夜色城市抽象构图" loading="lazy" width="800" height="600"></a><div class="flor-editorial-copy"><p class="flor-editorial-meta">布局 · 4 分钟</p><h4 class="flor-editorial-title"><a href="/about/">让主次关系先于装饰被看见</a></h4></div></article><article class="flor-editorial-card"><a class="flor-editorial-media" href="/about/"><img src="/demo-studio.svg" alt="工作室纸张抽象构图" loading="lazy" width="800" height="600"></a><div class="flor-editorial-copy"><p class="flor-editorial-meta">组件 · 5 分钟</p><h4 class="flor-editorial-title"><a href="/about/">用原生 HTML 保留内容语义</a></h4></div></article><article class="flor-editorial-card"><a class="flor-editorial-media" href="/about/"><img src="/demo-morning.svg" alt="叶片与纸张" loading="lazy" width="800" height="600"></a><div class="flor-editorial-copy"><p class="flor-editorial-meta">视觉 · 6 分钟</p><h4 class="flor-editorial-title"><a href="/about/">在克制的界面中留下在花的温度</a></h4></div></article></div>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
flor-editorial-grid | class | 一条主稿与三张小卡循环的响应式网格。 |
flor-editorial-card / -media / -copy | class | 语义文章、媒体与文字区域。 |
data-pattern="lead-three" | attribute | 主稿与三张卡片的编辑节奏。 |
03 · Actions
主要、次要与幽灵操作按钮。
<button type="button" class="flor-button is-primary is-medium">
主要操作
</button>
<a class="flor-button is-secondary is-small" href="/about/">关于</a>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
is-primary / is-secondary / is-ghost | class | 主要、次要与幽灵操作。兼容 data-variant。 |
is-small / is-medium / is-large | class | 三档尺寸；默认 medium。 |
disabled / aria-busy | native attributes | 原生禁用和忙碌状态；加载按钮需同时禁用。 |
is-icon-only / is-full-width / is-loading | class | 图标按钮需有 aria-label；满宽与加载视觉状态。 |
04 · Data Display
响应式图片、文本 initials、自定义回退与在线状态。
FlorUI 编辑FlorUI 编辑<script type="module">
import '@zaihuanews/florui/register';
</script>
<div class="demo-row"><span class="flor-avatar is-small"><img class="flor-avatar-image" src="/demo-studio.svg" alt="FlorUI 编辑" width="44" height="44"></span><span class="flor-avatar is-medium"><span class="flor-avatar-fallback" aria-hidden="true">FL</span><span class="flor-visually-hidden">FlorUI 编辑</span><i class="flor-avatar-status is-online" role="img" aria-label="在线"></i></span><span class="flor-avatar is-large"><span class="flor-avatar-fallback" aria-hidden="true">FL</span><span class="flor-visually-hidden">FlorUI 编辑</span><i class="flor-avatar-status is-away" role="img" aria-label="离开"></i></span></div>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
flor-avatar + is-small / is-medium / is-large | class | 三档头像尺寸。 |
flor-avatar-image / flor-avatar-fallback | class | 原生 img 支持 srcset；无图时提供文本回退。 |
flor-avatar-status + is-online / is-away | class | 形状与颜色共同表达状态；提供可访问名称。 |
五种语义 tone 与两档尺寸的轻量状态标签。
<script type="module">
import '@zaihuanews/florui/register';
</script>
<div class="demo-row"><span class="flor-badge is-neutral is-medium"><span class="flor-badge-dot" aria-hidden="true"></span>草稿</span><span class="flor-badge is-success is-medium"><span class="flor-badge-dot" aria-hidden="true"></span>已发布</span><span class="flor-badge is-warning is-medium"><span class="flor-badge-dot" aria-hidden="true"></span>待审核</span><span class="flor-badge is-danger is-medium"><span class="flor-badge-dot" aria-hidden="true"></span>已撤回</span><span class="flor-badge is-info is-medium"><span class="flor-badge-dot" aria-hidden="true"></span>更新</span></div>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
is-neutral / is-success / is-warning / is-danger / is-info | class | 五种语义 tone；文本必须表达状态。 |
is-small / is-medium | class | 两档尺寸。 |
flor-badge-dot | span | 装饰圆点使用 aria-hidden。 |
富文本标题、链接属性与无碰撞视图过渡标识。
使用原生 View Transitions 时，每个过渡名称必须在当前页面唯一。
<h2 class="flor-article-transition-title" style="view-transition-name: article-1024">
<a href="/articles/1024/">文章标题</a>
</h2>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
flor-article-transition-title | heading class | 任意正确层级的原生标题，支持富文本。 |
view-transition-name | CSS property | 由应用提供唯一名称；支持时渐进增强。 |
原生 HTML | attributes | 使用语义元素、aria-*、data-* 和 CSS 变量组合；文本与链接在脚本加载前可用。 |
富文本标题与摘要、原生标题层级和媒体内容卡片。
组件只负责建立秩序，让标题、摘要和图像自然形成阅读节奏。把界面的声音放轻，内容才能被清楚地听见。
<script type="module">
import '@zaihuanews/florui/register';
</script>
<div class="reading-demo"><article class="flor-news-card">
<div class="flor-news-meta"><time datetime="2026-08-08T08:30:00+08:00">2026年8月8日 · 08:30</time><div class="flor-news-meta-actions"><span class="flor-news-id">#1024</span><flor-share-menu id="catalog-news-share" url="https://github.com/ZaihuaNews/FlorUI#readme" share-title="在信息密度与阅读节奏之间，找到恰当的留白"><button type="button" class="flor-button is-ghost is-small" data-flor-popover-trigger aria-controls="catalog-news-share-panel" aria-expanded="false">分享</button><div class="flor-share-panel" id="catalog-news-share-panel" data-flor-popover-panel popover="manual"><p>分享这篇内容</p><button type="button" class="flor-button is-secondary is-small" data-flor-share-copy>复制链接</button><button type="button" class="flor-button is-ghost is-small" data-flor-native-share>系统分享</button></div><span class="flor-visually-hidden" data-flor-share-status role="status"></span></flor-share-menu></div></div>
<h4 class="flor-news-title"><a class="flor-news-link" href="/about/">在信息密度与阅读节奏之间，找到恰当的留白</a></h4>
<p class="flor-news-excerpt">组件只负责建立秩序，让标题、摘要和图像自然形成阅读节奏。把界面的声音放轻，内容才能被清楚地听见。</p>
<div class="flor-news-media"><img class="news-cover" src="/demo-morning.svg" width="800" height="600" alt="晨光里的纸张与叶片" loading="lazy"></div>
</article></div>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
flor-news-meta / -title / -excerpt / -media | class | 日期、标题、摘要和媒体区域。 |
time[datetime] | HTML element | 提供带时区的有效日期；显示文本由应用格式化。 |
is-deleted | class | 弱化已删除内容的视觉状态。 |
原生 HTML | attributes | 使用语义元素、aria-*、data-* 和 CSS 变量组合；文本与链接在脚本加载前可用。 |
可访问的投票结果与 RTL 逻辑比例条。
Community poll
<script type="module">
import '@zaihuanews/florui/register';
</script>
<div class="poll-demo"><section class="flor-poll" aria-labelledby="catalog-poll-title"><div class="flor-poll-heading"><div><p class="flor-poll-eyebrow">Community poll</p><h4 id="catalog-poll-title">你最常使用哪一种阅读主题？</h4></div><span class="flor-poll-closed">已结束</span></div><div class="flor-poll-options"><div class="flor-poll-option"><span class="flor-poll-bar" style="inline-size:55.00000000000001%" aria-hidden="true"></span><div class="flor-poll-option-main"><strong>跟随系统</strong><span>55.0%</span></div></div><div class="flor-poll-option"><span class="flor-poll-bar" style="inline-size:28.984375%" aria-hidden="true"></span><div class="flor-poll-option-main"><strong>浅色主题</strong><span>29.0%</span></div></div><div class="flor-poll-option"><span class="flor-poll-bar" style="inline-size:16.015625%" aria-hidden="true"></span><div class="flor-poll-option-main"><strong>深色主题</strong><span>16.0%</span></div></div></div><footer>1,280 人参与 · 匿名投票 · 单选</footer></section></div>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
flor-poll | section | 用 aria-labelledby 关联投票问题。 |
flor-poll-bar | span | 使用逻辑 inline-size 设置比例，自动适配 RTL。 |
统计数据 | application data | 展示投票结果；业务应用负责校验非负票数、总人数与百分比分母。 |
原生 marker 与静态、链接、选择三种互斥条目。
选择一个条目，查看事件反馈。
<script type="module">
import '@zaihuanews/florui/register';
</script>
<flor-list-item><ul class="flor-list is-divided"><li class="flor-list-item"><button type="button" class="flor-list-item-action" data-flor-list-select data-value="settings"><span class="flor-list-copy"><strong>阅读偏好</strong><span class="flor-list-description">跟随系统，保留舒适阅读节奏</span></span><span class="flor-list-trailing" aria-hidden="true">↗</span></button></li><li class="flor-list-item"><button type="button" class="flor-list-item-action" data-flor-list-select data-value="docs"><span class="flor-list-copy"><strong>组件文档</strong><span class="flor-list-description">浏览完整预览与用法</span></span><span class="flor-list-trailing" aria-hidden="true">↗</span></button></li><li class="flor-list-item"><button type="button" class="flor-list-item-action" data-flor-list-select data-value="disabled" disabled><span class="flor-list-copy"><strong>暂不可用</strong><span class="flor-list-description">此选项处于禁用状态</span></span><span class="flor-list-trailing" aria-hidden="true">↗</span></button></li></ul><p class="component-note" data-demo-list-status role="status">选择一个条目，查看事件反馈。</p></flor-list-item>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
flor-list / flor-list-item / flor-list-item-action | class | 保留 ul / ol、li、button / a 的原生列表语义。 |
<flor-list-item> | custom element | 包裹选择区域，增强 data-flor-list-select 控件。 |
flor:list-select | CustomEvent<{ value: string }> | 触发选择；值来自 data-value，应用负责更新选中态。 |
一到四项原生图片或视频预览网格。
<script type="module">
import '@zaihuanews/florui/register';
</script>
<div class="media-demo"><div class="flor-media-grid has-3 is-rounded"><a class="flor-media-item is-featured" href="/demo-morning.svg"><img class="flor-media-image" src="/demo-morning.svg" alt="晨间自然抽象构图" width="800" height="600" loading="lazy"></a><a class="flor-media-item" href="/demo-city.svg"><img class="flor-media-image" src="/demo-city.svg" alt="夜色城市抽象构图" width="800" height="600" loading="lazy"></a><a class="flor-media-item" href="/demo-studio.svg"><img class="flor-media-image" src="/demo-studio.svg" alt="工作室纸张抽象构图" width="800" height="600" loading="lazy"></a></div></div>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
flor-media-grid + has-1 / has-2 / has-3 / has-4 | class | 一至四项响应式布局。 |
flor-media-image / flor-media-video | class | 原生图片与视频；视频使用 controls、字幕 track 和文字稿链接。 |
is-rounded | class | 启用统一圆角。 |
限量图片预览、附件、图片说明与模态灯箱。
import { renderMediaGallery } from '@zaihuanews/florui/html';
// 在服务端或构建时输出 HTML
const html = renderMediaGallery({
id: 'story-gallery',
images: [
{ src: '/morning.jpg', alt: '晨光里的纸张', caption: '晨间编辑台' },
{ src: '/city.jpg', alt: '夜色城市' },
],
visibleCount: 3,
});
// 浏览器入口：加载样式并注册交互
import '@zaihuanews/florui/register';| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
id / images | string / GalleryImageHTML[] | 唯一 ID 与图片数组；支持 src、fullSrc、alt、caption。 |
visibleCount | 1 | 2 | 3 | 4 = 3 | 限制预览数量，灯箱始终包含全部图片。 |
files | GalleryFileHTML[] | href、name、sizeLabel；附件始终可访问。 |
locale / label | 'zh-Hans' | 'en' / string | 语言与对话框名称。 |
键盘 | Escape / ← / → | 关闭并返回入口焦点，左右切换支持 RTL。 |
重点内容轮播、倒计时与切换控制。
可使用“暂停自动播放”或“继续自动播放”按钮控制自动播放。 键盘焦点进入后会保持暂停。 手动切换后会保持暂停。 指针悬停期间会临时暂停。 可左右滑动、使用方向键或上一条和下一条按钮浏览。
import { renderFeaturedCarousel } from '@zaihuanews/florui/html';
// 在服务端或构建时输出 HTML
const html = renderFeaturedCarousel({
id: 'home-featured',
items: stories,
autoplay: { delay: 5000 },
showAutoplayToggle: true,
pagination: 'bullets',
});
// 浏览器入口：加载样式并注册交互
import '@zaihuanews/florui/register';| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
renderFeaturedCarousel(props) | HTML renderer | 输出完整大图轨道、倒计时圆环与交互展开控件。 |
id / items | string / FeaturedItem[] | 页面内唯一 ID；内容支持图片、标题、分类、时间和阅读入口。 |
autoplay | false | FeaturedCarouselAutoplayOptions | 默认 6000ms；可设置延迟、悬停暂停和交互后的播放行为。 |
showAutoplayToggle | boolean, default false | 只有显式设为 true 才渲染暂停 / 继续按钮；本预览显式开启。 |
pagination | false | 'bullets' | 'fraction' | 'progressbar' | 默认关闭，可显示圆点、计数或进度条。 |
controlsVisibility | 'interaction' | 'always' | 默认在悬停、聚焦或暂停时展开控件；触屏常驻。 |
index / defaultIndex / loop / rewind | number / boolean | 初始索引与导航边界；loop 和 rewind 互斥。 |
locale / messages | FlorLocaleInput / partial messages | 支持地区语言标签、自定义语言包及文案覆盖。 |
class / class:list / style / data-* / aria-* | native attributes | 保留根属性透传；style 支持字符串和 CSS 属性对象。 |
renderItem(item, index) | (FeaturedItem, number) => string | 原版 scoped slot 的 HTML 回调形式，返回已转义的自定义内容。 |
getFeaturedCarouselApi(id) | controller | next、previous、goTo、pause、play、getIndex。 |
具名内容流区域、有效日期分组与可访问计数。
晨间简报：让重要内容先被看见。
设计笔记：让组件回归语义。
<script type="module">
import '@zaihuanews/florui/register';
</script>
<div class="flor-timeline-day-list" role="region" aria-label="按天分组的内容流"><section class="flor-timeline-day-section" aria-labelledby="day-demo-title"><header class="flor-day-heading"><h4 id="day-demo-title"><span class="flor-day-title">今天</span><time class="flor-day-detail" datetime="2026-08-08">2026年8月8日</time></h4><span class="flor-day-rule" aria-hidden="true"></span><span class="flor-day-count">02 条内容</span></header><div class="flor-day-items"><p>晨间简报：让重要内容先被看见。</p><p>设计笔记：让组件回归语义。</p></div></section></div>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
flor-timeline-day-list | region | 具名内容流区域。 |
flor-timeline-day-section | section | 每个日期分组关联自己的标题。 |
flor-day-heading / -detail / -count / -items | class | 分组标题、有效日期、可访问计数和内容区域。 |
05 · Navigation
短横线侧栏，悬停展开、点击固定，支持触屏和键盘。
<script type="module">
import '@zaihuanews/florui/register';
</script>
<div style="min-height:18rem"><flor-floating-rail><button type="button" data-flor-rail-toggle aria-label="Browse years"><span data-flor-rail-mark data-current aria-hidden="true"></span><span data-flor-rail-mark aria-hidden="true"></span><span data-flor-rail-mark aria-hidden="true"></span><span data-flor-rail-mark aria-hidden="true"></span><span data-flor-rail-mark aria-hidden="true"></span><span data-flor-rail-mark aria-hidden="true"></span><span data-flor-rail-mark aria-hidden="true"></span><span data-flor-rail-mark aria-hidden="true"></span><span data-flor-rail-mark aria-hidden="true"></span><span data-flor-rail-mark aria-hidden="true"></span><span data-flor-rail-mark aria-hidden="true"></span><span data-flor-rail-mark aria-hidden="true"></span></button><div id="catalog-floating-panel" data-flor-rail-panel><header style="display:flex;align-items:center;justify-content:space-between"><strong>选择年份</strong><button type="button" data-flor-rail-close aria-label="收起年份面板">←</button></header><nav aria-label="按年份浏览" style="display:grid"><a style="padding:.65rem" href="#floating-rail">2026</a><a style="padding:.65rem" href="#floating-rail">2025</a><a style="padding:.65rem" href="#floating-rail">2024</a><a style="padding:.65rem" href="#floating-rail">2023</a></nav></div></flor-floating-rail></div>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
data-flor-rail-toggle | button | 悬停或聚焦展开；点击固定，再次点击收起。 |
data-flor-rail-panel | element + unique id | 非模态内容面板；关闭时不可聚焦；不锁滚动。 |
data-flor-rail-mark / data-current | attribute | 短横线及当前项指示，由使用方更新。 |
data-flor-rail-close / Escape | button / key | 收起并保留可继续使用的键盘焦点。 |
side="end" | attribute | 从末端向内展开，支持 RTL。 |
--flor-rail-width / --flor-rail-max-height | CSS variable | 面板宽度和可用高度，页面负责定位与视口边距。 |
经校验、RTL 感知且支持键盘的日期轨道。
当前日期：2026-08-08
RTL · 方向键跟随阅读方向
当前日期：2026-08-08
<script type="module">
import '@zaihuanews/florui/register';
</script>
<flor-timeline-rail id="catalog-timeline"><nav class="flor-timeline" aria-label="按日期浏览"><ol><li><button type="button" class="flor-timeline-item" data-flor-timeline-action data-key="2026-08-08" aria-current="date" aria-label="今天，8月8日，12条内容"><span class="flor-timeline-marker" aria-hidden="true"></span><span class="flor-timeline-copy"><strong>今天</strong><time datetime="2026-08-08">8月8日</time></span><span class="flor-timeline-count">12</span></button></li><li><button type="button" class="flor-timeline-item" data-flor-timeline-action data-key="2026-08-07" aria-label="昨天，8月7日，8条内容"><span class="flor-timeline-marker" aria-hidden="true"></span><span class="flor-timeline-copy"><strong>昨天</strong><time datetime="2026-08-07">8月7日</time></span><span class="flor-timeline-count">8</span></button></li><li><button type="button" class="flor-timeline-item" data-flor-timeline-action data-key="2026-08-06" aria-label="周四，8月6日，17条内容"><span class="flor-timeline-marker" aria-hidden="true"></span><span class="flor-timeline-copy"><strong>周四</strong><time datetime="2026-08-06">8月6日</time></span><span class="flor-timeline-count">17</span></button></li><li><button type="button" class="flor-timeline-item" data-flor-timeline-action data-key="2026-08-05" disabled aria-label="周三，8月5日，0条内容"><span class="flor-timeline-marker" aria-hidden="true"></span><span class="flor-timeline-copy"><strong>周三</strong><time datetime="2026-08-05">8月5日</time></span><span class="flor-timeline-count">0</span></button></li><li><button type="button" class="flor-timeline-item" data-flor-timeline-action data-key="2026-08-04" aria-label="周二，8月4日，6条内容"><span class="flor-timeline-marker" aria-hidden="true"></span><span class="flor-timeline-copy"><strong>周二</strong><time datetime="2026-08-04">8月4日</time></span><span class="flor-timeline-count">6</span></button></li></ol></nav><p class="component-note" data-demo-timeline-status role="status">当前日期：2026-08-08</p></flor-timeline-rail><p class="control-label">RTL · 方向键跟随阅读方向</p><flor-timeline-rail id="catalog-timeline-rtl" dir="rtl"><nav class="flor-timeline" aria-label="按日期浏览"><ol><li><button type="button" class="flor-timeline-item" data-flor-timeline-action data-key="2026-08-08" aria-current="date" aria-label="今天，8月8日，12条内容"><span class="flor-timeline-marker" aria-hidden="true"></span><span class="flor-timeline-copy"><strong>今天</strong><time datetime="2026-08-08">8月8日</time></span><span class="flor-timeline-count">12</span></button></li><li><button type="button" class="flor-timeline-item" data-flor-timeline-action data-key="2026-08-07" aria-label="昨天，8月7日，8条内容"><span class="flor-timeline-marker" aria-hidden="true"></span><span class="flor-timeline-copy"><strong>昨天</strong><time datetime="2026-08-07">8月7日</time></span><span class="flor-timeline-count">8</span></button></li><li><button type="button" class="flor-timeline-item" data-flor-timeline-action data-key="2026-08-06" aria-label="周四，8月6日，17条内容"><span class="flor-timeline-marker" aria-hidden="true"></span><span class="flor-timeline-copy"><strong>周四</strong><time datetime="2026-08-06">8月6日</time></span><span class="flor-timeline-count">17</span></button></li><li><button type="button" class="flor-timeline-item" data-flor-timeline-action data-key="2026-08-05" disabled aria-label="周三，8月5日，0条内容"><span class="flor-timeline-marker" aria-hidden="true"></span><span class="flor-timeline-copy"><strong>周三</strong><time datetime="2026-08-05">8月5日</time></span><span class="flor-timeline-count">0</span></button></li><li><button type="button" class="flor-timeline-item" data-flor-timeline-action data-key="2026-08-04" aria-label="周二，8月4日，6条内容"><span class="flor-timeline-marker" aria-hidden="true"></span><span class="flor-timeline-copy"><strong>周二</strong><time datetime="2026-08-04">8月4日</time></span><span class="flor-timeline-count">6</span></button></li></ol></nav><p class="component-note" data-demo-timeline-status role="status">当前日期：2026-08-08</p></flor-timeline-rail>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
<flor-timeline-rail> | custom element | 日期轨道，可使用按钮或链接。 |
data-flor-timeline-action / data-key | attribute | 可聚焦操作与日期标识；disabled 控件跳过。 |
flor:timeline-select | CustomEvent<{ key: string }> | 通知应用切换日期；选中态由 aria-current="date" 表示。 |
dir="rtl" | native attribute | 左右方向键跟随书写方向，支持 Home / End。 |
具备 next 关系与惰性禁用态的流式分页入口。
<script type="module">
import '@zaihuanews/florui/register';
</script>
<div class="demo-column stream-next-demo"><a href="/components/#timeline-day" class="flor-stream-next" rel="next">阅读更早的内容 <span aria-hidden="true">↓</span></a><flor-stream-next scope="demo"><button type="button" class="flor-stream-next" data-flor-stream-next>演示加载更多 ↓</button><p class="component-note" data-demo-stream-status role="status"></p></flor-stream-next></div>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
a.flor-stream-next[rel="next"] | HTML | 真实分页链接，不依赖 JavaScript。 |
<flor-stream-next> | custom element | 按钮触发 flor:stream-next 事件，由应用加载下一批数据。 |
scope | string = 'news' | 事件中的业务范围。 |
逐帧更新且保持焦点可见的返回顶部操作。
向下滚动后，页面右下角出现返回顶部按钮。减少动态效果时直接跳转。
返回目录顶部 ↑<flor-back-to-top>
<button type="button" class="flor-button" aria-label="返回顶部">↑</button>
</flor-back-to-top>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
<flor-back-to-top> | custom element | 超过视口高度的 75% 后显示；聚焦时保持可见。 |
aria-label | native attribute | 按钮的可访问名称。 |
prefers-reduced-motion | system preference | 减少动态效果时立即滚动。 |
06 · Feedback
有限动效且可控制播报的骨架占位。
<script type="module">
import '@zaihuanews/florui/register';
</script>
<div class="flor-skeleton" role="status" aria-label="正在加载文章"><div class="flor-skeleton-meta" aria-hidden="true"></div><div class="flor-skeleton-title" aria-hidden="true"></div><div class="flor-skeleton-line" aria-hidden="true"></div><div class="flor-skeleton-line is-short" aria-hidden="true"></div><div class="flor-skeleton-media" aria-hidden="true"></div></div>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
flor-skeleton | class | 骨架容器，按需提供 status 与名称。 |
flor-skeleton-meta / -title / -line / -media | class | 组合元信息、标题、正文与媒体占位。 |
prefers-reduced-motion | system preference | 减少动态效果时停止闪动。 |
具备严格四态与 live region 语义的内容流反馈。
<script type="module">
import '@zaihuanews/florui/register';
</script>
<div class="demo-column"><div class="flor-feed-indicator is-loading" role="status" aria-label="正在加载内容"><div class="flor-feed-skeleton" aria-hidden="true"><span class="is-meta"></span><span class="is-title"></span><span></span><span class="is-short"></span></div></div><flor-feed-indicator scope="demo"><div class="flor-feed-indicator is-error" data-demo-feed><button type="button" data-flor-feed-retry>加载失败，点击重试</button><p data-demo-feed-status role="status"></p></div></flor-feed-indicator><div class="flor-feed-indicator is-complete" role="status">已读完全部内容</div></div>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
is-idle / is-loading / is-error / is-complete | class | 空闲、加载中、错误和完成四态。空闲时使用 hidden。 |
<flor-feed-indicator> / data-flor-feed-retry | custom element / attribute | 重试按钮触发 flor:feed-retry，应用处理请求与状态。 |
role="status" / aria-busy | native attributes | 播报状态并表达加载过程。 |
07 · Overlays
统一焦点、关闭与滚动锁定，并支持桌面内联、移动模态的响应式对话框。
<script type="module">
import '@zaihuanews/florui/register';
</script>
<flor-modal id="catalog-modal" dismiss-on-outside="true"><button class="flor-button is-primary is-medium" type="button" data-flor-modal-open>打开模态对话框</button><dialog data-flor-modal aria-labelledby="catalog-modal-title"><section class="demo-dialog-content"><p class="section-kicker">Shared overlay lifecycle</p><h2 id="catalog-modal-title">给重要决定一点空间</h2><p>Escape、外部点击、焦点返回和滚动锁定都由 Modal 统一处理。</p><button class="flor-button is-secondary is-medium" type="button" data-flor-modal-close>关闭</button></section></dialog></flor-modal>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
presentation | 'modal' | 'inline' | 'responsive' | 默认 modal；responsive 在窄屏模态、宽屏内联。 |
data-flor-modal-open / -close | attribute | 显式入口与关闭操作。 |
dismiss-on-outside / dismiss-on-escape | boolean string | 外部点击与 Escape 策略。 |
show(invoker?) / close(reason?) / open | methods / getter | 共享焦点、隔离和滚动生命周期。 |
经校验、焦点可恢复的原生优先定位浮层。
<script type="module">
import '@zaihuanews/florui/register';
</script>
<flor-popover><button class="flor-button is-secondary is-medium" type="button" data-flor-popover-trigger aria-controls="catalog-popover-panel" aria-expanded="false">打开快捷操作</button><div data-flor-popover-panel id="catalog-popover-panel" popover="manual" class="popover-menu"><a href="/about/">关于 FlorUI ↗</a><a href="https://github.com/ZaihuaNews/FlorUI">查看源代码 ↗</a><button type="button" data-flor-popover-close>关闭菜单</button></div></flor-popover>| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
<flor-popover> | custom element | 原生 Popover 顶层与碰撞感知定位。 |
data-flor-popover-trigger / -panel / -close | attribute | 入口、浮层和关闭操作。 |
placement | string | 例如 bottom-start，空间不足时自动调整。 |
dismiss-on-outside / dismiss-on-escape | boolean string | 统一关闭策略与焦点返回。 |
日期、月份与年份选择器。
按年份、月份或具体日期浏览内容。
已选日期：2026-08-08
import { renderDatePicker } from '@zaihuanews/florui/html';
// 在服务端或构建时输出 HTML
const html = renderDatePicker({
id: 'archive-date',
name: 'date',
value: '2026-08-08',
min: '2025-01-01',
max: '2027-12-31',
});
// 浏览器入口：加载样式并注册交互
import '@zaihuanews/florui/register';| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
id / name / value | string | 唯一 ID、表单字段名与 YYYY-MM-DD 日期。 |
min / max / today | YYYY-MM-DD | 日期边界与可选的参考日期；构建时校验有效性。 |
firstDayOfWeek | 0–6 | 周首日；默认中文周一，英文周日。 |
locale / label / description | strings | zh-Hans / en 以及可访问标题和说明。 |
disabled / required | boolean | 原生表单约束。 |
flor:date-select | CustomEvent<{ value: string }> | 确认日期时发出；取消不修改表单值。 |
可组合外部入口与结果插槽的搜索对话框面板。
import { renderSearchDialog } from '@zaihuanews/florui/html';
// 在服务端或构建时输出 HTML
const html = renderSearchDialog({
id: 'component-search',
presentation: 'responsive',
items: [{ label: 'DatePicker', href: '/components/#date-picker', keywords: '日历 日期' }],
});
// 浏览器入口：加载样式并注册交互
import '@zaihuanews/florui/register';| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
id / items | string / SearchItemHTML[] | 唯一 ID 与静态搜索索引；可提供说明、类别和关键词。 |
presentation | 'modal' | 'inline' | 'responsive' | 复用 Modal 的生命周期。 |
flor-search-field | class | 透明、紧凑、仅下划线的输入框。 |
flor-search-recommendation-heading | class | 带向上趋势图标的推荐标题。 |
flor:search-query-change | CustomEvent | 包含 query、empty、resultCount。 |
安全 URL、能力预检、系统分享与复制反馈。
支持复制链接；浏览器提供原生分享能力时启用系统分享。
import { renderShareMenu } from '@zaihuanews/florui/html';
// 在服务端或构建时输出 HTML
const html = renderShareMenu({ id: 'share', url: 'https://github.com/ZaihuaNews/FlorUI', title: 'FlorUI' });
// 浏览器入口：加载样式并注册交互
import '@zaihuanews/florui/register';| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
id / url / title | string | 唯一 ID、无凭据的绝对 HTTP(S) URL 与分享标题。 |
data-flor-share-copy / data-flor-native-share | attribute | 能力预检、异步去重与错误反馈。 |
data-flor-share-status | live region | 复制与分享结果的可访问反馈。 |
原生 disclosure、单选语义与跨实例同步的主题选择。
浅色、深色和跟随系统；与顶栏选择保持同步。
import { renderThemeMenu } from '@zaihuanews/florui/html';
// 在服务端或构建时输出 HTML
const html = renderThemeMenu({ id: 'theme-menu' });
// 浏览器入口：加载样式并注册交互
import '@zaihuanews/florui/register';| 接口 | 类型 / 默认值 | 说明 |
|---|---|---|
<flor-theme-menu> | custom element | 原生 details disclosure 与 radio 语义。 |
storage-key | string = 'flor-theme' | 本地存储键；同页实例与跨标签页同步。 |
default-theme | 'light' | 'dark' | 'system' | 无存储值时使用的主题。 |
createThemeBootstrapScript() | server helper | 从 /theme-script 导入，在 head 内尽早设置主题，避免闪烁。 |