wp-calypso 促销区块组件（Promo Section）完全指南：布局、属性与实战用例

前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载Promo Section 是 wp-calypso 中用于排版PromoCard组件、构建推广型页面布局的容器组件主要服务于 Earn赚钱板块与 Marketing Tools营销工具等页面。本文基于 client/components/promo-section/README.md 展开结合仓库源码深入讲解其数据模型、两种调用形态、子组件PromoCard、PromoCardCta、PromoCardPrice的完整属性并通过源码级证据与可运行示例帮助你直接复用这套促销卡片方案搭建同类营销落地页。组件定位与适用场景PromoSection是一个纯展示型布局组件它本身不持有业务状态只负责把一组PromoCard按“1 个主推卡 若干普通卡”的结构排列成页面其设计初衷是为 Earn 板块和 Marketing Tools 提供统一的推广卡片排版。从入口文件 client/components/promo-section/index.tsx 可以看到它的渲染结构非常精简const PromoSection: FunctionComponent Props ( { header, promos } ) { return ( div classNamepromo-section { header PromoSectionCard isPrimary { ...header } / } div classNamepromo-section__promos { promos.map( ( promo, i ) ( PromoSectionCard { ...promo } key{ i } / ) ) } /div /div ); };结构约定如下传入header时它会被渲染为isPrimary{ true }的主推卡片位于区块顶部视觉上更突出详见后文is-primary样式promos数组中的每一项渲染为一张普通PromoCard统一收容在.promo-section__promos容器内由 CSS 自动完成栅格排列。快速上手一个最小可用示例原文档给出了最基础的PromoCard用法README.mdimport PromoCard from calypso/my-sites/promo-section/promo-card; const PromoCardExample () { return ( PromoCard titleUnder-used Feature img src/calypso/images/wordpress/logo-stars.svg width170 height143 altWordPress logo / p This is a description of the action. It gives a bit more detail and explains what we are inviting the user to do. /p /PromoCard ); };几点说明PromoCard可直接嵌套任意 JSX 作为children因此既可以直接放img也可以传结构化image属性见下文原文档中的导入路径calypso/my-sites/promo-section/promo-card为历史路径别名写法当前仓库中该组件实际位于calypso/components/promo-section/promo-card见 promo-card/index.tsx 及 docs/example.jsx 中的导入方式引用时以实际存在的components路径为准。声明式数据驱动PromoSection 的属性模型PromoSection的使用方式是传数据对象而非手写 JSX其完整类型定义位于 index.tsxexport interface PromoSectionCardProps extends PromoCardProps { body: string | TranslateResult; actions?: PromoCardCtaProps; } export interface Props { header?: PromoSectionCardProps; promos: PromoSectionCardProps[]; }header可选。用于主推卡片自动加isPrimary如 Earn 页“Start earning money”的引导卡promos必填数组。每项是一个卡片数据对象运行时被展开为PromoSectionCard { ...promo } /每个卡片对象在PromoCardProps基础上额外要求body正文文案支持 i18n 的TranslateResult并可选actionsCTA 配置类型见 cta.tsx。内部PromoSectionCard会对actions做一次分发index.tsx若actions.cta提供了自定义component则直接渲染该自定义组件否则渲染内置的PromoCardCtaCTA 按钮 可选的 “Learn more” 链接。仓库提供了完整的声明式示例 docs/example.tsx直接可复制运行import earnSectionImage from calypso/assets/images/earn/earn-section.svg; import recurringImage from calypso/assets/images/earn/recurring.svg; import simplePaymentsImage from calypso/assets/images/earn/simple-payments.svg; import PromoSection, { Props as PromoSectionProps } from calypso/components/promo-section; const PromoSectionExample () { const promos: PromoSectionProps { header: { title: Start earning money, image: { path: earnSectionImage }, body: There is a range of ways to earn money through your WordPress.com Site., }, promos: [ { title: Collect one-time payments, body: Add a payment button to any post or page to collect PayPal payments for physical products, digital goods, services, or donations. Available to any site with a Premium plan., image: { path: simplePaymentsImage }, actions: { cta: { text: Collect One-time Payments, action: / } }, }, { title: Collect payments, body: Charge for services, collect membership dues, or take one-time or recurring donations. Automate recurring payments, and use your site to earn reliable revenue. Available to any site with a paid plan., image: { path: recurringImage }, actions: { cta: { text: Collect Payments, action: / } }, }, ], }; return ( div classNamedesign-assets__group PromoSection { ...promos } / /div ); }; export default PromoSectionExample;可以看到CTA 的action可以直接传字符串路径内部会转成href也可以传函数或对象具体见下文 PromoCardCta 一节。PromoCard促销卡片的核心展示单元PromoCard本质是“基于Card、参照ActionPanel结构”设计的展示卡片用于推广套餐功能与合作伙伴内容见 promo-card/README.md。其渲染底层直接复用了ActionPanel系列组件promo-card/index.tsxActionPanel className{ classes } { image ! isCompact ( ActionPanelFigure inlineBodyText{ false } align{ imageActionPanelAlignment } { isImage( image ) ? ( img src{ image.path } alt{ image.alt || } className{ image.className } / ) : ( image ) } { titleComponentLocation TitleLocation.FIGURE titleComponentHeader } /ActionPanelFigure ) } { icon ! isCompact ( ActionPanelFigure inlineBodyText{ false } alignleft Gridicon icon{ icon } size{ 32 } / { titleComponentLocation TitleLocation.FIGURE titleComponentHeader } /ActionPanelFigure ) } ActionPanelBody { title ( ActionPanelTitle className{ clsx( { is-primary: isPrimary } ) } { icon isCompact Gridicon icon{ icon } size{ 32 } / } { title } { badgeComponent } /ActionPanelTitle ) } { titleComponentLocation TitleLocation.BODY titleComponentHeader } { isPrimary ? Children.map( children, ( child ) { if ( ! child || ! isValidElement { isPrimary?: boolean } ( child ) ) { return child; } return PromoCardCta child.type ? cloneElement( child, { isPrimary } ) : child; } ) : children } /ActionPanelBody /ActionPanel完整属性表类型定义见 promo-card/index.tsx属性类型默认值说明titlestring \| TranslateResult—卡片标题支持 i18n 翻译结果titleComponentReactElement—自定义标题元素可放置在 BODY 或 FIGURE 区域titleComponentLocationTitleLocationTitleLocation.BODY自定义标题的位置BODY位于正文区、FIGURE位于图示区iconstring—Gridicon 图标名非 compact 时渲染在左侧图示区compact 时渲染在标题内imageImage \| ReactElement—图片既可传{ path, className?, alt?, align? }对象也可直接传任意 React 元素isPrimarybooleanfalse是否为主推卡视觉与排版上更突出badgestring \| ReactElement—标题旁的角标徽章渲染为BadgeclassNamestring—追加到卡片根节点的自定义类名childrenReactNode—卡片正文内容variationPromoCardVariationPromoCardVariation.Default卡片形态compact紧凑模式 /default默认模式Image对象的align字段支持left | right用于控制图示在ActionPanelFigure中的对齐方向默认left见 index.tsx。isPrimary 与 compact 两种形态的行为差异从源码可以看到两处关键分支逻辑isPrimary主推卡PromoCardCta child.type ? cloneElement( child, { isPrimary } ) : child—— 会自动把children中的PromoCardCta注入isPrimary让主按钮样式同步为 primary同时标题使用品牌字体并放大字号图文居中排版见 style.scss 中.is-primary规则如$font-title-medium、justify-content: center等。compact紧凑卡isCompact variation PromoCardVariation.Compact此时不渲染image 与 icon 的ActionPanelFigure图示区图标改为内嵌在标题行内并以 20px 网格图标展示适合空间受限的列表场景style.scss。响应式行为两张卡片的样式共同负责响应式布局PromoCard在480px断点由纵向改为横向图文并排主推卡在660px隐藏图示、800px恢复图示避免 660–800px 区间插图过小1280px时左右内边距加大style.scssPromoSection的.promo-section__promos在移动端单列1280px断点切换为flex-direction: row每张卡宽度calc(50% - 1em)实现两列栅格style.scss。PromoCardCta主按钮与 Learn more 链接CTA 子组件负责渲染主行动按钮cta.tsx其属性与内部逻辑如下interface CtaAction { url: URL; onClick: ClickCallback; selfTarget?: boolean; label?: string; } export interface CtaButton { text: string | TranslateResult; action: URL | ClickCallback | CtaAction; isPrimary?: boolean; component?: JSX.Element; disabled?: boolean; busy?: boolean; }cta.text按钮文案cta.action支持三种形态——字符串 URL、点击回调函数、或{ url, onClick, selfTarget }对象component自定义按钮元素若存在则 PromoSection 优先渲染它而非内置按钮disabled/busy按钮禁用与加载态直接透传给automattic/components的ButtonlearnMoreLink可选次级链接渲染为 borderless 的 “Learn more” 按钮默认文案可被label覆盖且 URL 会经过localizeUrl本地化处理cta.tsx。按钮 props 的拼装逻辑值得注意cta.tsx对象形态的 action 会同时设置href、onClick与selfTarget当存在href且未设置selfTarget时自动补target_blank新标签打开随后删除 React 不认识的selfTarget属性以避免控制台警告。promo-card自带的文档示例 docs/example.jsx 展示了完整写法包括通过useSelector( getSelectedSiteSlug )动态拼接结账链接PromoCard titleUnder-used Feature image{ img } isPrimary{ false } p This is a description of the action. It gives a bit more detail and explains what we are inviting the user to do. /p PromoCardCTA cta{ { text: translate( Upgrade to Pro Plan ), action: { url: /checkout/${ siteSlug }/pro, onClick: clicked, selfTarget: true, }, } } / /PromoCardPromoCardPrice价格展示组件PromoCardPrice用于在卡片中展示价格、折扣与附加信息price.tsx属性类型说明formattedPricestring \| TranslateResult价格文案不传时默认渲染为 “Free”经translate处理discountstring \| TranslateResult \| null折扣文案渲染为绿色折扣标签同时给原价加删除线additionalPriceInformationstring \| TranslateResult \| ReactElement价格下方的附加说明可传任意 React 元素其格式化约定见源码注释formattedPrice应遵循格式span$price/span /interval例如span$1/span /year配合 SCSS 中.price__cost span的大号价格样式style.scss即可渲染出“大号价格 小号计费周期”的经典定价卡片效果。小结如何在自己的页面中组合使用组合思路可以总结为三层单卡层用PromoCard 可选PromoCardCta、PromoCardPrice描述一张促销卡的内容、图示、徽章、按钮与价格区块层用PromoSection的headerpromos数据模型声明式拼装整个推广区块主推信息放header样式层无需额外编写栅格代码PromoSection与PromoCard自带响应式规则移动端单列、宽屏两列主推卡自动居中放大。需要接入时直接引用calypso/components/promo-section与calypso/components/promo-section/promo-card并按上文示例填充数据即可若需自定义按钮样式或展示价格可分别扩展PromoCardCta的component字段或使用PromoCardPrice。相关源码与示例可进一步查看 client/components/promo-section/index.tsx、client/components/promo-section/promo-card/index.tsx、client/components/promo-section/promo-card/cta.tsx、client/components/promo-section/promo-card/price.tsx 及两个 docs 示例文件 docs/example.tsx 与 promo-card/docs/example.jsx。赞分享前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载相关推荐wp-calypso Section 组件详解构建带标题的分区布局与暗色背景实践wp calypso Section 组件详解构建带标题的分区布局与暗色背景实践 Section 是 WordPress.com 前端应用 wp calyps前端CMSwp-calypso Main 布局组件完全指南掌握 calypso/components/main 的宽屏布局与无障碍语义wp calypso Main 布局组件完全指南掌握 calypso/components/main 的宽屏布局与无障碍语义 Main 是 wp calyps前端CMSwp-calypso 双栏布局组件 Layout 与 Column 完整解析wp calypso 双栏布局组件 Layout 与 Column 完整解析 导读 Layout 与 Column 是 WordPress.com 前端核心仓库前端CMS上一篇3步轻松上手Vortex游戏模组管理器完全指南下一篇HsMod炉石传说终极增强插件 - 55项功能完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考