前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载本指南以 client/jetpack-connect/connection-content/README.md 为核心讲解如何在 WordPress.com 的 Calypso 前端即 wp-calypso 仓库中将一个新插件接入统一的 Jetpack 连接流程fromjetpack-connector。该流程是插件感知plugin-aware的WordPress 站点通过plugins查询参数把活动插件列表传给 Calypso后者据此为 authorize授权、login登录、signup注册三个页面动态选择复合 Logo、副标题文案、特性卡片以及二次连接secondary-connection文案。读完本文你将掌握家族family分类机制、插件注册表的用法、特性卡片与字幕场景的定制流程以及对应的测试与验证方法。背景统一连接流程与插件感知Calypso 的连接流程有多个入口变体其中fromjetpack-connector以及它的二次连接变体是一条统一授权/登录/注册链路。它的核心特点是插件感知WordPress 插件如 Jetpack 及其子插件、WooCommerce、Automattic for Agencies在生成授权 URL 时会把自身 slug 以逗号分隔列表的形式放进plugins查询参数Calypso 拿到这个列表后会为整个流程挑选复合 Logo——authorize、login、signup 三个页面头部展示的 Logo字幕场景Subtitle scenario——每个界面auth / login / signup从 16 条预写文案中选一条副标题特性卡片Feature cards——what youll get你将获得区域中最多 3 张按品牌区分的卡片二次连接文案——当站点已有连接所有者connection owner、其他管理员继续连接 WordPress.com 账号时展示的精简文案。二次连接内容由 Jetpack 插件Manager::get_authorization_url()在站点已有连接所有者时发出的has_connected_owner1URL 信号触发。authorize.jsx 中的isSecondaryConnection()是它的消费方而旧的already_authorized1信号仍由 Jetpack 插件的Webhooks::handle_connect_url_redirect()发出与本指南所述的插件感知二次内容无关。两个信号相互独立可能同时出现在同一个 URL 上但互不蕴含——在 AGENTS.md 中有明确记录不要把has_connected_owner加到非 connector 的门控上也不要把already_authorized的使用范围扩展到其他分支。工作原理总览插件 slug 通过plugins查询参数逗号分隔列表到达 Calypso。系统先把每个 slug 归类到某个家族familya4a、woo、jetpack或other再根据家族组成决定界面呈现。数据流如下plugins query param │ ▼ families.ts ── getFamilyFromSlug() ──► Family (a4a | woo | jetpack | other) │ ├── plugin-registry.ts ──► display name, isFullJetpack flag │ ├── scenarios.ts ──► SubtitleScenario (16 possibilities) │ └── copy.ts ──► subtitle strings for auth / login / signup / secondary │ ├── selectors.ts ──► getFeatureSelection() ──► card keys │ └── family-features.ts ──► card title bullets (first connection secondary) │ └── feature-cards.tsx ──► assembled cards with logos │ └── plugin-registry.ts ──► getLogoForFamilies() ──► composite header logo模块之间的依赖关系可以从 connection-content/index.ts 看出——它是一个统一的导出入口把families.ts、plugin-registry.ts、selectors.ts、copy.ts、scenarios.ts、family-features.ts的类型与函数集中 re-export供feature-cards.tsx和authorize.jsx等上层组件使用。逐步操作把插件加入现有家族如果你的插件属于现有家族A4A、Woo 或 Jetpack系统的大部分功能会通过前缀匹配自动生效。以下是具体步骤。第 1 步核对家族分类families.tsfamilies.ts 中的getFamilyFromSlug()按前缀对 slug 分类automattic*→a4awoocommerce*→woojetpack或jetpack-*→jetpack其他一切 →other如果你的插件 slug 命中这些前缀之一这一步就完成了。如果它属于已知家族但用了非标准前缀例如名为payments-gateway的 Woo 扩展则需要在getFamilyFromSlug()中追加一个分支。源码还定义了FAMILY_PRIORITY常量[a4a, woo, jetpack, other]这是家族在文案与卡片中的优先级顺序A4A 优先其次是 Woo、Jetpack最后才是其他。特性卡片与字幕场景的槽位选择都会遍历这个数组因此调整它的顺序会改变整个流程的层级关系。未知 slug 一律回退到other——未知插件永远不会阻断连接流程。第 2 步注册插件plugin-registry.ts在 plugin-registry.ts 的PLUGIN_REGISTRY中新增一条记录your-plugin-slug: { slug: your-plugin-slug, family: woo, // 或 jetpack、a4a displayName: Your Plugin Name, },这为任何需要引用该插件的界面提供了人类可读的名称。PluginEntry接口包含slug、family、displayName和可选的isFullJetpack。如果跳过这一步原始 slug 会被当作显示名使用——流程不会中断只是观感不够精致。对于 Jetpack 家族插件只有主 Jetpack 插件才设置isFullJetpack: true子插件应省略此标记。目前注册表中jetpack是唯一设置isFullJetpack: true的条目其余jetpack-backup、jetpack-protect、jetpack-boost、jetpack-search、jetpack-social、jetpack-videopress以及 Woo 家族的woocommerce、woocommerce-payments、A4A 家族的automattic-for-agencies-client均未设置。注册表是增量式additive的调用方应当始终把未知 slug 当作优雅回退来处理通过getFamilyFromSlug解析其家族而不是依赖注册表中存在该条目。getPluginDisplayName()在插件未注册时返回原始 sluggetPluginEntry()对未注册 slug 返回undefined。isFullJetpack标记在 selectors.ts 的hasFullJetpack()中被消费用于在完整 Jetpack 文案变体与单插件变体之间做选择。第 3 步决定插件是否需要专属特性卡片卡片有两个层级的特异性家族级卡片如woo、jetpack完整插件或多个同家族插件处于活动状态时使用。大多数新插件应该用这个。单插件卡片如jetpack-backup、jetpack-social仅当恰好一个Jetpack 子插件处于活动状态时使用让卡片可以做到超具体。如果你的插件需要单插件卡片仅限 Jetpack 子插件按以下子步骤操作a. 新增FeatureCardKeyfamily-features.ts把你的 slug 加进 family-features.ts 的FeatureCardKey类型export type FeatureCardKey | a4a | woo | jetpack // ...existing keys... | your-plugin-slug // ← 在这里添加 | other;卡片键集合是消费方驱动的每个键都由同一个FeaturesSection /组件使用getFeatureCardData()返回的数据渲染因此新增键后无需改动渲染组件。b. 添加首次连接卡片数据family-features.ts在getFeatureCardData()中添加一个casecase your-plugin-slug: return { title: __( Your Plugin Name ), bullets: [ __( First key benefit, written so it reads in isolation and in audience-neutral voice. ), __( Second key benefit. ), __( Third key benefit. ), ], };bullets[0]不变量第一条 bullet 必须是受众中立的不使用第二人称your优先用the site/the store并且必须能独立成句、读得通。当 A4A 也在活动插件中时feature-cards.tsx 中的getConnectorFeatureCards()会把每张支撑卡片裁剪到只剩bullets[0]避免机构agency语境被面向终端用户的收益淹没。bullet 1 和 2 只在 A4A 缺席时渲染因此如果面向直连站点所有者它们可以保持更亲切的第一人称语气。源码中 family-features.ts 的现有卡片可以作为文案范本例如jetpack-backup的三条 bullet 分别描述实时异地备份、一键恢复、变更活动日志jetpack-social描述自动发布、定时分享、老文章再曝光。每条 bullet 都单独用__()包裹让译者拿到的是完整句子而非碎片。c. 添加二次连接卡片数据family-features.ts在getSecondaryFeatureCardData()中添加一个case。二次连接的 bullet 描述的是附加管理员用户能获得的能力比所有者连接更窄case your-plugin-slug: return { title: __( Your Plugin Name ), bullets: [ __( What a secondary admin can do with this plugin, in audience-neutral voice. ), ], };恰好一条 bullet、受众中立语气、不提 SSO。二次连接卡片行必须扫描均匀——每张卡片都是一句管理口吻的文案getSecondaryFeatureCardData返回更多或更少的 bullet 都会让 test/family-features.test.ts 中的不变量测试失败。措辞要同时适配机构同事the clients site和站点共同所有者my site——优先使用this site/this store。不要列出 SSOSSO 只随完整 Jetpack 插件捆绑——A4A、Woo 以及各个jetpack-*子插件都不包含它——在别的卡片上提及它就是错误的而单独给通用 Jetpack 卡片加 SSO bullet 会破坏卡片行的统一外形。family-features.test.ts 用两条用例把上述规则固化为可执行约束getFeatureCardData对每个键返回非空标题且至少两条 bulletgetSecondaryFeatureCardData对每个键恰好返回一条 bullet并且所有 bullet 拼接后不包含SSO字样。d. 在 selector 中注册卡片键selectors.ts在 selectors.ts 的getFamilyCardKey()中添加一个case让单插件检测返回你的键case your-plugin-slug: return your-plugin-slug;getFamilyCardKey()对 Jetpack 家族做了特殊处理单个 Jetpack 子插件不带完整 Jetpack 插件获得单插件卡片以便文案更具体两个及以上子插件或任何未识别的子插件 slug则折叠回通用jetpack家族卡片。这与 scenarios.ts 中JETPACK_MULTI的折叠规则保持一致。getFeatureSelection()是卡片选择的最终入口先取有已知文案的最高优先级家族a4a、woo、jetpack封顶MAX_FEATURED_CARDS源码中定义为 3对应三方家族堆叠布局A4A 在上Woo Jetpack 在下再把每个家族映射到卡片键。唯一的other回退卡片只在没有任何已知家族时渲染空输入或只有未知插件的边界情况。e. 添加 Logo 映射feature-cards.tsx在 feature-cards.tsx 的getLogoForCardKey()中添加一个case。所有 Jetpack 家族卡片共用 Jetpack LogoWoo 和 A4A 使用各自的 Logocase your-plugin-slug: return JetpackLogo full size{ 32 } /;按设计要求每张卡片都使用完整品牌标识而非单圆变体Jetpack 家族卡片通用家族卡片和每个单插件覆盖共用同一个完整 Jetpack Logo让整个区域在插件组合变化时保持视觉一致插件特异性由 bullet 文案承担。A4A 和 Woo 各用完整的 wordmarkother回退卡片没有 Logobullet 文案本身就是视觉钩子。size{ 32 }使内联 SVG 标识与 features-section/style.scss 中imgLogo 的 CSS 强制height: 32px对齐保证每张卡片的品牌标识渲染高度一致。getConnectorFeatureCards()组装最终的卡片数组并返回heroFirstCard提示只要 A4A 作为主卡片出现FeaturesSection /就会把 A4A 卡片渲染为独占一行的全宽 hero其余卡片堆叠在其下方——即使在默认双列布局会把 A4A 与支撑卡片并排的 2 卡片场景中也是如此。getSecondaryAdminFeatureCards()复用同一套家族/优先级系统但 bullet 文案反映更窄的能力范围云管理、活动日志访问。第 4 步决定插件是否需要专属字幕场景字幕是Connect your account连接你的账户标题下方的描述性文字按场景预写让译者拿到完整的句子。大多数新插件不需要新场景。现有家族级场景已经覆盖多插件组合。只有当一个 Jetpack 子插件可以单独出现、且值得独特卖点文案时例如 Jetpack Backup 的开启实时备份才需要新场景。如果确实需要新场景a. 添加场景键scenarios.ts在 scenarios.ts 的SubtitleScenario类型中追加export type SubtitleScenario // ...existing scenarios... | YOUR_PLUGIN | OTHER_ONLY;SubtitleScenario共有 16 个键是场景的规范集合A4A_ONLY、A4A_WOO、A4A_JETPACK、ALL_THREE、WOO_ONLY、WOO_AND_PAY、WOO_JETPACK、JETPACK_FULL、JETPACK_BACKUP、JETPACK_PROTECT、JETPACK_BOOST、JETPACK_SEARCH、JETPACK_SOCIAL、JETPACK_VIDEOPRESS、JETPACK_MULTI、OTHER_ONLY。每个界面的预写字幕表都恰好以这些键为索引见copy.ts。注意刻意没有WOOPAY_ONLY场景WooPayments 硬依赖 WooCommerce 核心因此包含woocommerce-payments的 Woo 家族插件集必然同时包含woocommerce会路由到WOO_AND_PAY。但代码中仍保留了一个防御性 fall-through以处理 URL 截断等不可能但依然可能的畸形列表。b. 添加检测逻辑scenarios.ts把你的插件加进getJetpackSingleScenario()Jetpack 子插件或在getSubtitleScenario()中新增分支case your-plugin-slug: return YOUR_PLUGIN;getSubtitleScenario()的决策顺序自上而下多家族组合A4A Woo Jetpack按优先级排列单家族组合WooWooCommerce 与 WooPayments 同时出现 →WOO_AND_PAY其余包括畸形列表→WOO_ONLYJetpack区分完整 Jetpack / 单个子插件 / 两个及以上子插件。两个及以上子插件不含完整插件折叠为JETPACK_MULTI按设计复用完整 Jetpack 文案——单插件特异性交给特性卡片而非字幕A4A家族内只有一个插件。空输入或只有未知插件 →OTHER_ONLY。已知家族存在时未知other家族插件会被静默忽略不影响字幕文案。c. 为三个界面添加字幕文案copy.ts在 copy.ts 的三张字幕表中各添加一条getLoginSubtitles()—— Your site is registered with WordPress.com — finish connecting your account to {benefit}.你的站点已注册 WordPress.com——完成账号连接以{收益}。getAuthSubtitles()—— Your site is registered with WordPress.com — connecting your account gives it secure access to features from {plugin name}.你的站点已注册 WordPress.com——连接你的账号将使其安全访问{插件名}的功能。getSignupSubtitles()—— Youll use it to {benefit}.你将用它来{收益}。三个界面的定位差异值得注意auth 页面是唯一同时渲染动态FeaturesSection /的界面因此它的字幕回答隐含的我的站点已注册这还不够吗问题——通过点名活动插件、把连接框定为账号与插件之间的安全访问桥梁卡片则解释这些功能是什么。login 和 signup 不渲染卡片所以它们的字幕表保留更丰富的收益列表框架。JETPACK_MULTI在三个表中都复用JETPACK_FULL的字符串——插件组合的精确信息在特性区域呈现字幕停留在家族级总结。深层单插件场景Backup / Protect / Boost / Search / Social / VideoPress各有专属文案因为单个子插件的信息与家族级信息有本质不同。第 5 步二次连接文案copy.tsgetSecondaryAuthCopy()使用简化的家族级分支而非完整的 16 场景系统。getSecondaryAuthCopy( isAdmin, pluginSlugs )的逻辑非管理员连接主要启用 SSO因此无论插件如何都返回通用文案Connect to manage this site using your WordPress.com account.管理员则按家族组合分派——Jetpack Woo 同时存在、只有 Jetpack、只有 Woo、其他情况各有对应的精简字幕。如果你的插件属于现有家族现有字幕已经覆盖它。如果新增家族需要添加分支const hasYourFamily families.includes( your-family ); if ( hasYourFamily ) { subtitle __( Connect your account to access [your plugin benefits] for this site. ); }第 6 步复合头部 Logoplugin-registry.ts头部 Logo 由getLogoForFamilies()根据当前存在的家族选择。当前逻辑Woo A4A →jetpack-connect-all.svg仅 Woo →jetpack-connect-woo.svg仅 A4A →jetpack-connect-a8c.svg默认Jetpack / 其他→jetpack-connect.svg这些 SVG 资产位于 client/jetpack-connect/images/。源码注释说明该逻辑与 Jetpack 插件class-jetpack-connector.php中的 PHPget_connector_logo_url()相互镜像保证 Calypso 与 Jetpack 端保持对齐。如果你的插件引入了需要独立头部 Logo 的新家族在这里添加分支并创建 SVG 资产。第 7 步更新测试测试与各模块并列存放模块文件测试文件families.tstest/families.test.tsplugin-registry.tstest/plugin-registry.test.tsscenarios.tstest/scenarios.test.tsselectors.tstest/selectors.test.tsfamily-features.tstest/family-features.test.tscopy.tstest/copy.test.tsfeature-cards.tsx../test/feature-cards.test.tsxauthorize.jsx../test/authorize.js运行完整测试套件yarn test-client client/jetpack-connect/connection-content/test/ yarn test-client client/jetpack-connect/test/feature-cards.test.tsx yarn test-client client/jetpack-connect/test/authorize.js快速参考不同家族类型各需改哪些文件步骤Woo 插件Jetpack 子插件A4A 插件其他families.ts自动前缀自动前缀自动前缀添加分支plugin-registry.ts添加条目添加条目添加条目添加条目FeatureCardKey类型否若需单插件卡片否否getFeatureCardData()否若需单插件卡片否否getSecondaryFeatureCardData()否若需单插件卡片否否getFamilyCardKey()否若需单插件卡片否否getLogoForCardKey()否若需单插件卡片否否SubtitleScenario否若需独特字幕否否getSubtitleScenario()否若需独特字幕否否copy.ts字幕否若需独特字幕否否getSecondaryAuthCopy()否否否若新增家族getLogoForFamilies()否否否若需新 Logo二次连接信号has_connected_owner 与 already_authorized二次连接内容的触发链路是站点已有连接所有者时Jetpack 插件的Manager::get_authorization_url()发出has_connected_owner1信号Calypso 侧 authorize.jsx 的isSecondaryConnection()读取authQuery.hasConnectedOwner做出判断authorize.jsx。在渲染层面authorize.jsxconnector 分支会依据isSecondary与isAdmin的组合分派非管理员的二次连接不渲染卡片SSO 是唯一收益字幕已传达管理员二次连接调用getSecondaryAdminFeatureCards()首次连接调用getConnectorFeatureCards()。Tracks 埋点中calypso_jpc_approve_click与授权流程事件都会带上is_secondary_connection与is_admin_connection属性authorize.jsx便于后续分析连接漏斗。而already_authorized1信号代表当前 WP 用户已关联 wpcom 账号重入路径由Webhooks::handle_connect_url_redirect()发出作用于renderNotices()、按钮文案、自动重定向等逻辑与本指南的插件感知二次内容相互独立。现有家族接入的 TL;DR对现有家族而言加一条PLUGIN_REGISTRY条目就够了。前缀匹配的家族分类、家族级卡片、字幕场景会自动处理其余一切。只有当插件单独出现且值得独特文案时才需要添加单插件覆盖per-plugin override。赞分享前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载相关推荐wp-calypso Jetpack Connect 指南从 from 路由分支到插件感知的统一连接流wp calypso Jetpack Connect 指南从 from 路由分支到插件感知的统一连接流 本指南围绕 client/jetpack connec前端CMSwp-calypso Tracks 事件埋点实践指南从 calypso-analytics 包到 Analytics Middleware 的完整接入方案wp calypso Tracks 事件埋点实践指南从 calypso analytics 包到 Analytics Middleware 的完整接入方案 本前端CMS深入解析 wp-calypso 的 QueryJetpackConnection /Jetpack 站点连接状态的声明式数据获取组件深入解析 wp calypso 的 QueryJetpackConnection / Jetpack 站点连接状态的声明式数据获取组件 导读 QueryJ前端CMS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
