前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载导读在 WordPress.com 的阅读器Reader中当用户从文章流点击一篇文章时会进入一个专注阅读的“全文视图”Full Post。本文以 wp-calypso 仓库中 client/reader/full-post/README.md 为骨架结合 client/reader/full-post/controller.jsx、client/blocks/reader-full-post/index.jsx 等源码完整梳理该功能的两种路由形态、控制器到组件的渲染链路、组件 Props 契约以及阅读时长统计、已读标记、键盘导航等底层交互实现帮助读者理解并二次开发这一阅读器核心模块。一、全文章视图的两种路由形态根据 client/reader/full-post/README.md 的定义Reader 的全文视图存在两类路径分别对应两种数据来源Feed 文章RSS 等外部 Feed/reader/feeds/:feed_id/posts/:feed_item_id博客文章WordPress.com 或 Jetpack 站点/reader/blogs/:blog_id/posts/:post_id两者的区别在于资源的归属Feed 文章以feed_id feed_item_id唯一定位而博客文章以blog_id post_id唯一定位。这个区别贯穿了整个功能的实现——从路由注册、控制器取值到组件内文章 Key 的构造和“标记已读”的接口调用。路由注册两条路由在 client/reader/full-post/index.js 中注册使用了 Reader 自有的readerPage路由器来自calypso/reader/lib/reader-router并串入若干中间件export default function () { // Feed full post readerPage( /reader/feeds/:feed/posts/:post, blogDiscoveryByFeedId, redirectLoggedOutToSignup, sidebar, feedPost, makeLayout, clientRender ); // Blog full post readerPage( /reader/blogs/:blog/posts/:post, redirectLoggedOutToSignup, sidebar, blogPost, makeLayout, clientRender ); }这里有几个值得注意的细节Feed 路由额外挂载了blogDiscoveryByFeedId中间件来自calypso/reader/controller。由于 Feed 文章本身没有站点信息需要先通过 feed ID 完成“博客发现”discovery才能渲染站点头像、关注按钮等依赖站点数据的 UI。博客文章路由则不需要该步骤因为路径中直接带有 blog ID。两条路由都经过redirectLoggedOutToSignup未登录跳转到注册/登录流程和sidebar渲染 Reader 侧边栏最终由makeLayoutclientRender完成布局与客户端渲染。路由参数:feed、:blog、:post会被解析进context.params供控制器使用。二、控制器参数解析与异步加载控制器位于 client/reader/full-post/controller.jsx分别导出blogPost与feedPost两个处理函数。blogPost博客文章控制器export function blogPost( context, next ) { const blogId context.params.blog; const postId context.params.post; const basePath /reader/blogs/:blog_id/posts/:post_id; const fullPageTitle analyticsPageTitle Blog Post blogId postId; let referral; if ( context.query.ref_blog context.query.ref_post ) { referral { blogId: context.query.ref_blog, postId: context.query.ref_post }; } trackPageLoad( basePath, fullPageTitle, full_post ); context.primary ( AsyncLoad require{ loadReaderFullPost } blogId{ blogId } postId{ postId } referral{ referral } placeholder{ null } / ); scrollTopIfNoHash(); next(); }关键点query 参数传递 referral来源回引当 URL 形如/reader/blogs/123/posts/456?ref_blog789ref_post10时控制器会把{ blogId, postId }作为referral传入组件。这个 referral 用于把全文视图与来源流中的卡片如 Discover pick card关联起来实现“从哪来、回哪去”的导航体验。异步按需加载通过AsyncLoad组件动态加载calypso/blocks/reader-full-postwebpack 分包名为async-load-calypso-blocks-reader-full-post避免全文组件进入主包、拖慢首屏加载期间placeholder{ null }不显示占位骨架。页面统计trackPageLoad用basePath参数模板而非真实值记录页面加载fullPageTitle为Reader Blog Post {blogId} {postId}。滚动复位scrollTopIfNoHash()在 URL 无 hash 时将窗口滚动回顶部延后 0ms 执行确保 DOM 更新完成。若带 hash如#comments则交给组件内部的评论锚点逻辑处理。feedPostFeed 文章控制器export function feedPost( context, next ) { const feedId context.params.feed; const postId context.params.post; const basePath /reader/feeds/:feed_id/posts/:feed_item_id; const fullPageTitle analyticsPageTitle Feed Post feedId postId; trackPageLoad( basePath, fullPageTitle, full_post ); context.primary ( AsyncLoad require{ loadReaderFullPost } feedId{ feedId } postId{ postId } placeholder{ null } / ); scrollTopIfNoHash(); next(); }与blogPost的差异在于传入的是feedId而非blogId且不解析 referral query。这也解释了为什么组件设计上feedId与blogId是互斥可选的关系。三、渲染组件FullPostContainer → FullPostView 的层级结构README 指出“用于渲染页面的组件位于 blocks/reader-full-post”。该目录下组件文件众多整体渲染层级为FullPostContainer顶层容器读取 Feed 数据 └── withFullPostNavigation(ConnectedFullPostView)导航数据注入 └── ConnectedFullPostViewRedux HOC 连接 └── FullPostView核心视图组件 ├── ReaderFullPostHeader标题/元信息头 ├── ReaderFullPostActionBar评论/点赞/标记已读/关注操作条 ├── ReaderFullPostFeaturedImage特色图 ├── ContentProcessor LinkPreview正文渲染与链接预览 ├── ReaderPostActions文章底部操作 ├── Comments评论区块 ├── ReaderFullPostNavigation上一篇/下一篇导航 └── RelatedPostsFromSameSite / RelatedPostsFromOtherSites相关文章顶层容器Feed 数据装配client/blocks/reader-full-post/index.jsx 的默认导出FullPostContainer负责读取 Feed 信息export default function FullPostContainer( props ) { const { data: feed } useFeedQuery( props.feedId ); const follow useSiteSubscriptionForFeed( props.feedId ); const feedWithIcon feed ? { ...feed, site_icon: follow?.site_icon } : feed; return FullPostWithNavigation { ...props } feed{ feedWithIcon } /; }它通过useFeedQuery获取 Feed 数据并把站点订阅信息中的site_icon合并进 feed以便头部渲染站点图标。导航数据注入withFullPostNavigationwithFullPostNavigation是一个高阶组件HOC负责把“上一篇/下一篇”能力接进全文视图用usePost来自calypso/reader/data/post按文章 Key 拉取当前文章、referral 文章以及前后文章数据用useStreamPostKeySelection从当前流stream中选取前后文章的 Key用useCanMarkSeen判断当前文章是否支持“标记已读”用usePostCommentsApiDisabled判断评论 API 是否被禁用外部 Feed 文章为enabled: false通过navigationUrlFor预计算前后导航卡片的落地 URL。这里对 X-post交叉转载文章做了特殊处理流内条目只是本地站点的 “X-post: …” 占位 stub用户实际会跳转到原始站点文章因此预计算的 URL 会指向原始blog_id/post_id见 index.jsx保证中键/新标签页打开的落地页与点击一致。Redux 连接mapStateToFullPostPropsmapStateToFullPostProps负责把 Redux 状态映射为组件 Propsconst { feedId, blogId, postId } ownProps; const postKey pickBy( { feedId: feedId, blogId: blogId, postId: postId } );pickBy会剔除空值因此实际生效的文章 Key 只包含有值的那一组字段——Feed 文章是{ feedId, postId }博客文章是{ blogId, postId }。这正对应 README 中两条路由的本质差异。组件同时注入previousRoute用于关闭时回退和referralStream用于统计事件中的 pathname override。四、组件 Props 契约依据 blocks 目录 READMEclient/blocks/reader-full-post/README.md 对组件 Props 给出了正式契约必填 PropsProp类型说明blogIdstring/number文章的 blog idpostIdstring/number文章的 post idonClosefunction关闭全文视图的事件处理函数可选 PropsProp类型说明referralobject包含blogId和postId的对象Referral 的用途README 特别说明referral 对象用于把全文视图与文章流中的来源卡片关联起来当前的实际使用场景是把 Discover pick 卡片链接到全文视图。在源码中referral 经过两条路径生效mapStateToFullPostProps中若ownProps.referral存在则将ownProps.referralPost透传为referralPostprop在FullPostView.render()中referralPost被传入ReaderFullPostHeader用于头部展示来源上下文。注意上层控制器blogPost会把?ref_blogref_postquery 组装成referral而组件内部再通过usePost( props.referral )拉取 referral 文章的完整数据见withFullPostNavigation。除了文档列出的 PropsFullPostView的 propTypesindex.jsx还声明了更多内部注入项layoutdefault | recent控制默认布局与最近浏览布局、canMarkSeen、commentsApiDisabled等它们由 HOC 和 Redux 连接层注入外部无需关心。五、正文渲染内容处理与链接预览全文视图的核心是正文渲染。FullPostView用ContentProcessor包裹正文内容content-processor.tsxexport default function ContentProcessor( { content }: ContentProcessorProps ): JSX.Element | null { // If no content, return null if ( ! content ) { return null; } // Detect URL in the content. const url detectUrls( content ); return ( div classNamereader-full-post__story-content dangerouslySetInnerHTML{ { __html: content } } / { url LinkPreview url{ url } / } / ); }正文 HTML 通过dangerouslySetInnerHTML注入数据来自 Reader API属可信内容同时detectUrls会扫描正文中的裸链接并渲染LinkPreview卡片。URL 检测有三层防线content-processor.tsx跳过含媒体元素的正文若内容含img|video|audio|iframe则不做链接预览避免干扰富媒体阅读纯文本 URL 检测用正则/(https?:\/\/[^\s])/g找出裸链接并通过isUrlInHtmlTag排除位于 HTML 标签内部的 URLhref 属性检测匹配a href...链接文本/a仅当链接文本本身也是 URL、且不是提及或#话题时才提取 URL 用于预览。此外还有isValidUrl校验仅允许http:/https:且 hostname 含点从源头上过滤掉javascript:等非法协议。其他正文相关细节特色图去重仅当post.featured_image存在且! isFeaturedImageInContent( post )即特色图没有内嵌在正文中时才渲染ReaderFullPostFeaturedImage避免图片重复显示。摘录降级当post.use_excerpt为真时正文区渲染PostExcerpt并追加PostExcerptLink“阅读原文”链接而不是完整正文。文本方向自适应正文用AutoDirection包裹按内容语言自动切换 LTR/RTL 排版。iframe 自适应高度挂载时通过WPiFrameResize为正文容器内的嵌入 iframe 设置正确高度this.postContentWrapper.current并在卸载时移除监听。六、交互实现操作条、评论与键盘快捷键操作条Action Baraction-bar.jsx 渲染评论、点赞、“查看原文”、标记已读与关注按钮评论按钮仅在showComments ! commentsApiDisabled时显示点赞按钮通过isLikeable( post )判断外部 RSS 文章is_external不可点赞“View original”按钮始终指向post.URL新标签页打开relexternal noopener noreferrer“标记已读/未读”按钮仅在canMarkSeen为真时由父组件注入渲染关注按钮用SubscribeWithShelfButton其feedUrl优先于siteUrl作为关注目标。标记已读的底层实现markAsSeenindex.jsx再次体现了 Feed 与 Blog 的分支Feed 文章调用requestMarkAsSeen({ feedId, feedUrl, feedItemIds, globalIds })博客文章调用requestMarkAsSeenBlog({ blogId, postIds, globalIds })。组件还通过maybeMarkAsSeenOnLoad保证“每篇文章最多自动标记一次”并处理canMarkSeen在挂载后才变为 true 的时序问题。评论区块评论渲染在reader-full-post__comments-wrapper内条件为! commentsApiDisabled ( isCommentsOpen( post ) || isLoginRequiredToComment( post ) || post.discussion?.comment_count 0 )。评论组件参数值得关注initialSize若 URL 带#comment-{id}锚点则初始加载全部评论便于定位到锚点评论否则加载 10 条pageSize25、maxDepth1单层嵌套回复展示“回复箭头”样式shouldPollForNewComments由配置项reader/comment-polling控制开启后轮询新评论shouldHighlightNew高亮新增评论。URL 锚点#comments或#comment-{id}会被checkForCommentAnchor/getCommentIdFromUrl解析触发scrollToComments平滑滚动并聚焦评论输入框focusTextArea: true。键盘快捷键handleKeydown在document上监听捕获阶段提供完整的快捷键体系index.jsx按键动作Esc关闭全文视图并返回handleBackl点赞 / 取消点赞→或j下一篇←或k上一篇快捷键会避开以下场景通知面板打开时、焦点在输入控件INPUT/SELECT/TEXTAREA或 contentEditable 区域时、焦点在 popover 内时、以及按了meta/ctrl组合键避免与命令面板cmdk冲突。前后文章导航ReaderFullPostNavigationpost-navigation.tsx渲染上一篇/下一篇卡片其 URL 由上层navigationUrlFor预计算后传入postUrlprop卡片本身不做 X-post 解析。点击卡片走goToPostrecent 布局下更新选中项setSelectedItemdefault 布局下调用showSelectedPost切换文章。导航过程会记录calypso_reader_article_navigation_clicked事件附带directionprevious/next。七、阅读行为埋点与“已读”语义全文视图是 Reader 中埋点最密集的场景之一FullPostView通过recordTrackForPost上报多类事件且全部带context: full-post事件触发时机calypso_reader_article_opened文章加载完成首次展示pathname 覆盖为 referral 来源流calypso_reader_article_engaged_time阅读时长毫秒换算为秒含path与挂载路径calypso_reader_article_scroll_depth离开页面/切后台/切换文章时上报最大滚动深度百分比calypso_reader_article_exit_before_completion未读到 90% 即离开时上报calypso_reader_article_fast_exit阅读时长低于预估阅读时长minutes_to_read * 60的 25% 时上报“快速退出”calypso_reader_article_closed关闭全文视图calypso_reader_article_liked / unliked点赞/取消键盘触发时带event_source: keyboard埋点机制依赖ScrollTrackerscroll-tracker.ts它会寻找最近的滚动容器向上遍历 DOM 检查overflow-y: auto/scroll并在窗口与容器之间切换统计目标。visibilitychange监听确保用户切后台时立即结算阅读时长与滚动深度。“已读”语义还有一层attemptToSendPageView在文章与站点均就绪且非错误状态时调用markPostSeen( post, site )并setViewingFullPostKey把当前文章标记为正在阅读卸载时通过unsetViewingFullPostKey清除。八、测试与占位组件测试覆盖client/blocks/reader-full-post/test/ 下按模块拆分测试index.test.jsx通过 mock 掉usePostCommentsApiDisabled、usePost、useStreamPostKeySelection、useCanMarkSeen与 stats 模块聚焦测试FullPostView、mapStateToFullPostProps和withFullPostNavigation的核心逻辑如评论展示条件、文章 Key 组装content-processor.tsx验证 URL 检测、链接预览的触发与过滤逻辑link-preview.tsx、header-meta.jsx、featured-image.jsx、scroll-tracker.ts、wp-iframe-resize.js分别覆盖对应子模块。这说明全文视图具备良好的可测性数据层全部通过 Hooks 注入视图组件可以被替换 mock埋点模块也被统一隔离。加载占位加载态由 placeholders/ 提供content.jsx与header.jsx两个骨架屏post._state pending时头部显示ReaderFullPostHeaderPlaceholder正文区显示ReaderFullPostContentPlaceholder同时DocumentHead标题在加载期显示 “Loading”。期间 App Banner 会被禁用maybeDisableAppBanner文章加载完成且无错误后再重新启用。九、常见开发场景小结基于以上实现二次开发时可直接利用以下既有能力新增一种全文视图入口参照 client/reader/full-post/index.js 用readerPage注册新路由复用feedPost/blogPost控制器模式与AsyncLoad异步加载把流内卡片链到全文视图构造/reader/blogs/:blog_id/posts/:post_id?ref_blogref_postURLreferral 机制会自动建立来源关联调整评论初始展示修改Comments的initialSize/pageSize/maxDepth参数新增阅读行为指标参照trackReadingTime/trackScrollDepth的模式用recordTrackForPost上报带context: full-post的自定义事件控制评论与已读能力开关分别使用usePostCommentsApiDisabled与useCanMarkSeen的结果做条件渲染。如需深入了解各子组件可继续阅读 client/blocks/reader-full-post/ 目录下的源码与测试以及 Reader 路由体系 client/reader/controller.js、client/reader/lib/reader-router 的相关实现。赞分享前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载相关推荐wp-calypso Reader Full Post 组件完全指南Props、Referral 机制与源码级解析wp calypso Reader Full Post 组件完全指南Props、Referral 机制与源码级解析 导读 Reader Full Post 是前端CMSwp-calypso Reader 文章操作栏Reader Post Actions组件完全指南Props、条件渲染与源码解析wp calypso Reader 文章操作栏Reader Post Actions组件完全指南Props、条件渲染与源码解析 本篇技术指南以 wp ca前端CMSwp-calypso Plugins 模块架构解析路由、控制器与插件管理视图wp calypso Plugins 模块架构解析路由、控制器与插件管理视图 本文以 wp calypso 仓库中 client/my sites/plugi前端CMS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考