前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载本文以 client/jetpack-connect/AGENTS.md 及其关联的 connection-content/README.md 为主体深入剖析 wp-calypso 中 Jetpack Connect 模块的实现骨架/jetpack/connect/*路由下的from参数分支、驱动授权页行为的两个 URL 信号、集中式的授权查询解析管线以及支撑「统一连接流」的插件感知plugin-aware内容系统。读完本文你将掌握如何为 Unified Jetpack Connector 流程注册新插件、如何理解并扩展授权页的分支逻辑以及如何运行该模块的测试与静态检查。模块定位Jetpack Connect 是什么Jetpack Connect源码位于 client/jetpack-connect/是 wp-calypso 中面向用户的连接流程集合通过 Jetpack Connection 包把自托管self-hosted的 WordPress 站点连接到 WordPress.com覆盖 authorize授权、login登录、signup注册、install远程安装与 SSO单点登录五个环节。它的关键特征在于流量入口绝大多数页面渲染在/jetpack/connect/*路径下由远端站点上运行的 Jetpack 插件发出的重定向进入。也就是说Jetpack 插件在站点后台生成授权 URL用户点击后被带到 Calypso 的连接页完成授权后再跳回站点——Calypso 侧是这个握手流程的「接待方」。从目录结构list_files 可见来看模块由三类文件组成页面组件authorize.jsx授权页核心、signup.jsx、sso.jsx、install-step.jsx、remote-credentials.jsx等基础设施schema.js授权查询参数 schema、utils.js参数解析与工具函数、constants.js、controller.jsx、persistence-utils.js、woo-dna-config.js插件感知内容系统connection-content/子目录内含families.ts、plugin-registry.ts、scenarios.ts、selectors.ts、copy.ts、family-features.ts与配套测试。流路由Flow Routingfrom参数决定一切授权页authorize.jsx通过 URL 上的from查询参数选择视觉呈现。高层分支如下摘自 AGENTS.mdfrom值分支含义说明jetpack-connector统一连接流connector 分支插件感知走connection-content/唯一支持二次连接secondary connection的分支jetpack-onboarding统一流程无插件感知卡片通过isUnifiedConnectionFlow()与 connector 分支共享 wrappermy-jetpack、connect-after-checkout旧版 My Jetpack 连接/重连页面遗留 surfacewoocommerce-core-profiler、woocommerce-onboarding、woocommerce-services-auto-authorize、woocommerce-setup-wizard以及任何wooDnaConfig().isWooDnaFlow()命中Woo JPC / Woo DNA 流程WooCommerce 系引导流ssoJetpack SSO 授权握手对应sso.jsx各插件专属重定向jetpack-boost*、jetpack-backup*、jetpack-search*、jetpack-social*、jetpack-videopress*、blaze-ads*、automattic-for-agencies-client*、jpo*、connection-ui*、jetpack-partner-coupon*、wpcom-migration*用authorize.jsx中专门的isFrom…()辅助函数处理大多数在授权后直接 pass-through 重定向回 wp-admin其他任何值默认 Calypso 授权卡片渲染jetpack-connect__logged-in-card新增from值时的官方推荐做法AGENTS.md 明确要求优先扩展统一的jetpack-connector流程并把插件登记到connection-content/而不是新增一个isFrom…()分支。这保证了新插件自动获得 logo、副标题、特性卡片等全套内容而不是重新手写一套页面逻辑。授权页信号already_authorized与has_connected_owner授权页行为由两个 URL 信号塑造修改authorize.jsx、utils.js或schema.js时务必区分清楚信号发射方Jetpack 插件侧Calypso prop含义消费者already_authorized1Jetpack 插件的Webhooks::handle_connect_url_redirect()authQuery.alreadyAuthorized当前 WP 用户已关联到一个 wpcom 账户重入路径renderNotices()屏蔽ALREADY_CONNECTED_BY_OTHER_USER提示handleSubmit()的 go back 分支getButtonText()显示 Go back to your sitegetScreenReaderAuthMessage()在该分支有意提前返回与按钮文案配对抑制 SR 状态文本UNSAFE_componentWillReceiveProps()对已在站点列表上的用户自动重定向has_connected_owner1Jetpack 插件的Manager::get_authorization_url()authQuery.hasConnectedOwner站点已有任何连接所有者当前查看的 WP 用户可能是也可能不是该所有者isSecondaryConnection()门控把 connector 分支翻转成二次连接内容getSecondaryAuthCopy()、getSecondaryAdminFeatureCards()两个信号相互独立——可以同时出现在同一 URL 上且互不蕴含对方。文档明确警告不要把has_connected_owner加到非 connector 的门控上也不要让already_authorized的覆盖范围跨分支蔓延这一「过载」已被解开参见 PR #110763 / jetpack#48904。从源码看两个信号的解析utils.js的authQueryTransformer()client/jetpack-connect/utils.js把原始查询字符串转换为authQueryprops其中alreadyAuthorized: !! queryObject.already_authorized, hasConnectedOwner: !! queryObject.has_connected_owner,而schema.jsclient/jetpack-connect/schema.js为二者声明了{ type: string }属性即只接受字符串类型的参数值其他类型会被 schema 校验拒绝。解析管线parseAuthorizationQuery()使用makeJsonSchemaParser( authorizeQueryDataSchema, authQueryTransformer )懒加载构造解析器坏输入会抛出SchemaError或TransformerError并被捕获返回null。授权查询参数schema 与 transformer 双闸门client/jetpack-connect/schema.js 定义了authorizeQueryDataSchema其中required 字段缺失即校验失败为_wp_nonce、blogname、client_id、home_url、redirect_uri、scope、secret、site、site_url、state可选字段节选均标注了类型约束或取值约定参数类型/约束语义client_idpattern: ^\\d$wpcom 客户端 ID必须为纯数字字符串partner_idpattern: ^\\d$合作伙伴 IDclose_window_after_login/close_window_after_auth1为真登录/授权完成后关闭弹窗authorize.jsx的UNSAFE_componentWillMount中据此window.close()is_popup1为真是否弹窗流程already_authorized/has_connected_ownerstring上文两个信号fromstring流分支选择redirect_after_authstringvalidUrl.isWebUri校验授权后重定向地址skip_user已废弃即将移除旧参数被allow_site_connection取代allow_site_connection1为真允许站点连接installed_ext_success1为真Woo 核心向导安装扩展后是否显示成功提示plugins逗号分隔字符串插件 slug 列表驱动插件感知内容plugin_namestring临时参数用于 WooCommerce 核心中的 Jetpack AI / Boost A/B 测试实验结束后移除color_scheme、site_icon、site_lang、user_email、jp_version、woodna_service_name、woodna_help_url等string品牌化与站点信息关键约定授权查询解析是集中式的——authQueryTransformer()utils.js是把原始查询字符串变成authQueryprops 的唯一位置schema.js则把守哪些参数被接受。新增参数必须同时在这两处添加在 schema 中声明属性、在 transformer 中映射转换。plugins参数在 transformer 中被split( , )、trim()并过滤空串最终成为string[]。插件感知内容系统connection-content/统一连接流fromjetpack-connector是插件感知的根据站点传回的plugins查询参数选择 logo、副标题、特性卡片与二次连接文案。其数据流connection-content/README.md 中的 ASCII 图如下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家族Family分类families.ts 定义了四种家族a4a | woo | jetpack | other并按优先级数组FAMILY_PRIORITY [ a4a, woo, jetpack, other ]决定文案与卡片的展示层级A4A 最优先其次 Woo、Jetpack、其他。getFamilyFromSlug()采用前缀匹配automattic*→a4awoocommerce*→woojetpack或jetpack-*→jetpack其余 →other未知插件永远不会阻断连接流——回落到other家族仅在没有任何已知家族时渲染一个通用兜底卡片。插件注册表plugin-registry.ts 维护PLUGIN_REGISTRYslug →{ slug, family, displayName, isFullJetpack? }。内置条目包括Jetpack 家族jetpackisFullJetpack: true仅主插件、jetpack-backupJetpack VaultPress Backup、jetpack-protect、jetpack-boost、jetpack-search、jetpack-social、jetpack-videopressWoo 家族woocommerce、woocommerce-paymentsWooPaymentsA4A 家族automattic-for-agencies-client。注册表是增量式的未知 slug 一律优雅回退通过getFamilyFromSlug解析家族而不是依赖条目存在。getPluginDisplayName()在注册表缺失时直接返回原始 slug 作为显示名——流程不会坏只是不够精致。getLogoForFamilies()依据存在的家族组合选择头部合成 logo与 Jetpack 插件侧 PHPget_connector_logo_url()逻辑保持一致保证 Calypso 与 Jetpack 对齐Woo A4A →jetpack-connect-all.svg仅 Woo →jetpack-connect-woo.svg仅 A4A →jetpack-connect-a8c.svg默认Jetpack/其他→jetpack-connect.svg特性卡片选择selectors.ts 提供决策函数getPresentFamilies()/getTopFamilies()按优先级去重排序默认上限MAX_FEATURED_CARDS 3与三家族堆叠布局一致isStore()任一 Woo 家族插件活跃时返回 true是文案中称呼「store」还是「site」的唯一决策点hasFullJetpack()完整 Jetpack 插件是否在活跃列表中决定用「完整 Jetpack」还是「单插件」文案变体getFeatureSelection()优先取有文案的高优先级家族a4a / woo / jetpack映射为卡片键。Jetpack 家族特殊规则只有单个 Jetpack 子插件且无完整 Jetpack时才授予 per-plugin 卡片两个及以上子插件或未识别的单插件回落到通用的jetpack家族卡片镜像scenarios.ts的JETPACK_MULTI折叠规则。没有任何已知家族时返回[other]兜底卡片。实战为统一连接流注册一个新插件以下步骤完整继承自 connection-content/README.md是添加插件到fromjetpack-connector授权/登录/注册流程或其二次连接变体的官方路径。现有家族内插件通常只需一步如果你的插件落入现有家族A4A、Woo 或 Jetpack前缀匹配让大部分系统自动工作。只需在PLUGIN_REGISTRY添加条目your-plugin-slug: { slug: your-plugin-slug, family: woo, // 或 jetpack、a4a displayName: Your Plugin Name, },若 slug 属于已知家族但前缀不标准例如 Woo 扩展叫payments-gateway则在getFamilyFromSlug()中补一个分支。Jetpack 家族插件注意只有主 Jetpack 插件设置isFullJetpack: true子插件一律省略该标志。需要专属特性卡片时仅 Jetpack 子插件卡片分两档家族级卡片如woo、jetpack完整插件或多个同族插件活跃时使用大多数新插件适用与per-plugin 卡片如jetpack-backup、jetpack-social仅当恰好单个 Jetpack 子插件活跃时使用可写得高度具体。若要 per-plugin 卡片依次改动a. 添加FeatureCardKeyfamily-features.tsexport type FeatureCardKey | a4a | woo | jetpack // ...existing keys... | your-plugin-slug // ← add here | other;b. 添加首次连接卡片数据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 在活跃插件中时getConnectorFeatureCards()../feature-cards.tsx会把每张支持卡片裁剪到只剩bullets[0]避免代理商语境被终端用户导向的利益点淹没。第 2、3 条 bullet 仅在无 A4A 时渲染可以用更贴近个人口吻的措辞。c. 添加二次连接卡片数据getSecondaryFeatureCardData()新 casecase 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 会破坏统一形状。d. 在选择器中注册卡片键getFamilyCardKey()新 case使单插件检测返回你的键case your-plugin-slug: return your-plugin-slug;e. 添加 logo 映射getLogoForCardKey()新 casefeature-cards.tsxcase your-plugin-slug: return JetpackLogo full size{ 32 } /;Jetpack 家族卡片共用 Jetpack logoWoo 与 A4A 使用各自品牌 logo。需要专属副标题场景时副标题是「Connect your account」标题下方的描述文字按场景预写完整句子以方便翻译。大多数新插件不需要新场景——现有家族级场景已覆盖多插件组合只有「可单独出现且值得独特卖点」的 Jetpack 子插件如 Jetpack Backup 的「启用实时备份」才需要。a. 添加场景键scenarios.ts的SubtitleScenario类型export type SubtitleScenario // ...existing scenarios... | YOUR_PLUGIN | OTHER_ONLY;b. 添加检测逻辑Jetpack 子插件加入getJetpackSingleScenario()或为getSubtitleScenario()新增分支case your-plugin-slug: return YOUR_PLUGIN;c. 为三个 surface 添加副标题字符串copy.ts中三张副标题表各加一条getLoginSubtitles()— Your site is registered with WordPress.com — finish connecting your account to {benefit}.getAuthSubtitles()— Your site is registered with WordPress.com — connecting your account gives it secure access to features from {plugin name}.getSignupSubtitles()— Youll use it to {benefit}.二次连接文案与合成头部 logogetSecondaryAuthCopy()copy.ts使用简化的家族级分支不是完整 16 场景系统。现有家族内的插件已有现成副标题只有新增家族时才加分支const hasYourFamily families.includes( your-family ); if ( hasYourFamily ) { subtitle __( Connect your account to access [your plugin benefits] for this site. ); }若新家族需要独立头部 logo在getLogoForFamilies()plugin-registry.ts加分支并创建对应 SVG 资源参见上文 logo 组合逻辑。更新测试测试与各模块同目录存放模块测试文件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测试与命令AGENTS.md 给出模块级的开发命令yarn test-client client/jetpack-connect # 运行 jetpack-connect 全部测试 yarn test-client client/jetpack-connect/test/authorize.js yarn test-client client/jetpack-connect/connection-content/test/ yarn eslint client/jetpack-connect/file连接内容子系统的完整测试套件connection-content/README.mdyarn 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目录约定与最佳实践模块继承 client/AGENTS.md 的全部约定并额外强调authorize.jsx是遗留 class 组件使用UNSAFE_componentWillMount/UNSAFE_componentWillReceiveProps。修改时保留connect()HOC localize()包裹与authQueryPropTypes形状该目录下新增组件仍应为 TypeScript 函数组件从connection-content/*.ts全是 TS 模块、feature-cards.tsx等可见这一趋势。授权查询解析集中化authQueryTransformer()utils.js是唯一把原始查询字符串转为authQueryprops 的地方schema.js 把守参数白名单。新增参数须两处同步。插件感知内容系统有独立走查文档动connection-content/*.ts或feature-cards.tsx前先读 connection-content/README.md。Tracks 事件统一使用calypso_jpc_*前缀例如authorize.jsx中埋点的calypso_jpc_authorize_form_view、calypso_jpc_auth_view。新增from值的首选路径是扩展统一jetpack-connector流而不是新增isFrom…()分支AGENTS.md 的明确指引。现有家族插件接入速查表来自 connection-content/README.md 的速查表按插件类型对照「需要改动什么」步骤Woo 插件Jetpack 子插件A4A 插件其他families.ts自动前缀自动前缀自动前缀加分支plugin-registry.ts加条目加条目加条目加条目FeatureCardKey类型否若要 per-plugin 卡片否否getFeatureCardData()否若要 per-plugin 卡片否否getSecondaryFeatureCardData()否若要 per-plugin 卡片否否getFamilyCardKey()否若要 per-plugin 卡片否否getLogoForCardKey()否若要 per-plugin 卡片否否SubtitleScenario否若要专属副标题否否getSubtitleScenario()否若要专属副标题否否copy.ts副标题否若要专属副标题否否getSecondaryAuthCopy()否否否若新增家族getLogoForFamilies()否否否若需新 logoTL;DR现有家族插件只需在PLUGIN_REGISTRY添加一条——基于前缀的家族分类、家族级卡片与副标题场景会自动接管其余一切。只有「插件单独出现且值得独特文案」时才需要 per-plugin 覆盖。小结Jetpack Connect 模块的设计精髓在于「集中 分层」URL 信号与from参数集中决定行为分支schema.jsutils.js双闸门集中管参数connection-content/把品牌内容按 family → scenario → card 分层组织。理解这套骨架后无论是排查授权握手问题、新增插件接入还是扩展新的from流程都能在清晰的路径上完成同时保持与 Jetpack 插件侧 PHP 逻辑Manager::get_authorization_url()、Webhooks::handle_connect_url_redirect()、get_connector_logo_url()的语义对齐。赞分享前端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前端CMS深入 wp-calypso 的 jetpack-connector 连接流程从插件注册到品牌化授权界面的完整接入指南深入 wp calypso 的 jetpack connector 连接流程从插件注册到品牌化授权界面的完整接入指南 本指南以 client/jetpack前端CMS深入解析 wp-calypso 的 QueryJetpackConnection /Jetpack 站点连接状态的声明式数据获取组件深入解析 wp calypso 的 QueryJetpackConnection / Jetpack 站点连接状态的声明式数据获取组件 导读 QueryJ前端CMS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考