9.6 KiB
9.6 KiB
目标与口径
将 AKSRT 小工具系统中 12 个小工具对照 Zibll(仅参考"(新)"模块,忽略一切"旧版即将删除")做全量 1:1 复刻:后台配置项(字段、类型、选项、默认值、依赖、min/max/step、分组小标题)与前端 DOM/样式/状态全部对齐参考主题。已确认口径:
- 专题全部移除:本项目无 topics 分类法,12 个小工具范围内所有"专题限制"字段与
PostQuery的 topics 查询分支一并删除,测试同步更新。 - 修正参考源码明显 bug 的文案(如排序 label 颠倒、最近评论 style 默认值 'card' 不在选项中),数据值与行为保持一致。
- 省略 AKSRT 无法支撑的排序选项(销售价格/积分售价/销售数量),排序值域 = views/like/comment_count/favorite/modified/date/rand。
- 新增"搜索式多选+拖拽排序"分类选择字段(terms 类型)。
- 不写双路/迁移;清理被替换的死代码;不做 Docker 视觉验收;不改 37 个 slug 与 REST 路由形态。
复用基础(已核实)
- 文章 item DOM 契约已在
inc/helpers/posts-renderer/markup.php(posts-item/posts-mini/badges/meta,9.0 契约);main.css已含.zci-*、.zps-*、.graphic*等 Zibll 同款 CSS(76 处命中);frontend.css:179-228已有 tab/slider 的 Zibll 契约块;runtimemain.js已有.swiper-scroll/.new-swiper初始化。复刻 = 补齐缺失部分并对齐 markup,而非从零移植。 - 前次复刻先例:tab_posts/slider/buttons/notice 走
FrontendRenderer"特殊壳"路径(before_widget + reference_title + 内容自闭环),本次 12 个中需要 Zibll 壳的一并加入该列表。
实施步骤
Phase A 基础设施
FieldSchema.php/FormRenderer.php:新增terms字段类型(动态 get_terms 分类选项、搜索过滤、拖拽排序、按选择顺序保存 int 数组;支持 taxonomy 参数以供合作伙伴的链接分类复用);spinner/slider 渲染unit后缀(此前 unit 是死键)。PostQuery.php:删除 topics 分支;tabs 段支持zibpay_type(数组,沿用 apply_pay_type 映射 1/2/5/6);orderby 值域与 allowlist 对齐。PostRenderer.php:分页三态对齐 Zibll ——''→隐藏.ajax-pag.hide占位、ajax→"加载更多".ajax-pag .next-page.ajax-next、number→.pagenav.ajax-pag数字页码(全部带ajaxpager-target=".widget-ajaxpager"契约,REST 数据属性保留);mini_opt应用于 posts;热榜从通用分支拆出专用渲染。FrontendRenderer.php:特殊壳列表加入posts, oneline_posts, hot_posts, term_cards, term_aggregation, media_cards, combo_info, partners, recent_comments, posts_toc。frontend.js:移植/新增 ①IAS IntersectionObserver 懒加载(列表load_mode=ajax与加载更多自动触发,替代 Zibll lazysizes ias);②合作伙伴滚动初始化(测量 seed 组宽→克隆→--zps-duration,resize 重算,Zibll main.js:4204-4296);③幻灯片组合卡 footer 重算--cover-ratio(widget-slider.php:848-875);④目录树逻辑(section-navs 移植:h1-h4 抓取、排除.item-heading/.no-nav、wznav_{i}、scrollspy offset 105、>380px 折叠、hash 定位);保持 role=status/aria-busy/reduced-motion a11y 契约。admin.js/admin-core.js/admin.css:terms 字段交互(搜索、拖拽排序、选序同步)。
Phase B 逐个小工具(schema+render+CSS+JS+空态,均以参考文件为准逐字段移植)
| # | AKSRT slug | 参考定义(行号) | 要点 |
|---|---|---|---|
| 1 | posts 文章列表 | widget-posts.php:1881-2006 | load_mode radio(detail/ajax 默认 ajax)、cat(reference_ids)、zibpay_type checkbox、limit_day、orderby、order、style(list/card/mini)+mini_opt、count 4..20 默认 12、paginate radio ''/ajax/number;壳 widget-main-post mb20 style-X(mini 加 zib-widget posts-mini-lists);删旧 tag_ids/paginate select |
| 2 | tab_posts 多栏目文章 | widget-posts.php:2008-2155 | tabs 子字段 title/cat/zibpay_type/limit_day/orderby/order;移除 topics;删除现有 legacy post_ajax_trigger 双路,翻页三态;mini 骨架含缩略图变体 |
| 3 | oneline_posts 横向滚动文章 | widget-posts.php:2157-2234 | cat/zibpay_type/orderby/order/style 默认 card/count;移除 limit_day/paginate/autoplay(参考无);swiper-scroll DOM 已对齐,清 data-autoplay |
| 4 | hot_posts 热榜文章 | widget-posts.php:1803-1851 + zib-posts-list.php:769-888 | orderby radio 4 榜单、limit_day、count 默认 6、target_blank;zib-widget hot-posts、TOP1 大图+linear-mask+TOP 徽章(jb-red/jb-yellow/b-gray)、行布局与计数文案(人收藏/人点赞/条讨论/人已阅读);删 show_thumbnail/通用样式字段 |
| 5 | term_cards 分类图文卡片 | widget-posts.php:1565-1694 + functions.php:1939-2046 | 模块级 obs_animation/animation_repeat(common.animation 关)、terms 选择器、type style-1..4、height_scale、pc_row(1/2/3/4/6/12 默认 2)/m_row、mask_opacity 默认 10、target_blank;row gutters-5 + graphic hover-zoom-img + --cover-height-scale + graphic-mask,style-2/3/4 文案差异与 tooltip;新建共享助手 aksrt_graphic_card()(inc/helpers),term 分类默认封面回退 |
| 6 | term_aggregation → 改名"分类聚合卡片" | widget-posts.php:1696-1801 + zib-category.php:606-751 | 仅分类(去标签/专题):模块级动画、pc_row slider 1..2 默认 2、terms、orderby/order、count 1..20 默认 4、target_blank;移植 zib-widget term-aggregation(term-img+img-badge 浏览合计、term-title/meta/更多文章、按 orderby 的行内 meta、--delay 交错);Catalog 名称/描述/共同字段更新;服务端仅 category |
| 7 | media_cards 图文视频封面卡片 | widget-more.php:2005-2191 | 模块级动画、pc_row/m_row(1..12,默认 4/2)、mask_opacity、height_scale 默认 30、font_size_pc/m、font_bold、font_color、covers group{image,video,hide,title,link};widget-graphic-cover + this-font 变量 + 移动端回退图片;删旧 description/image_dark 卡片字段 |
| 8 | slider_media_combo 幻灯片加图文视频卡片 | widget-slider.php:361-887 | 模块级动画;补 5 个 subheading 分组;option 默认值逐项核对(源文件为准);m_layout_type=default 时 m_row=pc_row;clamp 上限 4/6 修正;footer 重算 JS 接入 |
| 9 | partners 横向滚动合作伙伴 | widget-more.php:2317-2581 | rows/m_rows 1..6 默认 3、style_type card/logo/chip、card_width/height(依赖)、card_bg/card_radius、speed slider 0.1..10 步 0.1、direction/pause_hover/show_widget_bg/go_link/end_fade、link_type(link 类别多选用 terms 类型 taxonomy=link_category/link_limit/link_orderby/page_links_order)、partners group{title,desc,image,link};zps-* DOM、round-robin 行分配、get_bookmarks 来源、go_link 走 aksrt_go_link、CSS 动画(已有)+JS 初始化 |
| 10 | combo_info 复合信息卡片 | widget-more.php:2583-2833 | 模块级动画、pc_row 2/3/4/6 默认 4、m_row 1/2、pc_gap/m_gap(gutters)、card_radius、top_band/top_band_height、go_link、cta_text/cta_color、cards group{title,icon,icon_image,tags 嵌套 group{text,color},desc,link,cta_text,cta_color,band_color auto/7色};zci-* DOM + band auto 循环 + --delay 交错;markup 改挂到已有 .aksrt-combo-info-card CSS;删 aksrt-combo-card 死代码 |
| 11 | recent_comments 最近评论 | widget-more.php:3315-3363 + zib-comments-list.php:340-407 | limit 1..50 默认 8、outer/outpost、show_source 默认 false、style radio(''简约/style_2 风格2,默认修正为 '');box-body comment-mini-lists zib-widget + comment-widget-item(avatar box、昵称+icon-spot 时间、点赞、con-link text-ellipsis-5、style_2 盒装、来源行);复用 inc/helpers/aksrt-comments.php 时间/头像,内容过滤图片→[图片] |
| 12 | posts_toc 文章目录树 | widget-more.php:445-532 | 改旧式字段:title 默认"文章目录"、mini_title、in_affix(删 min_headings/collapsed/offset);渲染空占位 .posts-nav-box[data-title];目录构建/scrollspy/折叠全部移入 frontend.js;.posts-nav-lists CSS 若缺则从 main.css:4835-4946 补 |
Phase C 死代码清理
- 删除被替换的渲染分支与 CSS:aksrt-term-cards、aksrt-term-aggregation、aksrt-combo-card、aksrt-widget-partners 旧轨、aksrt-widget-media-cards/comments/toc/pagination/load-more 旧标记、tab_posts legacy trigger、hot_posts 的 show_thumbnail、oneline 的 autoplay;
media_card_fields()仍被 knowledge_product 组使用故保留,仅解除 12 个目标对它的引用。
Phase D 测试与校验
tests/widget-system/run.php:query_contract 移除 topics、加 tab zibpay_type;modern_widget_contract 扩充 12 个的 schema/DOM 断言;保持既有断言全绿。- 新增
tests/widget-system/zibll-parity-widgets-contract.test.cjs(node --test 源码 token 契约:每 widget 的字段 id 清单、关键 DOM 类、CSS token、frontend.js 行为、死类负向断言)。 - 更新受影响的 zibll-modern-widgets / post-visual / a11y 契约测试(保持 aria-busy、role=status、reduced-motion)。
- 重新生成
tests/fixtures/widget-golden-v1.json(php tools/generate-widget-golden-fixture.php)并跑 php tools/validate-widget-golden.php(不带 --require-results)。 - 验证:
php -l全部改动 PHP;node --test tests/widget-system/全量;composer dump-autoload -o(优先不新增类,仅改现有文件)。
明确不做
不做旧设置迁移与双路渲染;不做真实视觉/Docker 验收;不参考"(旧版即将删除)"模块;不改 37 slug 顺序、REST 路由形态、其他 25 个小工具。
主要参考文件
zibll:inc/widgets/widget-posts.php、widget-more.php、widget-slider.php、inc/functions/{zib-posts-list,zib-category,functions}.php、js/section-navs.js、js/main.js、css/main.css;AKSRT:src/WidgetSystem/*、inc/helpers/*、assets/widgets/*、tests/widget-system/*。