# ZhaoUI

> ZhaoUI 是一套不依赖框架的中文 UI 组件库：引入 zhaoui.css 与 zhaoui.js 两个文件即可使用，组件用 data-zh-* 属性声明，或调用全局对象 ZhaoUI。版本 0.1.0，共 60 个组件，支持亮暗、B/C 端、密度等主题。

## 关键事实

- 浏览器：Chrome / Edge 111+、Safari 16.4+、Firefox 113+（Chromium、Firefox、WebKit 三个引擎自动测试）
- 无依赖：不需要 jQuery、Vue 或 React；JavaScript 压缩后 gzip 约 55.7 KB，CSS 约 28.3 KB
- 无障碍：键盘操作、ARIA 角色、减少动态效果、Windows 高对比度（后者只在 Chromium 模拟下验证）
- 完整文档合集（给模型一次读完）：[llms-full.txt](https://ui.352m.com/llms-full.txt)

## 文档

- [快速开始](https://ui.352m.com/guide/quickstart.html)
- [主题](https://ui.352m.com/guide/theme.html)
- [图标](https://ui.352m.com/guide/icons.html)
- [样式类](https://ui.352m.com/guide/styles.html)
- [公共类（可选）](https://ui.352m.com/guide/utilities.html)

## 组件

- [锚点目录](https://ui.352m.com/components/anchor.html)：长页面的“本页目录”：一列指向页内各节的链接，滚动时自动标出当前所在的一节，点击平滑滚动过去。适合文档、设置页的右侧。
- [头像](https://ui.352m.com/components/avatar.html)：图片头像；图片缺失或加载失败时，用姓名首字（中文取第一个字，英文取首字母）和由姓名决定的颜色代替。
- [返回顶部](https://ui.352m.com/components/backtop.html)：滚动超过一段距离后出现的圆形按钮，点击平滑回到顶部；系统开启“减少动态效果”时直接跳回。
- [徽标](https://ui.352m.com/components/badge.html)：挂在头像、图标、按钮角上的数字、红点或文字徽标。数量为 0 时自动隐藏，超过上限显示 99+。
- [面包屑](https://ui.352m.com/components/breadcrumb.html)：纯样式组件：不需要 JS，写好标记即可。页面层级路径。当前页用 aria-current="page"；手机宽度只保留最后两级。
- [按钮组](https://ui.352m.com/components/btngroup.html)：纯样式组件：不需要 JS，写好标记即可。把几个相关按钮连成一组：共用边框，只有两端有圆角。常用来做视图切换或分段筛选；选中项用 is-active 或 aria-pressed="true"。
- [内嵌日历](https://ui.352m.com/components/calendar.html)：一直显示在页面里的月历（不是弹出的选择器）：点选一天、键盘切换、月年快速跳转，可禁用日期，还能给某些天加小圆点或热力底色（如日程、签到）。
- [卡片](https://ui.352m.com/components/card.html)：纯样式组件：不需要 JS，写好标记即可。带边框、圆角、阴影的内容容器。可只放一个标题和内容，也可用 zh-card--flush 配头部、正文、底部、封面图；整张卡片可点时用 zh-card--hover。
- [轮播](https://ui.352m.com/components/carousel.html)：一组幻灯片：左右箭头、圆点、键盘方向键、触屏滑动（基于 CSS 滚动吸附）；可自动播放。
- [级联选择](https://ui.352m.com/components/cascader.html)：多级联动选择（省市区、分类树）。数据写成页面里的嵌套列表，或用 ZhaoUI.cascader 传一棵树。支持搜索、悬停展开，窄屏自动变成逐级下钻。
- [图表](https://ui.352m.com/components/chart.html)：基础图表：折线、面积、柱状、环形、迷你趋势。颜色用主题固定的 8 色分类色板（随亮暗主题变化），只有一条纵轴（不做双纵轴），图例可点击隐藏某个系列，鼠标悬停或键盘左右键查看每个点的数值，并附带给读屏用的数据表。需要堆叠、散点、地图、动画等复杂图表时请用专门的图表库。
- [代码块](https://ui.352m.com/components/code.html)：纯样式组件：不需要 JS，写好标记即可。展示代码：zh-code 用在 <pre> 上（等宽字体，过宽时横向滚动），zh-code-inline 用在行内的 <code> 上。不含语法高亮。
- [折叠面板](https://ui.352m.com/components/collapse.html)：手风琴或多开的折叠列表。展开状态用 .is-open 表示，库负责切换、无障碍属性和键盘。
- [命令面板](https://ui.352m.com/components/command.html)：按快捷键或点按钮弹出的搜索框：输入几个字就能跳到某个页面或执行某个操作。支持模糊匹配（含关键词）、按分组显示、最近使用、键盘上下选择、回车执行。命令用一个数组描述。
- [评论](https://ui.352m.com/components/comment.html)：纯样式组件：不需要 JS，写好标记即可。评论列表项：头像、昵称、时间、正文、操作，回复缩进显示。头像用 zh-avatar。
- [日期选择](https://ui.352m.com/components/date.html)：点击输入框弹出日历，也可以直接键入日期。支持最早 / 最晚日期、禁用周末、禁用指定日期，键盘完整可用。声明式写一个空 <div data-zh-date>，命令式用 ZhaoUI.datePicker。周从周一开始。
- [日期范围选择](https://ui.352m.com/components/daterange.html)：两个输入框加一个双月日历，选开始和结束两次点击；带「近 7 天 / 近 30 天 / 本月 / 上月」快捷项。窄屏变为单月。
- [日期时间选择](https://ui.352m.com/components/datetime.html)：左边日历、右边时间列的组合面板，一次选定日期和时间，点「确定」提交。窄屏上下排列。
- [描述列表](https://ui.352m.com/components/descr.html)：纯样式组件：不需要 JS。用 <dl> 展示一组「名称：值」，如订单详情、项目信息。有两种外观：plain（无框）、bordered（带框表格式）；列数 1 到 3 可选，窄屏自动降列。
- [模态框与抽屉](https://ui.352m.com/components/dialog.html)：模态框基于原生 <dialog>，抽屉是右侧滑出的面板。用 data-zh-open / data-zh-close 声明即可，也可用 ZhaoUI.open / close / dialog 调用。
- [下拉菜单](https://ui.352m.com/components/dropdown.html)：点击按钮弹出菜单。菜单内容写在页面里的一个隐藏列表中，选中后触发 zh:select。一个菜单可以被多个按钮共用（比如表格每一行一个「操作」按钮，都指向同一个 #menu）。
- [警告条、空状态、骨架屏](https://ui.352m.com/components/feedback.html)：纯样式组件：不需要 JS，写好标记即可。页面内的提示条（信息、成功、警告、危险）、没有数据时的空状态、加载中的骨架屏。会自动消失的轻提示用 ZhaoUI.message。
- [页脚](https://ui.352m.com/components/footer.html)：纯样式组件：不需要 JS，写好标记即可。页面底部：版权文字在一侧，链接在另一侧，窄屏自动换行。
- [表单控件与字段](https://ui.352m.com/components/form.html)：纯样式组件：不需要 JS，写好标记即可。字段（标签、控件、提示）、文本输入、下拉、多行文本、复选框、单选、开关。带搜索、清除、校验等行为的输入框见「输入框」「下拉选择」等组件。
- [图片](https://ui.352m.com/components/image.html)：纯样式组件：不需要 JS，写好标记即可。图片的响应式与外观：zh-img 让图片不超出容器、保持比例；--rounded 圆角，--circle 正圆（头像），--thumb 带边框的缩略图。配图说明用 <figure> 加 zh-figure。
- [行内编辑](https://ui.352m.com/components/inline-edit.html)：点击文字原地变成输入框，Enter 或失焦保存，Esc 取消。空内容不会被保存。
- [输入框](https://ui.352m.com/components/input.html)：带前置图标、清除按钮、密码显示开关、搜索快捷键的文本输入。结构是 .zh-inp 包着 .zh-inp-box 和原生 input，按钮按需添加。
- [键位](https://ui.352m.com/components/kbd.html)：纯样式组件：不需要 JS。用 <kbd class="zh-kbd"> 显示键盘按键，如快捷键提示。
- [布局](https://ui.352m.com/components/layout.html)：纯样式组件：不需要 JS，写好标记即可。响应式栅格（桌面 12 列、平板 8 列、手机 4 列）、自适应卡片网格、主内容加侧栏、垂直堆叠、水平排列、两端对齐。间距来自 Token，不要自己写死。
- [列表](https://ui.352m.com/components/list.html)：纯样式组件：不需要 JS，写好标记即可。一行一项的列表：主文字、说明、右侧附加内容（标签、时间、按钮），行之间有分隔线。zh-list--bordered 加外框，zh-list--hover 悬停高亮，zh-list--plain 是带圆点的普通列表。
- [营销页区块](https://ui.352m.com/components/marketing.html)：可选的 zhaoui-marketing.css：搭一个落地页用的整块样式，页宽与区块间距、hero（左文右卡）、区块标题、特性卡、价格卡、品牌渐变横幅、带品牌色发光的主按钮，以及可选的渐变文字、数据条、极光光斑和玻璃标签。极光、渐变文字、玻璃标签只是装饰，默认不用：普通页面直接用 zh-hero 的浅色渐变；只有深色、发布会式的首屏才考虑加 zh-aurora（并在该区块写 data-mode="dark"）。下面的示例为了演示全部类才把它们放在一起，不是推荐的搭配。全部读主题变量，跟着品牌色、亮暗和 B/C 端走。需要额外引入 zhaoui-marketing.css，放在 zhaoui.css 之后。
- [滚动公告](https://ui.352m.com/components/marquee.html)：一行向左滚动的公告文字，首尾无缝衔接；悬停或聚焦时暂停；系统开启“减少动态效果”时不滚动，改为可横向拖动。
- [遮罩条](https://ui.352m.com/components/maskbar.html)：纯样式组件：不需要 JS，写好标记即可。盖在图片或卡片底部的说明条：渐变深色底配白字，在任何图片上都能读。zh-maskbar--solid 是纯色条，zh-maskbar--hover 平时隐藏、悬停或聚焦时出现。
- [配置式菜单与右键菜单](https://ui.352m.com/components/menu.html)：用一个数组描述菜单，再挂到按钮或区域上：分组标题、分隔线、图标、快捷键提示、复选项、单选项、危险项、禁用项、多级子菜单。同一份数组也能做右键菜单。固定写在 HTML 里的简单菜单用「下拉菜单」（data-zh-dropdown）更省事。
- [消息提示](https://ui.352m.com/components/message.html)：顶部居中的轻量提示，自动消失。只提供方法调用，不需要写标记。
- [顶部导航条](https://ui.352m.com/components/navbar.html)：网站或应用顶部的导航：左侧标志，中间链接（当前页下方有滑动的下划线），右侧放搜索、通知、头像等你自己的内容。有嵌套 <ul> 的链接自动成为下拉菜单；宽度小于 768px 时链接收进汉堡按钮打开的侧滑抽屉。
- [数字步进器](https://ui.352m.com/components/number.html)：带加减按钮的数字输入，支持范围、步长、小数位数，键盘可操作，按住按钮连续加减。
- [验证码输入](https://ui.352m.com/components/otp.html)：分格的一次性验证码输入。只写一个空的容器，格子由库生成；支持粘贴、退格回退、方向键。校验由你来做，用 ZhaoUI.otp 把结果显示出来。
- [页头](https://ui.352m.com/components/pageheader.html)：纯样式组件：不需要 JS。后台内容区顶部的标题区：返回按钮、标题、说明、操作按钮和一行元信息。
- [分页](https://ui.352m.com/components/pager.html)：分页器，页码数量恒定不跳动，支持每页条数、跳转框、简洁模式、多种尺寸。声明式写 data-zh-pager，或用 ZhaoUI.pager 创建。库不管数据，只管页码，翻页后你自己取数据。
- [气泡确认](https://ui.352m.com/components/popconfirm.html)：挂在触发按钮旁的小确认框，用于轻量的二次确认（删除一行、下线一篇）。比模态框轻；破坏性很大的操作仍用确认对话框。
- [气泡卡片](https://ui.352m.com/components/popover.html)：点击（或悬停、聚焦）触发的浮层，里面可以放任意内容：说明、小表单、操作列表。内容写在页面里的一个隐藏元素中，库会复制进浮层。
- [进度条](https://ui.352m.com/components/progress.html)：线性进度条，支持标签位置、状态、分步、缓冲、目标线和不确定进度。只写一个带 data-* 的空元素，内容由库生成。
- [评分](https://ui.352m.com/components/rating.html)：星形或心形评分，支持半星、只读、清除、文字标签。交互版本是一组 radio，键盘与读屏都可用。
- [结果页](https://ui.352m.com/components/result.html)：纯样式组件：不需要 JS。操作完成、失败或页面不存在时的反馈块：图标（或大号错误码）、标题、说明、补充信息、操作按钮，居中排列。用 data-tone 选语气。
- [环形进度](https://ui.352m.com/components/ring.html)：圆环、仪表盘（270°）、半圆三种形状的进度，中心显示百分比或自定义内容。
- [下拉选择](https://ui.352m.com/components/select.html)：增强原生 <select>：单选、多选、搜索、分组、清除、选项描述，选中值同步回原生 select 并触发原生 change，表单提交、name、required 照常工作。也可用 ZhaoUI.select 命令式创建，支持远程搜索和自动完成。
- [侧边菜单](https://ui.352m.com/components/side.html)：后台常见的左侧导航：多级分组、当前页标记、可折叠成 64px 图标栏，支持键盘（方向键、Home/End、字母）。用嵌套的 <ul> 写，库会补齐 ARIA 树结构。
- [滑块](https://ui.352m.com/components/slider.html)：单值或范围滑块，支持刻度、步进、竖直、颜色分档，键盘与指针都可操作。只写一个带 data-* 的空元素。
- [加载中](https://ui.352m.com/components/spinner.html)：纯样式组件：不需要 JS，写好标记即可。一个转动的圆圈，表示正在加载。三个大小：sm、默认、lg。系统开启“减少动态效果”时圈会静止，所以旁边请同时写“加载中”之类的文字。
- [步骤条](https://ui.352m.com/components/steps.html)：表示多步流程走到了哪一步：数字或图标标记、连接线、当前步骤、出错步骤。你只写每步的标题，库生成标记并按当前步骤算出完成、进行中、未开始。容器放不下时自动改成纵向。
- [表格](https://ui.352m.com/components/table.html)：带圆角边框的数据表：表头底色、行悬停高亮、数字列右对齐。窄屏（≤ 767px）默认变成卡片列表，也可以改成横向滚动。样式部分不需要 JS；加 data-zh-table 后可以点表头排序、用复选框选择行。分页用 data-zh-pager。
- [标签页](https://ui.352m.com/components/tabs.html)：横向或纵向标签页。标签用 aria-controls 关联面板，面板的显示隐藏由库处理。也可以当「分段开关」用：几个标签指向同一个面板，在 zh:tab-change 里换内容。
- [标签](https://ui.352m.com/components/tag.html)：标签：普通的彩色标签、可关闭的标签，以及可选中的标签（单选组、多选）。普通标签只要 class="zh-tag" 加颜色类，不需要 zh-tag--x；zh-tag--x 才表示可关闭或可选。新增标签的输入框不在库里，按你的业务自己做。
- [多行文本](https://ui.352m.com/components/textarea.html)：随内容增高的文本域，带字数统计。硬上限用 maxlength，软上限 data-soft-max 允许继续输入但提示超出。
- [时间选择](https://ui.352m.com/components/time.html)：时、分（可选秒）三列滚动选择，也可以直接键入。分钟可按步长取整。
- [时间线](https://ui.352m.com/components/timeline.html)：按时间顺序展示事件：左侧一条轨道和圆点，右侧是标题、时间、说明。圆点颜色表示状态（primary、success、warning、danger、info），进行中的项显示转圈。可以带头像、引用、附件，以及点击展开的详情。
- [文字提示](https://ui.352m.com/components/tooltip.html)：悬停或键盘聚焦时显示的小气泡，自动避让屏幕边缘，带箭头。适合解释图标按钮或被禁用的按钮。不用 JS 的简易版见「样式类」里的 zh-tip。
- [树](https://ui.352m.com/components/tree.html)：可展开的层级列表：文件目录、组织架构、分类。写一个嵌套的 <ul>，库渲染成带展开箭头的行；可选复选框（父级根据子级显示全选、半选、未选）、单选高亮和完整的键盘操作。
- [文件上传](https://ui.352m.com/components/upload.html)：拖拽或点击选择文件，带文件列表、进度条、类型与大小校验、数量限制，失败可重试，上传中可取消。可以用 data-action 直接 POST 到接口，也可以用自己的函数上传；两者都不给时只收集文件，由你在提交表单时取。只有列表模式；头像上传和图片卡片墙没有做。

## 使用规则

- 引入方式：<link rel="stylesheet" href="zhaoui.css"> 与 <script src="zhaoui.js"></script>（放在 </body> 前，不加 defer）
- 主题用 <html> 上的 data-audience / data-mode / data-density / data-trend / data-brand / data-style 控制
- 颜色与间距只用 CSS 变量 var(--zh-*)，不写死；文字色用带 text 的一档
- 图标写 <i data-i="名称"></i>，禁止 emoji；只有图标的按钮必须有 aria-label
- 一个区域只放一个主按钮 (zh-btn primary)
- 确认框用 ZhaoUI.dialog，提示用 ZhaoUI.message，不要用 confirm / alert

## 尚未提供

堆叠或散点等复杂图表、上传的头像与图片卡片模式、树的拖拽排序与按需加载、导航里的超大菜单：库里没有；不要编造类名，用主题变量自己写。