飞立（plui）上手

飞立（plui）是一个自研的响应式 CSS 框架，风格是白底黑线的极简设计。当前版本 0.3.0。

1. 引入文件

<link rel="stylesheet" href="dist/css/plui.css">
<!-- 生产环境用压缩版 -->
<link rel="stylesheet" href="dist/css/plui.min.css">

<!-- 交互组件需要这两个脚本，顺序不能换 -->
<script src="src/common.js"></script>
<script src="src/plui.js"></script>
文件作用
dist/css/plui.css当前版本的展开版，保留注释，可读性好
dist/css/plui.min.css当前版本的压缩版
dist/css/plui-0.3.0.css带版本号的展开版，便于锁定版本
dist/css/plui-0.3.0.min.css带版本号的压缩版
src/common.js用户上传的 sx 函数库，框架唯一的第三方 JS 依赖
src/plui.js框架自己的轻量交互层，挂在 window.plui

不用 JS 也能用：栅格、排版、间距、按钮、表单、表格、卡片等纯样式组件不需要任何脚本；只有标签页、折叠面板、下拉菜单、模态框、可关闭提示框、轮播、吐司、弹出框需要 plui.js。

plui.js 会在 DOM 就绪后自动初始化一次。也可以手动调用：

window.plui.init();   // 重新扫描并初始化（幂等）
window.plui.version;   // '0.3.0'

2. 容器与栅格

<div class="plui-container">
  <div class="plui-row g-3">
    <div class="plui-col-12 plui-col-md-6">左</div>
    <div class="plui-col-12 plui-col-md-6">右</div>
  </div>
</div>

规则：

3. 断点前缀

前缀媒体查询用途
（无前缀）< 576pxxs 基线，所有屏宽都生效
sm≥ 576px大屏手机
md≥ 768px平板
lg≥ 992px小屏笔记本
xl≥ 1200px桌面
xxl≥ 1400px超宽屏

栅格与组件沿用 Bootstrap 的中缀写法（.plui-col-lg-4），工具类走 Tailwind 路线，断点段放最前面（.plui-md:mt-6）。两套写法各管一层，不混用：

<!-- 栅格（Bootstrap 路线） -->
<div class="plui-col-12 plui-col-lg-4"></div>

<!-- 间距：md 起上边距 1.5rem -->
<p class="plui-mt-3 plui-md:mt-6"></p>

<!-- 显隐：md 以下显示 -->
<div class="plui-block plui-md:hidden"></div>

<!-- 弹性布局：lg 起横向排列 -->
<div class="plui-flex-col plui-lg:flex-row"></div>

<!-- 文本：lg 起居中 -->
<h2 class="plui-text-center plui-lg:text-left"></h2>

工具类的命名规则与完整清单见 UTILITIES.md：断点段一律放在最前面，因为 Tailwind 的取值里本来就有 sm / md / lg / xl（字号 sm、圆角 md），断点写在中缀位置会与档位撞名。

断点取值写在 src/css/base/tokens.css 的 --plui-breakpoint-* 里，同时在 src/css/responsive/ 每个媒体查询上方的注释里标明对应关系。CSS 自定义属性不能用在媒体查询条件中，所以媒体查询里写的是字面量。

4. 常用组件

<!-- 按钮 -->
<button class="plui-btn">实心</button>
<button class="plui-btn plui-btn-outline">描边</button>
<button class="plui-btn plui-btn-ghost">幽灵</button>
<button class="plui-btn" disabled>禁用</button>

<!-- 表单 -->
<label class="plui-form-label" for="a">名称</label>
<input class="plui-form-control" id="a" type="text">
<select class="plui-form-control plui-form-select"><option>一</option></select>

<!-- 提示框 -->
<div class="plui-alert">提示内容</div>
<div class="plui-alert plui-alert-dismissible">
  可关闭
  <button class="plui-alert-close" data-plui-dismiss="alert">×</button>
</div>

<!-- 卡片 -->
<div class="plui-card">
  <div class="plui-card-header"><h3 class="plui-card-title">标题</h3></div>
  <div class="plui-card-body">内容</div>
  <div class="plui-card-footer">底部</div>
</div>

<!-- 表格 -->
<table class="plui-table plui-table-bordered">
  <thead><tr><th>列</th></tr></thead>
  <tbody><tr><td>行</td></tr></tbody>
</table>

各组件的完整类名清单与最小示例见 COMPONENTS.md。

5. 需要 JS 的组件

标签页：

<ul class="plui-nav-tabs">
  <li><button class="plui-nav-tabs-link active" data-plui-toggle="tab" data-plui-target="#p1">一</button></li>
  <li><button class="plui-nav-tabs-link" data-plui-toggle="tab" data-plui-target="#p2">二</button></li>
</ul>
<div class="plui-tab-content">
  <div class="plui-tab-pane active" id="p1">面板一</div>
  <div class="plui-tab-pane" id="p2">面板二</div>
</div>

折叠面板：

<div class="plui-accordion" data-plui-accordion="single">
  <div class="plui-accordion-item">
    <h3>
      <button class="plui-accordion-button" data-plui-toggle="collapse" data-plui-target="#c1">
        标题 <span class="plui-accordion-indicator">▸</span>
      </button>
    </h3>
    <div class="plui-accordion-collapse" id="c1">
      <div class="plui-accordion-body">内容</div>
    </div>
  </div>
</div>

容器上加 data-plui-accordion="single" 表示同一组内互斥展开；不加则可以同时展开多个。

下拉菜单：

<div class="plui-dropdown">
  <button class="plui-btn plui-btn-outline plui-dropdown-toggle" data-plui-toggle="dropdown">菜单</button>
  <ul class="plui-dropdown-menu">
    <li><button class="plui-dropdown-item">项一</button></li>
  </ul>
</div>

模态框：

<button class="plui-btn" data-plui-toggle="modal" data-plui-target="#m1">打开</button>

<div class="plui-modal" id="m1">
  <div class="plui-modal-dialog">
    <div class="plui-modal-content">
      <div class="plui-modal-header">
        <h2 class="plui-modal-title">标题</h2>
        <button class="plui-modal-close" data-plui-dismiss="modal">×</button>
      </div>
      <div class="plui-modal-body">内容</div>
      <div class="plui-modal-footer">
        <button class="plui-btn plui-btn-outline" data-plui-dismiss="modal">取消</button>
        <button class="plui-btn" data-plui-dismiss="modal">确定</button>
      </div>
    </div>
  </div>
</div>

模态框支持 Esc 关闭、点击右上角关闭、点击底部按钮关闭；关闭后焦点会回到打开它的元素。

6. 样式约定

项目取值
主色 / 正文#000
背景#fff
次级文字#666，更弱的用 #999
边框1px 纯黑实线
圆角0
阴影不使用
渐变不使用
彩色不使用，只有黑白灰

间距档位 0 / 1 / 2 / 3 / 4 / 5 对应 0 / 0.25rem / 0.5rem / 1rem / 1.5rem / 3rem，由 --plui-spacing-* 令牌统一控制。

7. 自己构建

源码在 src/css/，构建在本地 Node 环境完成，站点上不装任何工具链：

node build/build.mjs        # 拼接 + 压缩 + 语法自检
node build/gen-utilities.mjs  # 重新生成重复度高的工具类源码（一般不需要跑）

产物固定为四个文件：plui-0.1.0.css、plui-0.1.0.min.css，以及别名 plui.css、plui.min.css。

8. 已知限制

7. 暗色模式

<html data-plui-theme="dark">

或者什么都不写，跟随系统的 prefers-color-scheme。暗色只改语义层令牌，组件与工具类自动跟随；原始色阶（bg-gray-100 这类）不跟随，需要深色适配请用语义类（bg-soft、text-muted、text-faint）。

8. 按需裁剪构建

只需要部分组件时，跑一次裁剪构建：

node build/mini.mjs --pages examples/index.html,index.html

产出 dist/css/plui-mini.css 与 .min.css，只保留页面真正用到的类（组件按族保留，工具类精确匹配）。当前示例页裁剪后约 63 KB，比全量压缩版小约 85%。裁剪版只适合单页或已知页面集合的站点，常规站点仍用 plui.css。

9. JS API 快速上手

var modal = plui.Modal.getOrCreateInstance('#my-modal');
modal.show();
document.addEventListener('shown.bs.plui', function (e) { console.log('显示完成', e.target); });

完整接口见 JS-API.md。

本页由 build/build-docs.mjs 从同名 Markdown 生成，请修改 .md 后重新生成，不要手工编辑本文件。