refactor: 增强代码可读性 - 添加结构化注释

style.css:
- 添加 CSS 变量定义区块注释
- 添加主题色系统、动画系统分区
- 添加夜间模式、沉浸式主题色分区
- 添加框架样式覆盖、基础样式分区

argontheme.js:
- 添加文件头目录索引
- 添加 10 个功能模块的分区注释
- 为工具函数添加 JSDoc 注释
- 统一注释风格

argontheme.js

@@ -1,9 +1,24 @@
 /*!
  * Argon 主题核心 JavaScript
+ * 
+ * 目录:
+ * 1. 兼容性修复 - 第三方库 polyfill
+ * 2. 全局配置 - argonConfig 初始化
+ * 3. 工具函数 - Cookie、翻译等
+ * 4. 顶栏功能 - 透明度、搜索
+ * 5. 侧边栏 - 浮动、滚动
+ * 6. 文章列表 - 瀑布流布局
+ * 7. 浮动按钮 - 回顶、设置
+ * 8. 评论系统 - 发送、回复、编辑
+ * 9. 代码高亮 - Prism 增强
+ * 10. PJAX - 页面无刷新加载
  */
 
-// ========== 兼容性修复 ==========
+// ==========================================================================
-// 确保 Prism 和 autoloader 存在
+// 1. 兼容性修复 - 确保第三方库存在
+// ==========================================================================
+
+// Prism 代码高亮
 if (typeof window.Prism === 'undefined') {
     window.Prism = { 
         highlightAll: function() {},
@@ -21,21 +36,19 @@ if (typeof window.Prism.plugins.autoloader === 'undefined') {
     };
 }
 
-// 确保 Zoomify 存在
+// Zoomify 图片缩放
 if (typeof window.Zoomify === 'undefined') {
     window.Zoomify = function() {};
     window.Zoomify.DEFAULTS = {};
 }
 
-// 确保 jQuery 插件存在
+// jQuery 插件
 if (typeof jQuery !== 'undefined') {
     (function($) {
-        // 确保 zoomify 插件存在
         if (typeof $.fn.zoomify === 'undefined') {
             $.fn.zoomify = function() { return this; };
         }
         
-        // 确保 fancybox 存在
         if (typeof $.fancybox === 'undefined') {
             $.fancybox = {
                 defaults: {
@@ -57,7 +70,6 @@ if (typeof jQuery !== 'undefined') {
             };
         }
         
-        // 确保 pjax 存在
         if (typeof $.pjax === 'undefined') {
             $.pjax = function() {};
             $.pjax.defaults = {
@@ -76,20 +88,39 @@ if (typeof jQuery !== 'undefined') {
     })(jQuery);
 }
 
-// ========== 原有代码 ==========
+// ==========================================================================
+// 2. 全局配置
+// ==========================================================================
+
 if (typeof(argonConfig) === "undefined"){
 	var argonConfig = {};
 }
 if (typeof(argonConfig.wp_path) === "undefined"){
 	argonConfig.wp_path = "/";
 }
-/*Cookies 操作*/
+
+// ==========================================================================
+// 3. 工具函数
+// ==========================================================================
+
+/**
+ * 设置 Cookie
+ * @param {string} cname - Cookie 名称
+ * @param {string} cvalue - Cookie 值
+ * @param {number} exdays - 过期天数
+ */
 function setCookie(cname, cvalue, exdays) {
 	let d = new Date();
 	d.setTime(d.getTime() + (exdays * 24 * 60 * 60 * 1000));
 	let expires = "expires=" + d.toUTCString();
 	document.cookie = cname + "=" + cvalue + ";" + expires + ";path=/";
 }
+
+/**
+ * 获取 Cookie
+ * @param {string} cname - Cookie 名称
+ * @returns {string} Cookie 值
+ */
 function getCookie(cname) {
 	let name = cname + "=";
 	let decodedCookie = decodeURIComponent(document.cookie);
@@ -106,7 +137,7 @@ function getCookie(cname) {
 	return "";
 }
 
-/*多语言支持*/
+// ---------- 多语言翻译系统 ----------
 var translation = {};
 translation['en_US'] = {
 	"确定": "OK",
@@ -302,7 +333,11 @@ function __(text){
 	return translation[lang][text];
 }
 
-/*根据滚动高度改变顶栏透明度*/
+// ==========================================================================
+// 4. 顶栏功能
+// ==========================================================================
+
+// ---------- 顶栏透明度随滚动变化 ----------
 !function(){
 	let toolbar = document.getElementById("navbar-main");
 	let $bannerContainer = $("#banner_container");
@@ -379,7 +414,7 @@ function __(text){
 	document.addEventListener("scroll", changeToolbarTransparency, {passive: true});
 }();
 
-/*搜索*/
+// ---------- 搜索功能 ----------
 function searchPosts(word){
 	if ($(".search-result").length > 0){
 		let url = new URL(window.location.href);
@@ -488,7 +523,11 @@ $(document).on("change" , ".search-filter" , function(e){
 	});
 });
 
-/*左侧栏随页面滚动浮动*/
+// ==========================================================================
+// 5. 侧边栏
+// ==========================================================================
+
+// ---------- 侧栏随滚动浮动 ----------
 !function(){
 	if ($("#leftbar").length === 0){
 		let contentOffsetTop = $('#content').offset().top;
@@ -573,7 +612,11 @@ if (argonConfig.headroom === "true"){
 	}).init();
 }
 
-/*瀑布流布局*/
+// ==========================================================================
+// 6. 文章列表布局
+// ==========================================================================
+
+// ---------- 瀑布流布局 ----------
 function waterflowInit() {
 	if (argonConfig.waterflow_columns === "1") {
 		return;
@@ -681,7 +724,10 @@ if (argonConfig.waterflow_columns !== "1") {
 	});
 }();
 
-/*浮动按钮栏相关 (回顶等)*/
+// ==========================================================================
+// 7. 浮动操作按钮
+// ==========================================================================
+
 !function(){
 	// 确保 DOM 和 jQuery 已加载
 	if (typeof jQuery === 'undefined') {
@@ -924,9 +970,12 @@ if (argonConfig.waterflow_columns !== "1") {
 	});
 }();
 
-/*评论区 & 发送评论*/
+// ==========================================================================
+// 8. 评论系统
+// ==========================================================================
+
 !function(){
-	//回复评论
+	// ---------- 回复评论 ----------
 	let replying = false , replyID = 0;
 	function reply(commentID){
 		cancelEdit(false);
@@ -2278,8 +2327,12 @@ if ($("html").hasClass("banner-as-cover")){
 	});
 }
 
-/*Pjax*/
+// ==========================================================================
-let pjaxScrollTop = 0, pjaxLoading = false;
+// 10. PJAX 无刷新加载
+// ==========================================================================
+
+let pjaxScrollTop = 0;
+var pjaxLoading = false;
 $.pjax.defaults.timeout = 10000;
 $.pjax.defaults.container = ['#primary', '#leftbar_part1_menu', '#leftbar_part2_inner', '.page-information-card-container', '#rightbar', '#wpadminbar'];
 $.pjax.defaults.fragment = ['#primary', '#leftbar_part1_menu', '#leftbar_part2_inner', '.page-information-card-container', '#rightbar', '#wpadminbar'];

style.css

@@ -11,6 +11,11 @@
 
 @charset "utf-8";
 
+/* ==========================================================================
+   CSS 变量定义 (CSS Custom Properties)
+   ========================================================================== */
+
+/* ---------- 主题色系统 ---------- */
 :root {
 	--themecolor: #5e72e4;
 	--themecolor-R: 94;
@@ -99,31 +104,36 @@
 	--color-border-on-foreground-deeper: #eee;
 	--color-text-deeper: #212529;
 	--color-selection: #cce2ff;
-	/* ========== 统一动画系统 - 桌面端和移动端一致 ========== */
+	
-	/* 动画时长 - 基于 Material Design 3 规范 */
+	/* ---------- 动画系统 (Material Design 3) ---------- */
+	/* 动画时长 */
 	--animation-instant: 100ms;
 	--animation-fast: 150ms;
 	--animation-normal: 250ms;
 	--animation-slow: 400ms;
 	--animation-slower: 600ms;
-	/* 缓动函数 - Material 3 标准曲线 */
+	
+	/* 缓动函数 - 标准曲线 */
 	--ease-standard: cubic-bezier(0.2, 0, 0, 1);
 	--ease-standard-decelerate: cubic-bezier(0, 0, 0, 1);
 	--ease-standard-accelerate: cubic-bezier(0.3, 0, 1, 1);
 	--ease-emphasized: cubic-bezier(0.2, 0, 0, 1);
 	--ease-emphasized-decelerate: cubic-bezier(0.05, 0.7, 0.1, 1);
 	--ease-emphasized-accelerate: cubic-bezier(0.3, 0, 0.8, 0.15);
-	/* 弹性缓动 - 用于交互反馈 */
+	
+	/* 缓动函数 - 弹性曲线 */
 	--ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
 	--ease-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);
 	--ease-smooth: cubic-bezier(0.4, 0, 0.2, 1);
-	/* 状态层透明度 - Material 3 */
+	
+	/* 状态层透明度 */
 	--state-hover-opacity: 0.08;
 	--state-focus-opacity: 0.12;
 	--state-pressed-opacity: 0.12;
 	--state-dragged-opacity: 0.16;
 }
 
+/* ---------- 夜间模式配色 ---------- */
 html.darkmode body {
 	--color-background: #282828;
 	--color-foreground: #424242;
@@ -138,8 +148,8 @@ html.darkmode body {
 	--color-selection: #607799;
 }
 
+/* ---------- AMOLED 夜间模式 ---------- */
 html.darkmode.amoled-dark body,
-
 html.darkmode.amoled-dark.immersion-color body {
 	--color-background: #111;
 	--color-foreground: #000;
@@ -150,10 +160,11 @@ html.darkmode.amoled-dark.immersion-color body {
 	--color-border-on-foreground-deeper: #252525;
 	--color-text-deeper: #eee;
 	--color-selection: #607799;
---color-darkmode-toolbar: 0, 0, 0;
+	--color-darkmode-toolbar: 0, 0, 0;
 	--color-darkmode-banner: #131313;
 }
 
+/* ---------- 沉浸式主题色 (日间) ---------- */
 html.immersion-color body {
 	--color-background: rgb(var(--color-tint-86));
 	--color-foreground: rgb(var(--color-tint-92));
@@ -166,6 +177,7 @@ html.immersion-color body {
 	--color-selection: rgb(var(--color-tint-70));
 }
 
+/* ---------- 沉浸式主题色 (夜间) ---------- */
 html.immersion-color.darkmode body {
 	--color-background: rgb(var(--color-shade-94));
 	--color-foreground: rgb(var(--color-shade-90));
@@ -176,11 +188,13 @@ html.immersion-color.darkmode body {
 	--color-border-on-foreground-deeper: rgb(var(--color-shade-75));
 	--color-text-deeper: rgb(var(--color-tint-82));
 	--color-selection: rgb(var(--color-shade-70));
---color-darkmode-toolbar: var(--color-shade-90);
+	--color-darkmode-toolbar: var(--color-shade-90);
 	--color-darkmode-banner: rgb(var(--color-shade-96));
 }
 
-/* 主题切换过渡效果 (Dark/Light Mode Transition) */
+/* ==========================================================================
+   主题切换过渡效果
+   ========================================================================== */
 html {
 	transition: none;
 }
@@ -197,8 +211,9 @@ html.theme-transitioning *::after {
 		stroke 200ms var(--ease-standard) !important;
 }
 
-/*Argon CSS Override*/
+/* ==========================================================================
-
+   Argon 框架样式覆盖
+   ========================================================================== */
 .bg-white,
 
 .card,
@@ -249,7 +264,9 @@ html.theme-transitioning *::after {
 	background-color: var(--color-widgets-disabled);
 }
 
-/* Main CSS */
+/* ==========================================================================
+   基础样式
+   ========================================================================== */
 
 :root {
 	--card-radius: 4px;