Calypso Guided Tours 示例导览：用 simple-payments-end-of-year-guide 掌握 Tour 与 Selector 的构建之道

前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载导读本文以 client/layout/guided-tours/docs/examples/README.md 为骨架深入剖析 CalypsoWordPress.com 的 JavaScript 单页应用中 Guided Tours 示例目录的组织方式与实战用法。你将学会如何在config.js中挂载一个示例 Tour、如何将归档的示例 Tour 作为新 Tour 的起点复制到tours目录、如何遵循selector 随 Tour 归档/回迁的工程约定并通过simple-payments-end-of-year-guide这个完整示例读懂 Guided Tours 框架中Tour、Step、Continue、Next、Quit等核心元素的真实写法。一、示例目录的定位灵感库与起点模板client/layout/guided-tours/docs/examples/是 Guided Tours 框架的示例陈列室。按 README.md 的定位这个目录同时存放两类示例Tour 示例完整可运行的引导流程定义以 JSX 元素树编写Selector 示例用于判定何时触发 Tour、当前步骤是否可展示的 Redux selector。它们的用途有两个作为灵感来源inspiration以及作为新 Tour 的起点starting points。这意味着示例并不需要时刻保持与生产代码同步而是作为可持续沉淀、复用的素材库存在。从仓库结构看当前示例目录下只有一个 Tour 文件 simple-payments-end-of-year-guide.jsx其兄弟文档 TUTORIAL.md、API.md、ARCHITECTURE.md 则提供了从零构建 Tour 的完整方法论示例目录正是这套方法论的具体落地样本。二、如何运行一个示例 Tour示例本身不会自动出现在产品中需要开发者手动接入。README 给出了两条核心操作路径1. 直接试用加入 config.js要试运行某个示例 Tour把它导入并挂载进 client/layout/guided-tours/config.js。该文件目前采用 ES Module 的import ... from calypso/layout/guided-tours/tours/.../meta形式并以数组导出全部 Tour 的 meta 信息例如import checklistSiteTitle from calypso/layout/guided-tours/tours/checklist-site-title-tour/meta; // ... export default [ checklistSiteTitle, jetpackChecklist, jetpackMonitoring, // ... mediaBasicsTour, ];若要让示例 Tour 生效参考 TUTORIAL.md 的做法先按name键把 Tour 注册进config.js旧版配置写法或追加到上述数组再在 all-tours.js 的combineTours列表中加入 Tour 本体同时为对应环境如config/development.json添加guided-tours/tour-name: true这样的 feature flag。重点提醒feature flag 是保证 Tour 只在特性齐全的环境中触发的关键尤其是desktop环境其上下文与通用 Calypso 不同发布周期也不同。2. 作为起点复制到 tours 目录如果要以某个示例为基础开发自己的 Tour把它复制到client/layout/guided-tours/tours目录即示例 README 中提到的../../tours指向的位置。当前 tours 目录下已有 9 个正式 Tourchecklist-site-title-tour、jetpack-checklist-tour、jetpack-monitoring-tour、jetpack-plugin-updates-tour、jetpack-sign-in-tour、jetpack-site-accelerator-tour、jetpack-video-hosting-tour、marketing-connections-tour、media-basics-tour每个都由meta.js元数据与index.jsx/index.tsxTour 元素树组成可作为参照系。3. 归档约定Selector 随 Tour 迁移README 特别强调了一项工程约定当把一个不再使用的 Tour 归档为示例时要把仅被该 Tour 使用的 selectors 一并移入 Tour 自身文件以免它们继续影响构建流程。反过来当你引入一个用到这些 selector 的新 Tour 时记得把它们移回其应属的位置例如state/guided-tours/contexts。这一约定保证了示例目录中的代码可以被安全地隔离不参与生产构建而一旦被复活依赖关系也能被正确归位。仓库中 make-tour.js 通过static meta omit( tree.props, children )提取 Tour 的静态元数据正是这种Tour 自带所需数据设计的一个侧面体现。三、示例 Tour 深度拆解simple-payments-end-of-year-guide该示例是 Guided Tours 用于Simple Payments简单支付功能的年终促销型引导它在多种路径下触发但只针对有 Simple Payments 功能权限的站点引导用户完成创建页面 → 插入 Simple Payments 按钮 → 设置标题 → 发布的完整流程。3.1 触发条件path when 的组合Tour namesimplePaymentsEndOfYearGuide version20171103 path{ [ /stats, /plans, /pages, /posts, /media, /comments, /types, /themes, /sharing, /people, /plugins, /settings, ] } when{ and( isDesktop, hasSimplePaymentFeature ) } nameTour 唯一名称camelCase用于框架内部引用与?tourTOURNAME强制触发version版本号仓库惯例使用 YYYYMMDD 格式日期此处为 20171103path触发路径前缀可以是字符串或数组——本例覆盖了 Calypso 侧边栏的主要管理分区whenRedux selector 函数判定是否触发。这里用and组合了isDesktop来自automattic/viewport与站点功能判断。hasSimplePaymentFeature是本 Tour 自带 selector 的典范它完整复现了归档时 selector 随 Tour 迁移的约定import { FEATURE_SIMPLE_PAYMENTS } from automattic/calypso-products; import siteHasFeature from calypso/state/selectors/site-has-feature; import { getSelectedSiteId } from calypso/state/ui/selectors; const hasSimplePaymentFeature ( state ) { const siteId getSelectedSiteId( state ); return siteHasFeature( state, siteId, FEATURE_SIMPLE_PAYMENTS ); };and工具函数定义在 utils.jsconditions.every( cond cond() )即所有条件为真才通过且具有短路求值特性。按 API.md 的建议组合条件时应注意顺序——把计算代价低、最容易否决的条件放在前面以便尽早退出。3.2 步骤编排render prop 与定位系统simple-payments-end-of-year-guide共 5 步完整展示了 Guided Tours 步骤编写的主要技巧第一步initplacementright无 target面向全屏的欢迎语包含插图、ButtonRow按钮组和Link外链。这是 Tour 的第一印象负责说服用户参与Step nameinit placementright { ( { translate } ) ( Fragment p{ translate( Prepare for holiday shopping … ) }/p ButtonRow Next stepadd-new-page{ translate( Get started! ) }/Next Quit{ translate( No thanks. ) }/Quit /ButtonRow Link href{ localizeUrl( https://wordpress.com/support/pay-with-paypal/ ) } { translate( Learn more about Pay with PayPal. ) } /Link /Fragment ) } /Step注意children是render prop渲染函数框架在步骤实际渲染时才求值从而避免为所有 Tour 静态实例化 JSX 与翻译字符串——这是 TUTORIAL.md 明确指出的性能设计。而Step的 TypeScript 实现step.tsx也印证了这一点children: FunctionComponent{ translate }并把canSkip默认设为true。第二步add-new-pagetarget arrow placement style通过 CSS selector 把步骤粘到侧边栏添加页面按钮上Step nameadd-new-page arrowleft-top targetli[data-post-typepage] a.sidebar__button placementbeside style{ { marginTop: -15px } } p{ translate( To add a payment button, create a page. ) }/p Continue click stepeditor-intro targetli[data-post-typepage] a.sidebar__button { translate( Click {{strong}}Add{{/strong}} to continue., { components: { strong: strong / } } ) } /Continue /Step这里用到两类定位目标方式详见 API.md 的 Targeting elements in Calypsodata-tip-target属性推荐目标元素加data-tip-targetsome-nameTour 里直接用该名字框架通过[data-tip-target${target}]查询CSS selector当target含.、#或空格时框架直接把它当作标准 selector 传给document.querySelector例如本例的li[data-post-typepage] a.sidebar__button与后面用于定位编辑器按钮的.editor-html-toolbar__button-insert-content-dropdown, .mce-wpcom-insert-menu button。Continue组件监听目标 DOM 节点的click事件点击后跳转到editor-intro步骤。位置计算由 positioning.ts 的getStepPosition、posToCss等实现把坐标换算为步骤元素的 CSS 定位属性。第三、四、五步editor-introplacementcenter无 target介绍编辑器editor-insert-button用arrowtop-leftplacementbelow指向插入内容的下拉按钮注意这里的 target 是一个用逗号分隔的两个 selector用于兼容新旧编辑器界面editor-set-title指向.editor-title最终步骤publish指向.editor-ground-control__publish-button鼓励用户发布并用Quit primary收尾同时提供Learn about managing menus的Link外链。在style上的克制使用示例中多处出现style{{ marginTop: -15px }}之类的微调这正是 TUTORIAL.md 强调的原则——仅在自动定位视觉重心偏了几像素时做小幅修正应尽量少用甚至不用以保持 Guided Tours 全局样式的一致性。四、从示例到框架理解底层机制4.1 决策算法actionLog 与 selector 级联Guided Tours 的状态由 ARCHITECTURE.md 描述的actionLogRedux action 的时间戳列表最多保留 50 条会话内不持久化驱动。Tour 的选择是一串createSelector级联getGuidedTourState └── findEligibleTour ├── findOngoingTour └── findTriggeredTour └── getToursFromFeaturesReached优先级依次为进行中的 Tour 被显式请求的 Tour?tourname 可被触发的 Tour。findTriggeredTour的核心逻辑是reachedTours - seenTours到达过的减去看过的再对剩余候选逐个执行when( state )取第一个有效者。这也是示例 Tour 只在特定路径、特定功能条件下触发的机制根源。4.2 触发方式三途径按 API.md一个 Tour 有三种触发途径用户导航到匹配path的 URL 且when求值为真每用户仅自动触发一次URL 携带?tourTOURNAME查询参数忽略path、when与历史记录适合通过邮件/聊天分享?tourreset可重置历史dispatch Redux actionrequestGuidedTour( tour )同样忽略路径、条件与历史。4.3 makeTour用 context 注入动态状态示例中的makeTour( Tour…)包裹器实现在 make-tour.js它返回一个TourContextProvider类组件通过static getDerivedStateFromProps组装tourContext包含next、quit、step、branching、isLastStep、tour、tourVersion、dispatch等再用TourContext.Provider把动态数据提供给整棵 JSX 树。早年的React.cloneElement方案因每次渲染都克隆、生命周期易出 bug被弃用context 方案让 Tour 作者只需写静态 JSX无需手工传递动态 props。4.4 Step 的其它高级属性从 step.tsx 的AcceptedProps可见完整属性面除target/placement/arrow/style外还有wait返回 Promiseresolve 后才展示步骤、waitForTarget目标可见才渲染如 marketing-connections-tour 的用法、onTargetDisappear目标消失时回调可决定quit或next、shouldScrollTo/scrollContainer目标不可见时滚动容器如.sidebar__region、when/next步骤级条件与跳过目标等。示例中虽未全部用到但理解这些属性有助于基于示例做扩展。五、调试与验证让示例跑起来DEBUGGING.md 提供了针对示例/新 Tour 不按预期触发的排查指南与示例目录直接相关Tour 只出现一次Tour 显示后会写入用户的 guided tours 历史不再重复出现。开启调试输出localStorage.setItem( debug, calypso:guided* )框架按eligibleTours reachedTours - seenTours计算若 Tour 已在seen中需要重置历史。重置历史当前没有系统的清理入口可通过应用仓库自带的 clean-history.patch 实现在仓库根目录执行git apply client/layout/guided-tours/docs/patch/clean-history.patch刷新页面清理历史后再移除该 patch。仅在?tourname下显示依次检查——用户偏好是否缺失调试输出应出现No fresh user preferences, bailing.常见原因是 2FA token 过期可访问/me处理Tour path指定的路径是否真的被访问应出现在reachedTours调试输出中when触发函数以及步骤级when条件。对于本示例 Tour可以在本地 Calypso 开发环境如yarn start下用?toursimplePaymentsEndOfYearGuide强制触发绕开path/when/历史记录直接预览流程需注意该示例的文件扩展名为.jsx作为归档示例并未挂载到 config.js需按上文加入 config.js一节接入后才可经查询参数触发。六、结语simple-payments-end-of-year-guide虽然只是一次性的年终广告型引导却被完整归档为示例恰恰因为它覆盖了 Guided Tours 的大部分核心 API多路径触发、and组合 selector、render prop步骤内容、CSS selector 定位、Continue/Next/Quit/Link/ButtonRow的协同以及selector 随 Tour 归档的工程约定。对照 TUTORIAL.md 的先定目标、再定步骤、再定触发流程这个示例就是一套可直接复制、替换文案与目标选择器即可上线的新 Tour 蓝本若要深入了解状态决策与定位原理可继续研读 ARCHITECTURE.md 与 API.md。赞分享前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载相关推荐浏览器资源嗅探扩展猫抓3 步保存网页里的音视频文件浏览器资源嗅探扩展猫抓3 步保存网页里的音视频文件 猫抓cat catch是一款开源浏览器资源嗅探扩展它监听当前页面的网络请求把其中的音视频资源自动列前端CMSwp-calypso Guided Tour 组件指南基于 Context 构建应用内交互式引导教程wp calypso Guided Tour 组件指南基于 Context 构建应用内交互式引导教程 导读 本文聚焦 wp calypso 仓库中负责「应用内前端CMS深入解析JSONWebToken.swift理解JWT算法和签名机制终极指南深入解析JSONWebToken.swift理解JWT算法和签名机制终极指南 JSON Web TokenJWT作为现代Web应用中最流行的身份验证机制之前端CMS上一篇【免费下载】 推荐开源项目LlamaParse - 文件解析与高效检索的得力助手下一篇样式表入门用DuiLib_Ultimate美化界面的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考