前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载导读本文基于 Calypso 仓库的官方组件文档docs/components.md系统讲解 CalypsoWordPress.com 的 JavaScript/API 前端应用中 UI 组件与子组件的定义、命名空间规则、目录组织、CSS 类命名约定以及组件复用策略。阅读本文后你将掌握如何区分 UI 组件UI primitives、Block 组件、Query 组件、高阶组件与 Section 组件理解component/index.jsx与component/sub-component.jsx的结构差异写出符合 Calypso 规范的my-component__element类名并理解为什么 Calypso 选择复用组件而非复用类的架构哲学。文中结合仓库真实源码如client/blocks/site-icon、client/blocks/site等进行深度印证。概述Calypso 的组件化 UI 哲学Calypso 的 UI 完全由**组件components与子组件sub-components**构建。Calypso 建立了一套既能享受样式封装style encapsulation好处、又能同时利用自然 CSS 级联cascade与原生工具集的系统。核心思想是通过组合composition复用组件而非复用类classes。也就是说CSS 的可复用性依然重要级联cascade被当作有用的工具但开发者通过组合 React 组件来达成复用而不是在多个地方复制粘贴 CSS 类名。正如 client/components/README.md 所述组件是用于组合 Calypso UI 的 React 组件它们自带按照规范docs/coding-guidelines/css.md定义的样式并且样式文件从组件目录中手动加载component/style.scss例如 Badge 组件的样式文件不过当前仓库中该路径实际位于client/components下各组件目录。用这些积木式组件构建界面可以快速构造与 Calypso 其余部分视觉一致的视图也更易于迭代。补充阅读Calypso 组件总览、Blocks 组件总览。术语表Calypso 中遇到的组件类型在 Calypso 中会遇到以下类型的组件类型说明UI componentsUI 原语UI primitives直接渲染 HTML 元素Blocks连接到 state状态的组件或直接代表应用实体的组件Query components负责数据查询但不渲染任何内容的组件Higher-order components封装并提供功能的组件高阶组件Section components特定领域的组件不打算被复用其中Blocks 组件文档 进一步解释Blocks 是由 UI 原语创建出更复杂实体的 React 组件它们通常连接到 state、具备派发 action 的能力承载SitePostCardComments等应用语义功能被封装起来以便在不同 section 中轻松复用。本文档只聚焦UI 组件即直接渲染 HTML 元素、需要添加 class 属性来做样式的 React 组件。关于数据查询组件可参考 我们处理数据的方式 中关于 Query 组件的说明。组件与子组件index.jsx与sub-component.jsxUI 组件本质上分为两种component/index.jsx—— 我们称之为组件componentcomponent/sub-component.jsx—— 我们称之为子组件sub-component一个组件由存放主文件index.jsx的文件夹表示一个子组件是用于渲染组件某一部分的任何其他 jsx 文件。文件夹就是组件的命名空间namespace并决定了该文件夹中任何子组件的 class 前缀。对命名空间唯一有意义的文件夹是 jsx 文件所在的直接容器。这一区分带来三个关键后果每个组件只有一个style.scss。类名无论组件还是子组件总是以组件名作为前缀。子文件夹在功能上不依赖其父文件夹。也就是说子组件写 HTML class 时必须使用其所在文件夹名即组件名其样式进入该文件夹的style.scss文件。把一个子组件提升为独立组件时需要考虑这一点一旦提升它的作用域和前缀就变成全局且独立的了。语法类命名约定我们这样写类名.my-component__element用__表示元素所属的组件。因此组件名存放index.jsx的文件夹名需要具有全局作用域、足够具体、语义清晰。避免使用 vanilla HTML 选择器如.my-component h1尽量使用.my-component__title。因为每个元素都有可被直接选中的 class我们尽量避免后代选择器与子选择器。同样地避免在伪选择器、媒体查询和is-modifier之外使用 Sass 缩进嵌套。大多数选择器应该是样式文件根级别上的单个 class 选择器。更多 Sass/CSS 编写细节见 CSS/Sass 编码规范。与 CSS 编码规范的呼应CSS/Sass 编码规范 给出了一段经典示例展示如何用site/index.jsx渲染站点条目并给标题着色推荐写法.site__title { color: #333; .is-jetpack { color: #444; } }不推荐写法.site { .title { color: #333; .jetpack { color: #444; } } }modifier 类如.is-jetpack总是附着在基础元素组件包裹层上除非上下文需要修改某个组件的属性如.current-site .site__title否则不使用嵌套。规范还强调component片段必须与它所服务样式的 React 组件的文件夹名一致.is-modifier类不能脱离组件类单独使用且不要用#id来做样式。目录组织组件文件夹的可移植性任何组件文件夹都应该能在任何时候被移动到client/components而不会丢失含义或产生冲突。我们把组件放在文件夹中是为了组织目的但它们在语义上并不与这种结构耦合。示例 1命名要自解释假设我们要创建一个渲染 post 元信息的组件并把它放在my-sites/posts/meta-info这被认为是不正确的。meta-info太通用了单独看含义模糊——记住子文件夹是感知不到其容器的——应该写成post-meta或post-meta-info无论父文件夹叫什么。把任何带 jsx 的文件夹想象成一个扁平的组件列表即可。示例 2post-navigation的位置决策假如我们把它放在posts/navigation.jsx则使用的类名是.posts__navigation表明它是posts的子组件并且会随posts移动到任何地方。但如果把它移动到自己的文件夹posts/posts-navigation/index.jsx则类名变成.posts-navigation它就成为独立于posts的独立组件——此时仍放在 posts 目录下只是出于组织需要。这两种做法都是正确的是否创建文件夹应该取决于我们希望一个组件有多独立以及它是否会在其他位置被使用。除直接父目录外的任何文件夹分组都纯粹是组织性的不应影响使用的类名或组件本身的命名。仓库中的实际佐证client/blocks/site-icon从源码看client/blocks/site-icon/index.tsx 是一个独立的组件其根元素 class 为site-icon第 59 行clsx( site-icon, ...)并借助is-${variant}is-primary/is-blank与is-transient等 modifier 区分不同状态它的样式集中在一个style.scssclient/blocks/site-icon/style.scss内部.site-icon.is-blank .gridicon等规则正好体现了单一类选择器 is-modifier 有意义的上下文写法。而 client/blocks/site/style.scss 中则出现.site .site-icon这样的父子组件上下文覆盖第 16-29 行说明site组件在自身作用域内调整子组件site-icon的尺寸、边距等细节——这正是文档所讲上下文需要修改某个给定组件的属性的真实案例。可复用性与目录位置无关组件天然是可复用的无论它们被放在目录结构的哪个位置。这是一个重要的澄清我们并不是根据是否可复用来决定把组件放在哪个文件夹。组件并不一定要放在client/components才能被复用。事实上my-sites/site组件被用于在编辑器中渲染当前站点在侧边栏中渲染站点选择器site picker在 Me 中渲染站点等等只有那些对某个主 section 组没有天然倾向、因此更纯粹的 UI 构建块才被放入client/components。从仓库结构看client/blocks/site/README.md 说明了site组件通过siteId或siteprop 从 Redux store 获取站点数据并暴露indicator、onSelect、href、isSelected等 props——它虽位于client/blocks却被编辑器中渲染当前站点、侧边栏站点选择器、Me 区域等众多位置复用正是复用与目录无关的例证。表现力为什么避免内联 JS 样式避免使用内联 JS 样式作为 props 的一个优势是当需要在远程父组件上下文中修改子组件时。设想你希望在my-sites的侧边栏中显示SiteIcon组件时改变它的边框颜色。这个SiteIcon组件恰好渲染在Site内部Site又在SiteSelector内部最后在Sidebar内部Sidebar → SiteSelector → Site → SiteIcon如果我们使用内联样式就需要从sidebar想要做修改的组件把 style prop 一路传给site-icon以修改那个特定的边框样式值。这既混乱又晦涩还要求把一个无意义的属性穿过那些根本不在乎它的组件把它们与你想要在 Sidebar 中表达的设计意图耦合起来。而使用 CSS 加上我们的命名规范它就变成侧边栏style.scss文件中的一条简单的.sidebar .site-icon {}规则.sidebar .site-icon { // 针对侧边栏上下文修改 site-icon 的边框颜色 }这种做法依然富有表现力、易于阅读并且鉴于我们的约定它能立刻向阅读或检查样式的人传达site-icon是sidebar在某个层级下的子组件——样式表自然反映了组件组合树也表达出仅在此特定上下文中修改该独立组件的意图。由于特异性specificity也增加了所以无论构建过程中侧边栏样式表的顺序如何结果都不受影响。源码中的真实案例client/a8c-for-agencies/components/sidebar/style.scss 第 49-53 行在.all-sites__icon-container, .site-icon上设置border-radius: 2px与margin-inline-end: 12px正是在父组件上下文中微调子组件外观的典型做法client/blocks/site/style.scss 中.site .site-icon规则调整图标尺寸height: 30px; width: 30px;与边距同理。与其他文档的关联脉络数据查询组件Query components详见 我们处理数据的方式其中按时间线讲述了 Emitter Objects → Flux → Redux → Modularized Redux → TanStack Query 五个数据管理时代Query 组件属于该体系中的一类组件。CSS/Sass 编写细则详见 CSS/Sass 编码规范涵盖类命名、is-modifier、媒体查询断点break-*mixins、RTL 处理、z-index 函数等与本组件体系配套的样式规则。组件库总览client/components/README.md 与 client/blocks/README.md 分别给出了 UI 组件与 Blocks 组件的定位说明。小结Calypso 组件体系的核心要点可归纳为组件与子组件由index.jsx与文件夹内其他 jsx 文件区分文件夹即命名空间决定所有类的统一前缀一个组件一个style.scss类名一律component__element避免后代选择器尽量用根级单类选择器目录只服务于组织组件随时可移到client/components而不失语义命名必须自解释如post-meta-info而非meta-info复用组件而非复用类my-sites/site、site-icon等组件跨 section 复用的实例遍布仓库用 CSS 表达上下文用.sidebar .site-icon {}这类上下文选择器替代逐层传递 style prop兼顾表现力、可读性与特异性稳定性。理解并遵循这套规范你就能在 Calypso 中写出命名清晰、样式内聚、可跨目录复用的高质量组件。赞分享前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载相关推荐wp-calypso 组件体系深度指南从 UI 组件、子组件到样式与复用规范wp calypso 组件体系深度指南从 UI 组件、子组件到样式与复用规范 导读 本文基于 wp calypso 仓库中 client/components前端CMSArduino红外遥控库深度解析5个实战技巧掌握多协议红外通信Arduino红外遥控库深度解析5个实战技巧掌握多协议红外通信 Arduino红外遥控库Arduino IRremote是一个功能强大的开源红外信号处理库物联网嵌入式智能家居vscode-cmake-tools与CTest集成自动化测试的完整实现vscode cmake tools与CTest集成自动化测试的完整实现 vscode cmake tools是一款强大的Visual Studio Code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考