基于 Lit 官方 JavaScript 模板构建my-elementWeb 组件从零开始的实战指南【免费下载链接】litLit is a simple library for building fast, lightweight web components.项目地址: https://gitcode.com/GitHub_Trending/li/litmy-element是 Lit 官方lit-starter-js模板内置的示例组件它用最简的代码演示了 Lit 构建 Web Components 的完整链路模板渲染、属性attribute/property配置、事件派发、插槽slot与 CSS Shadow Part。本文以该组件为骨架结合packages/lit-starter-js仓库内的源码、配置与示例页逐步拆解如何在纯 JavaScript 项目中用 Lit 定义自定义元素并把它跑起来、测起来、发布成文档站。组件是什么一个即插即用的 HTML 元素my-element的全部实现位于 packages/lit-starter-js/my-element.js约 70 行代码。它导出一个继承自LitElement的类并在文件末尾通过window.customElements.define(my-element, MyElement)注册为浏览器原生自定义元素。组件对外暴露的能力非常清晰从类上方的 JSDoc 注释my-element.js即可一览事件firescount-changed点击按钮时派发插槽slot默认插槽承载外部传入的子内容CSS Shadow Partcsspartbutton允许外部通过::part(button)定制按钮样式。组件内部维护两个响应式属性properties 声明属性类型默认值作用nameStringWorld生成问候语的收件人名字countNumber0按钮被点击的次数render()方法my-element.js用 Lit 的html模板标签声明视图一个由sayHello(this.name)生成的标题、一个带click事件绑定与partbutton的按钮以及一个slot/slot用于投影子内容。点击按钮时_onClick使count自增并派发count-changed自定义事件my-element.js——这正是 Lit 响应式系统的典型用法改属性视图自动更新。组件还通过静态styles定义了宿主样式:host { display: block; border: 1px solid gray; ... }展示 Lit 内置的css标签写法my-element.js。场景一像写 HTML 一样直接使用my-element是标准 HTML 元素凡是可以写 HTML 的地方都能直接用。文档站首页docs-src/index.md给出的最小用法只有一行my-element/my-element在浏览器中加载时只需要保证my-element.js作为 ES Module 被执行过即可。仓库的 dev/index.html 展示了完整的最小页面结构先加载webcomponents/webcomponentsjs的 loader 做旧浏览器降级再引入lit/polyfill-support.jsLit 的 polyfill 支持主要用于 shadow DOM 相关的浏览器兼容最后以typemodule引入组件源码script src../node_modules/webcomponents/webcomponentsjs/webcomponents-loader.js/script script src../node_modules/lit/polyfill-support.js/script script typemodule src../my-element.js/script页面 body 里直接嵌套使用my-element pThis is child content/p /my-element这段子内容会进入组件的默认插槽被渲染出来同时演示了组件可以包裹内容这一 Web Components 基本能力。文档站的 Basic 示例docs-src/examples/index.md也复用了同样的写法并额外展示了从外部用 CSS 影响插槽内容的方式。场景二用 attribute 配置组件Web 组件与普通 HTML 元素的亲和力还体现在可以用 attribute 直接传参。文档首页给出的配置方式my-element nameHTML/my-element这里的nameattribute 会被 Lit 的属性反射机制映射到组件的nameproperty 上。在 my-element.js 中name: {type: String}的声明正是这种映射的契约Lit 读取 HTML attribute 的字符串值按type转换后赋给 property反过来当 property 变化时 Lit 也会将其序列化回 attributecount同理默认的 attribute 名即属性名小写。所以运行时组件会渲染出Hello, HTML!这样的标题。另一个 Name Property 示例docs-src/examples/name-property.md给出等价用法my-element nameEarth/my-element值得注意的是模板中的nameattribute 是静态写法若想在动态场景中传值就要用到下面介绍的声明式渲染通过.name的 property 绑定语法点号前缀传入任意 JavaScript 值。场景三在声明式渲染框架中集成my-element并不局限于手写 HTML它可以无缝嵌入 Angular、React、Vue 以及 lit-html 等声明式渲染体系。文档首页给出的 lit-html 示例import {html, render} from lit-html; const name lit-html; render( html h2This is a lt;my-elementgt;/h2 my-element .name${name}/my-element , document.body );这段代码中有两个关键点.name${name}是 property 绑定点号告诉 lit-html 直接设置 DOM property 而非 attribute因此可以传入非字符串值。由于name是响应式属性后续更新name变量并重新render时Lit 的差异算法会精准更新对应节点无需手动操作 DOM。lt;my-elementgt;是 HTML 实体转义在模板字面量中写出lt;与gt;是为了让h2内以纯文本形式显示标签名字符串属于演示性写法。这一场景还体现了 Lit 生态的核心设计任何 Lit 组件包括模板、指令、装饰器都遵循同一套响应式与更新机制因此可以被其它框架的渲染循环驱动这是 Web Components 跨框架复用的天然优势。在本地把项目跑起来packages/lit-starter-js是一个独立的 npm 包package.jsondependencies中直接依赖lit当前仓库对应版本为^3.2.0。按以下步骤可完成从安装到预览npm i # 安装依赖 npm run serve # 启动 Web Dev Server 并打开浏览器预览serve实际执行的是wds --watchweb/dev-server它负责两件事解析浏览器不支持的 Node 风格裸模块导入bare import如import {LitElement} from lit以及自动转译与按需注入 polyfill。开发预览地址为http://localhost:8000/dev/index.html。package.json中还提供了开发/生产两种模式的切换npm run serve # 开发模式Lit 输出更详细的报错信息 npm run serve:prod # 生产模式MODEprod 环境变量驱动输出更精简测试、Lint 与格式化质量闭环模板内置了基于 web/test-runner 的完整测试链路全部脚本见 package.jsonnpm test # 依次跑 test:dev 与 test:prod双模式回归 npm test:watch # 开发模式 文件变更自动重跑 npm run test:prod # 仅生产模式 npm run test:prod:watch # 生产模式 watch双模式测试的意义在于开发模式下 Lit 提供更详尽的报错提示便于调试而生产模式则验证打包后的真实行为二者组合能最大化覆盖问题面。代码质量方面模板同时接入两套工具npm run lint # eslint **/*.js lit-analyzer my-element.js npm run format # Prettier 统一格式化其中lit-analyzer专门对 lit-html 模板做类型检查与 lint使用的规则引擎与 VS Code 的 lit-plugin 扩展完全一致。仓库推荐在 VS Code 中安装 lit-plugin以获得模板语法高亮、悬停文档、跳转定义、快速修复等能力.vscode目录也配置了扩展推荐。Lint 规则基于各工具推荐配置并针对 LitElement 做了适度放宽可按需编辑.eslintrc.json调整。生成文档站eleventy Custom Elements Manifestlit-starter-js另一个特色是自带一个由Eleventy11ty静态站点生成器构建的文档站源码在 docs-src 目录构建产物输出到docs/。站点页面由三部分支撑手工编写的 Markdown 页面如首页 docs-src/index.md即my-element的主页、docs-src/install.md 安装页以及 docs-src/examples/ 下的示例页Basic、Name PropertyAPI 文档页由 docs-src/api.11ty.cjs 从 Custom Elements Manifestcustom-elements.json自动生成将组件的 Attributes、Properties、Methods、Events、Slots、CSS Shadow Parts、CSS Custom Properties 渲染成结构化表格真正实现文档与源码同步布局与导航模板位于 docs-src/_includes其中example.11ty.cjs扩展自page.11ty.cjs为示例页额外渲染可切换的示例导航列表。构建与预览文档站的命令npm run docs # 完整构建clean → analyze → build → assets → gen npm run docs:serve # 本地预览默认 http://localhost:8000 npm run docs:gen:watch # watch 模式改文件自动重建构建链路的各环节对应 package.json 中的脚本rimraf docs清理旧产物cem analyze --litelement用 Custom Elements Manifest Analyzer 扫描**/*.js生成custom-elements.jsonrollup -c --file docs/my-element.bundled.js将组件打包压缩成单文件供文档站演示用eleventy --config.eleventy.cjs生成静态站点。注意这里的 Rollup 打包仅服务于文档站并非组件发布流程。站点按docs-src/_README.md的说明部署到 GitHub Pages在仓库 Settings 中将 Pages 的 Source 设置为main branch /docs folder把构建产物提交并推送即可生效。发布组件时的正确姿势模板 README 特别提醒推荐以未压缩的 ES Module 形式发布组件把构建期优化留给应用层如摇树、去重等由打包器完成。也就是说lit-starter-js中 Rollup 配置的存在理由是生成文档站演示产物而不是作为组件发布的默认方式真正面向生产应用时应按应用级打包工具如 Rollup、webpack、Vite的惯例去处理依赖与压缩。小结一条从示例到生产的学习路径从docs-src/index.md的三段式演示直接使用 → attribute 配置 → lit-html 声明式渲染出发配合 my-element.js 的实现、package.json 的脚本体系和 dev/index.html 的页面样例可以完整掌握 Lit 组件开发的五个核心环节定义响应式组件、属性映射与事件派发、在任意框架中集成、双模式测试与 Lint、自动生成并部署文档站。这套模板既是初学者理解 Lit 的入口也是可复用组件项目的起步骨架。【免费下载链接】litLit is a simple library for building fast, lightweight web components.项目地址: https://gitcode.com/GitHub_Trending/li/lit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考