wired-elements 之 wired-checkbox：手绘风格复选框 Web 组件的完整使用与源码剖析

UI组件前端【免费下载链接】wired-elementsCollection of custom elements that appear hand drawn. Great for wireframes or a fun look.项目地址https://gitcode.com/gh_mirrors/wi/wired-elements点击查看免费下载本文围绕 wired-elements 仓库中的 docs/wired-checkbox.md 展开系统讲解wired-checkbox手绘风格复选框组件的安装引入、属性配置、事件监听与样式定制方法并结合 src/wired-checkbox.ts 等源码剖析其手绘渲染原理与交互实现。读完本文你将能够在线框原型、低保真 Mockup 或追求手绘趣味风格的页面中直接落地使用并深度定制该组件。组件概述wired-checkbox是 wired-elements 组件库中的一个 Web Component用于渲染带有手绘hand-drawn / sketchy外观的复选框。它适合用于 wireframes线框图、mockups原型稿或只是想要手绘风格的页面场景。整个 wired-elements 项目被定义为Collection of custom elements that appear hand drawn其全部组件基于LitWeb Components 标准库与RoughJS手绘风格矢量绘制引擎构建这一点可以从 package.json 中的dependencieslit: ^2.0.0-rc.1、roughjs: ^4.3.1得到确认。当前仓库版本为3.0.0-rc.7。wired-checkbox是使用 Custom Elements 标准定义的通过customElement(wired-checkbox)注册见 src/wired-checkbox.ts因此在 HTML 中可直接以wired-checkbox标签使用无需任何框架。安装与引入方式一npm 安装推荐在你的 JavaScript 项目中安装npm i wired-elements安装完成后按需引入WiredCheckbox类import { WiredCheckbox } from wired-elements; // 或按单文件路径引入 import { WiredCheckbox } from wired-elements/lib/wired-checkbox.js;从源码看src/wired-elements.ts 通过export * from ./wired-checkbox将组件汇出到库的统一入口因此两种引入方式效果一致按需路径引入有助于减小打包体积。方式二CDN 直接加载如果不想使用打包工具可以直接在 HTML 页面中通过 ES Module 方式加载script typemodule srchttps://unpkg.com/wired-elements/lib/wired-checkbox.js?module/script方式三本地示例参考仓库自带的 examples/checkbox.html 给出了最简可运行示例其引入方式为script typemodule src../lib/wired-checkbox.js/script注意该示例假设你已经执行过构建npm run build即rm -rf lib tsc产出编译后的lib/目录参见 package.json 的 scripts 配置。直接浏览示例前需先构建项目。在 HTML 中使用引入模块后即可像使用原生标签一样使用wired-checkboxCheckbox One/wired-checkbox wired-checkbox checkedCheckbox Two/wired-checkbox wired-checkbox disabledDisabled checkbox/wired-checkbox标签中间的内容文本或任意元素通过slot/slot渲染为复选框的标签文字见 src/wired-checkbox.tschecked属性声明默认选中disabled属性声明禁用状态。从源码看组件的内部结构WiredCheckbox继承自WiredBasesrc/wired-base.ts其渲染模板核心结构为见 src/wired-checkbox.tslabel idcontainer input typecheckbox ← 真实原生输入框透明覆盖负责语义与键盘交互 spanslot/slot/span ← 标签文字 div idoverlaysvg/svg/div ← 手绘外观的 SVG 覆盖层 /label关键设计点真正的交互仍由原生input typecheckbox承担保证了表单语义、键盘操作与无障碍Accessibility基础原生 input 被opacity: 0隐藏视觉上完全由覆盖层 SVG 呈现手绘外观覆盖层 SVG 由WiredBase.wiredRender()统一绘制管理且在未完成渲染前组件整体opacity: 0渲染完成后通过.wired-rendered类切换为可见见 src/wired-base.ts避免闪烁。属性Properties属性类型默认值说明checkedbooleanfalse复选框的选中状态disabledbooleanfalse是否禁用复选框源码中的定义src/wired-checkbox.tsproperty({ type: Boolean }) checked false; property({ type: Boolean, reflect: true }) disabled false;实现细节两个属性均为布尔类型采用property装饰器声明是响应式属性——当值变化时组件会自动重新渲染disabled额外设置了reflect: true即该属性会反映到 DOM 的 attribute 上因此:host([disabled])这类属性选择器样式才会生效例如禁用态的半透明外观checked没有设置 reflect它仅作为组件内部状态并通过change事件对外同步禁用态样式在 src/wired-checkbox.ts 中定义整体opacity: 0.6、cursor: default、pointer-events: none阻止一切指针交互且 SVG 背景叠加rgba(0, 0, 0, 0.07)以强化灰色不可用的视觉提示。选中状态的内部管理在onChange处理器src/wired-checkbox.ts中组件将原生 input 的勾选状态同步到自身checked属性刷新勾选记号可见性然后派发事件private onChange() { this.checked this.input!.checked; this.refreshCheckVisibility(); this.fire(change, { checked: this.checked }); }勾选记号√由两段手绘线条组成绘制于draw()方法src/wired-checkbox.tsprotected draw(svg: SVGSVGElement, size: Point) { rectangle(svg, 0, 0, size[0], size[1], this.seed); this.svgCheck svgNode(g); svg.appendChild(this.svgCheck); line(this.svgCheck, size[0] * 0.3, size[1] * 0.4, size[0] * 0.5, size[1] * 0.7, this.seed); line(this.svgCheck, size[0] * 0.5, size[1] * 0.7, size[0] 5, -5, this.seed); }外框使用rectangle绘制画布尺寸固定为 24×24canvasSize()返回[24, 24]见 src/wired-checkbox.ts对勾是两条线段line未选中时通过refreshCheckVisibility()将g元素display设为none隐藏src/wired-checkbox.tsthis.seed是组件创建时生成的随机数种子Math.floor(Math.random() * 2 ** 31)见 src/wired-base.ts它决定了手绘线条的随机抖动形态——这就是每个组件手绘纹理独一无二的来源。这些rectangle、line等底层绘制函数封装在 src/wired-lib.ts 中内部调用 RoughJS 的渲染器生成手绘路径。事件Events事件触发时机事件详情change用户勾选/取消勾选复选框时detail: { checked: boolean }监听示例document.querySelector(wired-checkbox).addEventListener(change, (e) { console.log(checked:, e.detail.checked); });事件通过WiredBase.fire()派发src/wired-base.ts底层调用fireEventsrc/wired-base.ts构造的CustomEvent带有composed: true与bubbles: true因此事件可以穿透 Shadow DOM 冒泡到普通 DOM 树在父级容器统一监听即可detail中携带最新选中状态{ checked: boolean }可直接用于表单状态收集。自定义样式Custom CSS Properties主要变量CSS 变量作用默认值--wired-checkbox-icon-color复选框整体外框与对勾的描边颜色currentColor使用方式wired-checkbox { --wired-checkbox-icon-color: red; }在 src/wired-checkbox.ts 中SVG 路径的描边颜色定义为path { stroke: var(--wired-checkbox-icon-color, currentColor); stroke-width: var(--wired-checkbox-default-swidth, 0.7); }由于默认值是currentColor只需通过 CSS 的color属性改变文字颜色就能同步改变复选框颜色无需单独设置变量。仓库示例 examples/checkbox.html 正是这样演示的为元素设置color: blue与--wired-checkbox-icon-color: red实现文字与勾选框分色。额外可用的内部变量从源码还可以发现一个未写入原文档但实际可用的变量CSS 变量作用默认值--wired-checkbox-default-swidth手绘线条的描边粗细0.7组件聚焦focus时线条会加粗到1.5src/wired-checkbox.ts这是键盘可达性keyboard accessibility的视觉反馈用户通过 Tab 聚焦到复选框时能够清晰看到焦点所在。与聚焦/键盘交互相关的细节组件重写了focus()方法src/wired-checkbox.ts将焦点委托给内部的隐藏原生 input从而支持 Tab 键聚焦、空格键切换勾选状态等原生键盘行为聚焦/失焦时通过focused状态类切换外观对勾加粗、线条描边变粗。这对表单类组件的可访问性非常重要视觉上手绘化交互上仍完全遵循原生复选框行为。进阶在表单场景中组合使用wired-checkbox的checked属性既可以声明式设置也可以在 JavaScript 中读写const box document.querySelector(wired-checkbox); box.checked true; // 编程式勾选 console.log(box.checked);配合change事件可以构建自定义表单逻辑例如收集一组手绘复选框的选中项document.querySelectorAll(wired-checkbox).forEach((box) { box.addEventListener(change, (e) { const state e.detail.checked; // state 为 boolean处理选中项 }); });需要注意的是仓库示例 examples/checkbox.html 展示了四种典型状态普通、默认选中checked、禁用disabled以及自定义样式classcustom可以作为集成时的最小参考模板。小结wired-checkbox在保持原生复选框完整语义表单、键盘、无障碍的前提下通过 Lit RoughJS 提供了可高度定制的手绘外观。使用它只需三步安装wired-elements、引入模块、在 HTML 中书写wired-checkbox标签。核心可配置项为checked、disabled两个属性、change事件以及--wired-checkbox-icon-color自定义属性另有未文档化的--wired-checkbox-default-swidth可调线条粗细。结合 src/wired-checkbox.ts、src/wired-base.ts、src/wired-lib.ts 与 examples/checkbox.html你可以进一步理解其渲染原理并在线框图、原型或趣味风格的页面中自由使用。许可说明组件遵循 MIT License版权归作者 Preet Shihn 所有详见仓库根目录 LICENSE 文件。赞分享UI组件前端【免费下载链接】wired-elementsCollection of custom elements that appear hand drawn. Great for wireframes or a fun look.项目地址https://gitcode.com/gh_mirrors/wi/wired-elements点击查看免费下载相关推荐wired-elements 之 wired-radio-group手绘风格单选组组件完整使用与源码解析wired elements 之 wired radio group手绘风格单选组组件完整使用与源码解析 导读 wired radio group 是 wirUI组件前端wired-elements 之 wired-toggle手绘风格开关组件完整使用与实现解析wired elements 之 wired toggle手绘风格开关组件完整使用与实现解析 wired toggle 是 wired elements 组件UI组件前端wired-elements 手绘风格输入组件 wired-input 完整使用指南wired elements 手绘风格输入组件 wired input 完整使用指南 wired input 是 wired elements 组件库中一个UI组件前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考