3.2.30: 文章目录进后台(新增「自动目录」标签页)—— 位置/插入点/默认展开可配,手写 [TOC] 永远优先

后台「主题设置」新增第 5 个标签页「自动目录」,7 个选项:
  目录位置   正文中间 / 页面左侧(浮动)/ 页面右侧(浮动)
  添加方式   手动(只认 [TOC])/ 自动
  自动插入位置  文章开头 / 第一个 H1、H2 之前 / 文章结尾
  默认状态   默认显示 / 默认隐藏
  另外:目录标题、收录层级(H1~H4)、是否显示序号

设计要点:
- 插入方式拆成 toc_mode(manual/auto) x toc_anchor(start/first/end) 两个正交
  字段,不合成一个四值下拉:侧栏模式下插入位置毫无意义,合并会产生歧义。
- 手写 [TOC] 绝对优先:yang_toc_plan() 里 $has_marker 最先返回,inline_at
  ='marker' 且 rail=false —— 否则同一篇会出现两份目录,老文章升级后突然多
  出一个目录。这条是刻意守住的。
- 纯函数 + 薄壳分层:normalize_settings / plan / inject / build_list 全部不查库,
  单进程可喂几十种组合;settings() 只负责读库 + 调纯函数 + static 缓存。
- <details open> 是唯一可靠的「默认收起」手段:展开态不接受 CSS 覆盖,只能
  由 open 属性决定,所以隐藏时必须不输出该属性。
- 侧栏收起态必须 translateX(±100%) 完全移出视口:只做 opacity 会让透明面板
  留在原位吃掉正文点击(探针 elementFromPoint 才抓得到)。
- yang_toc_rail_ready() 开关:侧栏在 wp_footer 输出,那时正文可能没走
  the_content(缓存插件/OEmbed),标题没 id ⇒ 侧栏链接全跳不动却看起来正常。
  宁可不出侧栏。
- 后台联动隐藏「插入位置」不用 jQuery show()/hide():会把 .section 的行内
  display 写成 block,悄悄回退 3.2.28 的 display:flow-root BFC 修复。改用
  class + display:none!important。

验证(全部在本轮重跑):
  _test_toc.php       53/0   旧 TOC 行为回归
  _toc330_logic.php   88/0   逻辑判据
  _toc330_falsify     13/13  注入全变红且红对地方
  _geo330_rail.js     73/0   侧栏真实几何(左/右 x 展开/收起 x 宽窄屏)
  _geo330_falsify     8/8
  _guard330.php       46/0   后台控件与运行时默认值双向一致
  _guard330_falsify   8/8
  _admin330_tab_check 36/0   新标签页几何 + 联动 + 载入态
  _admin330_falsify   8/8
  _admin328_check     13/0   3.2.28 布局回归

发布:只发 zip + readme + update.json 到 theme-update/,不动服务器主题目录,
用户在 WP 后台自行升级(沿用 3.2.24 起的策略)。
This commit is contained in:
2026-10-25 12:18:52 +08:00
parent 677de0f24e
commit 6f51d50a58
7 changed files with 1060 additions and 91 deletions
@@ -100,6 +100,22 @@ jQuery(document).ready(function ($) {
jQuery('#section-top_describe').show()
}
// 自动目录:只有「目录位置 = 正文中间」时,插入位置才有意义。
// 侧栏模式(左/右)下它完全无效 —— 若还留着这个下拉框,用户会以为
// 「选了文章结尾却没插进正文」是个 bug。
//
// 用 class 切换而不是 fadeIn/fadeOut:.section 的 display 是 flow-root
// (3.2.28 靠它建独立 BFC,避免被左侧浮动标签列的 clear:both 拉长)。
// jQuery 的 show()/hide() 会写行内 display,把那套布局打回 block,
// 等于悄悄回退 3.2.28 的修复。
function yq_toggle_toc_anchor () {
var center = jQuery('#toc_place').val() === 'center'
jQuery('#section-toc_anchor').toggleClass('yq-cond-hide', !center)
}
jQuery('#toc_place').on('change', yq_toggle_toc_anchor)
yq_toggle_toc_anchor()
// Loads the color pickers
$('.of-color').wpColorPicker()