• 文档
• 教程

本指南以开源仓库 app-ideas 中 Border-Radius-Previewer.md 这一 Tier-1 入门级项目文档为核心，讲解如何从零实现一个「圆角预览器」：通过控件实时调整元素的 border-radius 值、即时查看形状变化，并将最终生成的 CSS 声明一键复制到剪贴板。读完本文，你将完整掌握 border-radius 四值与八值（斜杠）语法、基于滑块/数值输入驱动的实时预览方案、navigator.clipboard剪贴板 API 的用法及其兼容回退，并得到一个可直接运行、可继续扩展的参考实现。

项目定位：一个入门级的 CSS 可视化调试工具

根据仓库根目录 README.md 中的分档说明，Tier-1（Beginner）面向处于学习早期、以构建用户界面应用为主要目标的开发者。该档位下的 Border Radius Previewer 正是这样一个典型的界面工具型项目：README 对它的概括是"Preview how CSS3 border-radius values affect an element"（预览 CSS3 border-radius 值如何影响元素外观）。

项目文档给出的目标非常清晰：

The border-radius property can have multiple values changed. Preview how the shape looks while changing these values.

即：border-radius 属性可以同时承载多个值，本应用的价值在于让开发者一边改变这些值、一边直观看到元素形状的实时变化。它非常适合作为学习 CSS 基础属性、DOM 事件绑定、style对象读写以及浏览器剪贴板 API 的第一批练手项目。

值得注意的是，本仓库是一个「应用创意集合」而非成品代码库：除项目规格文档外，仓库中并没有该应用的现成实现源码。因此，本文中所有实现代码均是依据 Border-Radius-Previewer.md 的用户故事逐条推导出的参考实现方案，你可以把它当作需求到代码的映射范例，再按自己的技术栈重写（原生 JavaScript、Vue、React 均可）。

需求拆解：User Stories 与验收标准

原文档以「User Stories（用户故事）+ Bonus features（加分特性）」的形式定义需求，这也是仓库中每个项目文档的统一格式（可参照 Example Guide.md 的模板约定）。Border Radius Previewer 的需求清单如下：

下面先补齐完成这些需求所必需的核心知识点，再给出逐条落地的参考实现。

核心知识一：CSS border-radius 的取值语法

要写出正确的预览器和正确的 CSS 导出文本，必须先吃透 border-radius 的语法规则。它是 CSS 背景与边框（CSS Backgrounds and Borders）规范的一部分，支持 1～4 个简写值，也支持用斜杠/分隔的椭圆半径写法。

1～4 值简写：顺时针遍历四角

border-radius 的简写值按「左上 → 右上 → 右下 → 左下」的顺时针顺序作用于四个角：

/* 1 个值：四角相同 */ border-radius: 10px; /* 2 个值：第一个作用于左上/右下，第二个作用于右上/左下（对角配对） */ border-radius: 10px 20px; /* 3 个值：依次作用于左上、右上/左下、右下 */ border-radius: 10px 20px 30px; /* 4 个值：依次作用于左上、右上、右下、左下 */ border-radius: 10px 20px 30px 40px;

这正是原文档 US-2 要求「可以改变应用到盒子上的 4 个 border-radius 值（左上、右上、左下、右下）」的语法依据：导出 CSS 时，四个值按该顺序拼成一行四值声明即可。

斜杠语法：8 个值构建复杂形状

border-radius 还允许在斜杠前写一组水平半径、斜杠后写一组垂直半径，从而生成非对称的椭圆角：

border-radius: 10px 20px 30px 40px / 40px 30px 20px 10px;

• 斜杠左侧 4 个值：每个角的水平半径（沿 X 轴方向）；
• 斜杠右侧 4 个值：每个角的垂直半径（沿 Y 轴方向）；
• 当水平半径 ≠ 垂直半径时，角呈现椭圆形而非四分之一正圆。

这就是原文档 Bonus 特性「改变 border-radius 的全部 8 个可能值以创建复杂形状」的落地方式：把 4 个水平半径和 4 个垂直半径共 8 个自由度全部暴露给用户，即可拼出类似花瓣、气泡、Squircle 等形态。

单位与百分比

border-radius 支持长度单位（px、em、rem等）与百分比：

• 百分比计算时，水平半径基于元素宽度，垂直半径基于元素高度；
• 对于非正方形元素，即使四个角取相同百分比，四个角也会呈现为椭圆角；
• 当单个半径超过盒子尺寸的一半时，浏览器会按相邻角的半径比例进行钳制（clamping），不会出现两条圆角曲线相交穿透的情况。

在预览器中用百分比配合非正方形盒子，可以直观演示这一行为；而导出 CSS 时使用px则能让结果更贴近「所见即所得」。

读取与设置的正确姿势：长属性优先

border-radius是简写属性，四个角分别对应四个长属性（longhand）：

border-top-left-radius: 10px; border-top-right-radius: 20px; border-bottom-right-radius: 30px; border-bottom-left-radius: 40px;

在 JavaScript 中操作时，需要注意两点：

1. 分开设置长属性（element.style.borderTopLeftRadius = ...）可以逐角精确控制，避免每次重写整条简写声明，也更利于 8 值模式复用同一套更新逻辑；
2. 导出 CSS 时不要依赖style.borderRadius的回读结果——浏览器对简写属性的序列化格式在不同设置组合下可能不一致（例如四个值相同时可能序列化为10px）。更稳妥的做法是由前端状态自行拼装标准四值/八值文本，保证输出格式稳定可预期。

核心知识二：把 CSS 写入剪贴板的两种方式

US-3 要求「将生成的 CSS 复制到剪贴板」。现代浏览器首选基于 Promise 的Clipboard API：

await navigator.clipboard.writeText(cssText);

使用它需要注意的前提条件：

• 需要在安全上下文中运行（https页面或localhost本地开发环境）；
• 需要在用户手势（如按钮点击）触发的事件回调中调用，否则会被浏览器拦截。

作为兼容回退，可选用经典的隐藏textarea+document.execCommand('copy')方案：

function copyWithFallback(text) { const ta = document.createElement('textarea'); ta.value = text; ta.style.position = 'fixed'; ta.style.opacity = '0'; document.body.appendChild(ta); ta.select(); try { document.execCommand('copy'); } finally { document.body.removeChild(ta); } }

推荐在复制按钮的处理函数里做成「优先 Clipboard API、失败则回退 execCommand」的封装，兼顾现代浏览器与旧环境。

实战一：基础版参考实现（覆盖 US-1 与 US-2）

下面给出一个零依赖、单文件的参考实现骨架，对应 US-1（显示带圆角的盒子）与 US-2（调节四个角）。

1. HTML 结构

<section class="app"> <!-- 预览区：US-1，必须能明显看出圆角 --> <div class="stage"> <div id="preview" class="preview-box"></div> </div> <!-- 四个角的控件：US-2 --> <div class="controls"> <label> Top-Left <input type="range">.stage { display: grid; place-items: center; min-height: 320px; background: #f0f0f0; /* 深色对比背景，让圆角与形状变化清晰可见 */ } .preview-box { width: 240px; height: 240px; background: #4a90d9; /* 初始四个角都由 JS 写入，这里不写 border-radius */ }

为了「预览形状」，务必保证预览盒子与舞台背景之间有足够的颜色/明度对比，否则圆角变化难以观察。盒子建议做成正方形（宽高相等），这样 8 值模式下的水平/垂直半径差异可以直观呈现。

3. JavaScript 逻辑

const preview = document.getElementById('preview'); const sliders = document.querySelectorAll('input[data-corner]'); const output = document.getElementById('css-output'); const copyBtn = document.getElementById('copy-btn'); const state = { tl: 20, tr: 20, bl: 20, br: 20 }; function updatePreview() { // 1. 逐角写入长属性，实时生效（US-2） preview.style.borderTopLeftRadius = state.tl + 'px'; preview.style.borderTopRightRadius = state.tr + 'px'; preview.style.borderBottomLeftRadius = state.bl + 'px'; preview.style.borderBottomRightRadius = state.br + 'px'; // 2. 由状态拼装规范的四值简写声明（US-3 的文本来源） const css = `border-radius: ${state.tl}px ${state.tr}px ${state.br}px ${state.bl}px;`; output.textContent = css; // 3. 同步滑块旁边的数值显示 sliders.forEach((s) => { const out = document.querySelector(`output[data-out="${s.dataset.corner}"]`); if (out) out.textContent = s.value + 'px'; }); } sliders.forEach((slider) => { slider.addEventListener('input', (e) => { state[e.target.dataset.corner] = Number(e.target.value); updatePreview(); }); }); updatePreview(); // 初始渲染（US-1）

值得注意的实现细节：

• 状态源唯一：所有显示（预览盒、CSS 文本、output 数值）都从state派生，避免「改一处、漏一处」的同步问题；
• 长属性写入：四条长属性赋值对应style.borderTopLeftRadius等，顺序与简写语义解耦，为后面的 8 值模式复用同一更新函数做了铺垫；
• 使用input事件而非change事件，保证滑块拖动过程中预览实时刷新。

实战二：复制生成的 CSS（覆盖 US-3）

在基础版之上补上复制按钮的逻辑。将上一节「核心知识二」的两种方式封装成一个函数：

async function copyText(text) { try { if (navigator.clipboard && window.isSecureContext) { await navigator.clipboard.writeText(text); return; } } catch (err) { // 剪贴板写入被拒绝或不可用时，走回退方案 } copyWithFallback(text); // execCommand 回退 } copyBtn.addEventListener('click', async () => { await copyText(output.textContent); copyBtn.textContent = 'Copied!'; setTimeout(() => (copyBtn.textContent = 'Copy CSS'), 1500); });

这段代码实现了 US-3 的完整闭环：点击按钮 → 读取当前生成的 CSS 文本 → 写入剪贴板 → 给出「Copied!」的即时反馈。给用户视觉反馈是这类工具型应用的良好体验实践。

Bonus 实战：支持 8 值复杂形状预览

在基础版上扩展斜杠语法能力，即可覆盖 Bonus 特性。思路是：在四个角的控件基础上，再增加一组「垂直半径」滑块，形成 8 个输入。

1. 新增控件与状态

将原先的state拆成水平半径与垂直半径两组：

const state = { h: { tl: 20, tr: 20, bl: 20, br: 20 }, // 水平半径 v: { tl: 20, tr: 20, bl: 20, br: 20 }, // 垂直半径 };

控件层为每组 4 个滑块，用data-axis="h|v"与data-corner组合标识。若不想界面过于拥挤，可以增加一个「复杂形状模式」开关：关闭时只显示一组滑块、导出四值简写；开启时显示两组滑块、导出八值斜杠语法。

2. 更新逻辑与 CSS 导出

function updatePreview() { preview.style.borderTopLeftRadius = `${state.h.tl}px ${state.v.tl}px`; preview.style.borderTopRightRadius = `${state.h.tr}px ${state.v.tr}px`; preview.style.borderBottomRightRadius = `${state.h.br}px ${state.v.br}px`; preview.style.borderBottomLeftRadius = `${state.h.bl}px ${state.v.bl}px`; const h = state.h, v = state.v; const css = `border-radius: ${h.tl}px ${h.tr}px ${h.br}px ${h.bl}px / ` + `${v.tl}px ${v.tr}px ${v.br}px ${v.bl}px;`; output.textContent = css; }

此处长属性直接接受「水平 + 空格 + 垂直」的二元写法（如10px 40px），一行代码同时写入一个角的两个半径，逻辑非常紧凑。导出文本则严格按照斜杠语法生成：

border-radius: 10px 20px 30px 40px / 40px 30px 20px 10px;

把四组水平/垂直半径设为显著不同的值（例如水平全20px、垂直全80px），预览盒会呈现出拉长的椭圆花瓣效果——这正是「用 8 个值创建复杂形状」的直观演示。可以结合几个经典的「花形」取值组合（如围绕0 50%附近的比例搭配）来验证效果。

功能验证与测试建议

完成实现后，建议对照原文档的 User Stories 逐条验收，形成一份可复现的测试清单：

• US-1：页面加载后，预览盒子四角呈现圆角（有border-radius生效）；
• US-2：分别拖动 Top-Left / Top-Right / Bottom-Left / Bottom-Right 四个滑块，只有对应角发生变化，其余角保持不变；
• US-2（边界）：滑块调到 0 时对应角变为直角，调到 200（或大于半边长）时对应角完全收圆且不产生曲线交叉；
• US-3：点击 Copy 按钮后，在任意编辑器中粘贴，得到border-radius: ...的完整合法声明，且数值与当前滑块一致；
• US-3（格式）：导出的 CSS 为四值顺序（左上、右上、右下、左下），8 值模式下为斜杠分隔的水平/垂直两组；
• Bonus：8 值模式下水平半径与垂直半径独立生效，组合后可形成非对称椭圆角与复杂形状；
• 复制按钮在 HTTPS 或 localhost 环境工作正常；在受限环境下回退方案（execCommand）仍可完成复制。

如果以「文档驱动开发」的方式组织代码，可以把上面每条验收项写成注释锚点挂在对应函数旁，让代码与 Border-Radius-Previewer.md 的需求条目一一对应，便于复习与评审。

扩展方向与仓库约定

本项目的仓库定位决定了它的价值主要在「需求规格」而非「实现代码」，但这恰好给了练习者充分的自由发挥空间。基于基础实现可以继续延伸：

• 单位切换：在px与百分比之间切换，观察非正方形盒子下百分比半径的椭圆效应；
• 预设形状：内置若干经典取值组合（圆角矩形、胶囊、花瓣、Squircle）一键套用，方便对比学习；
• 联动 CSS 变量：将预览值写入--radius-tl之类的自定义属性，体验运行时动态改 CSS 变量的能力（仓库中的 Dynamic-CSSVar-app.md 正是这一主题的姊妹项目）；
• 导出到样式表：一键复制整段.box { border-radius: ...; }规则，而不只是单条声明。

如果你打算向仓库贡献新的项目创意，请参考 Example Guide.md 的模板（Tier 标注、User Stories、Bonus features、Useful links、Example projects 五段式结构），并遵循 CONTRIBUTING.md 中「提交前检查是否重复、逐条 PR」的约定——这也解释了为什么每个项目文档都长得如此规整、可直接当需求规格书使用。

总之，Border Radius Previewer 是一个「麻雀虽小、五脏俱全」的入门项目：它横跨 CSS 属性语法、DOM 样式读写、事件驱动更新与剪贴板 API 四个知识点，完成它即完成了一次完整的前端小工具开发闭环。对照本文的语法拆解与参考实现，相信你很快就能跑通全部 User Stories 并玩出属于自己的复杂形状。

• 文档
• 教程