外观设置
外观设置允许管理员配置多个外部 CSS 样式表，这些样式表会自动注入到所有页面的 HTML <head> 中。这使您可以在不修改核心代码的情况下进行站点范围的外观自定义，类似于 Moodle 的外观自定义功能。
外观设置提供：
- 外部 CSS 样式表：添加多个样式表 URL
- 顺序控制：重新排序样式表以控制 CSS 级联优先级
- URL 验证：自动验证 HTTP/HTTPS URL
- 轻松管理：通过简单界面添加、删除和重新排序样式表
- 全局应用：样式表自动应用于所有页面
访问外观设置
Section titled “访问外观设置”有两种方式访问外观设置页面：
方法1：通过管理员仪表板
Section titled “方法1：通过管理员仪表板”- 以管理员身份登录
- 导航到顶部导航中的 站点管理
- 点击站点管理菜单中的 “外观” 选项卡
- 点击外观部分中的 “附加 CSS”
- 您将被带到
/admin/appearance的外观设置页面
方法2：直接导航
Section titled “方法2：直接导航”- 以管理员身份登录
- 在浏览器中直接导航到
/admin/appearance
添加 CSS 样式表
Section titled “添加 CSS 样式表”要添加新的 CSS 样式表：
- 导航到外观设置页面
- 点击 “添加样式表” 按钮
- 在文本输入字段中输入样式表 URL
- URL 必须是有效的 HTTP 或 HTTPS URL
- 点击 “保存更改” 以应用
URL 格式
Section titled “URL 格式”样式表 URL 必须：
- 协议：使用
http://或https://（推荐 HTTPS） - 格式：有效的 URL 格式
- 可访问性：公开可访问（不需要身份验证）
- CORS：如果需要，具有适当的 CORS 标头
URL 示例：
https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.csshttps://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.csshttps://example.com/custom-theme.cssURL 验证
Section titled “URL 验证”系统在多个级别验证 URL：
- 字段级验证：使用 JavaScript
URL构造函数检查 URL 格式 - 服务器端验证：在保存前验证所有 URL
- 客户端验证：表单中的实时反馈
无效的 URL 将显示错误消息：“必须是有效的 HTTP 或 HTTPS URL”
重新排序样式表
Section titled “重新排序样式表”样式表的顺序对于 CSS 级联优先级很重要。后面的样式表可以覆盖前面的样式表。
向上移动样式表
Section titled “向上移动样式表”要在列表中较早移动样式表：
- 找到要移动的样式表
- 点击样式表旁边的 “向上” 按钮（↑）
- 样式表将向上移动一个位置
- 点击 “保存更改” 以应用新顺序
向下移动样式表
Section titled “向下移动样式表”要在列表中较晚移动样式表：
- 找到要移动的样式表
- 点击样式表旁边的 “向下” 按钮（↓）
- 样式表将向下移动一个位置
- 点击 “保存更改” 以应用新顺序
- 向上按钮：在第一个样式表上禁用（无法进一步向上移动）
- 向下按钮：在最后一个样式表上禁用（无法进一步向下移动）
- 活动按钮：在中间的样式表上启用
CSS 级联优先级
Section titled “CSS 级联优先级”样式表按配置的顺序加载：
- 第一个样式表：首先加载，优先级最低
- 后续样式表：按顺序加载，每个都可以覆盖前一个
- 最后一个样式表：最后加载，优先级最高
这允许您：
- 首先加载基础样式：基础样式表（例如，Bootstrap）
- 其次加载主题覆盖：主题特定样式
- 最后加载自定义：站点特定自定义（最高优先级）
1. Bootstrap CSS（基础框架）2. 主题 CSS（主题覆盖）3. 自定义 CSS（站点特定自定义）← 最高优先级要删除样式表：
- 找到要删除的样式表
- 点击样式表旁边的 “删除” 按钮（垃圾桶图标）
- 样式表将从列表中删除
- 点击 “保存更改” 以应用
未配置样式表时：
- 空状态消息：“未配置样式表。点击 ‘添加样式表’ 添加一个。”
- 添加按钮：可用于添加第一个样式表
- 无影响：页面将在没有附加样式表的情况下正常加载
样式表的加载方式
Section titled “样式表的加载方式”样式表按以下顺序注入到 HTML <head> 中：
- Mantine 核心样式：基础框架样式（通过
@mantine/core/styles.css导入） - Highlight.js 样式表：代码高亮主题（主题感知）
- 附加 CSS 样式表：您配置的样式表（按配置顺序）← 新增
- 页面特定样式：任何页面特定样式
HTML 结构
Section titled “HTML 结构”样式表在 HTML 中显示为：
<head> <!-- Mantine 样式 --> <link rel="stylesheet" href="/mantine-styles.css" />
<!-- Highlight.js 样式 --> <link rel="stylesheet" href="/highlight-theme.css" />
<!-- 您配置的样式表 --> <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" /> <link rel="stylesheet" href="https://example.com/custom.css" />
<!-- 页面内容 --></head>- 使用 CDN：优先使用 CDN 托管的样式表以获得可靠性和性能
- 仅 HTTPS：出于安全考虑使用 HTTPS URL
- 压缩版本：使用压缩的 CSS 文件以获得更好的性能
- 版本固定：考虑使用版本化的 URL 以获得稳定性
- 逻辑顺序：从一般到特定对样式表进行排序
- 文档：记录每个样式表的功能
- 测试：在部署前测试样式表组合
- 备份：记录您的样式表配置
- 限制数量：避免添加太多样式表（影响页面加载时间）
- 优化顺序：将最重要的样式表放在前面
- 监控影响：添加样式表后检查页面加载性能
- 使用异步：考虑对非关键样式表进行异步加载（未来功能）
- 定期审查：定期审查并删除未使用的样式表
- 更新 URL：保持样式表 URL 最新
- 测试更改：在添加或重新排序样式表后测试外观
- 版本控制：在文档中跟踪样式表更改
样式表未加载
Section titled “样式表未加载”如果样式表未加载：
- 验证 URL 是否可访问（在浏览器中打开）
- 检查 URL 是否使用 HTTP 或 HTTPS 协议
- 验证 CORS 标头是否允许从您的域加载
- 检查浏览器控制台中的加载错误
- 验证样式表已保存且页面已刷新
如果样式未应用：
- 检查样式表顺序（后面的样式表覆盖前面的样式表）
- 验证 CSS 特异性（您的样式可能需要更高的特异性）
- 检查浏览器开发工具中的 CSS 冲突
- 确保样式表正在加载（检查网络选项卡）
- 验证样式表内容是否正确
无效 URL 错误
Section titled “无效 URL 错误”如果收到无效 URL 错误：
- 确保 URL 以
http://或https://开头 - 验证 URL 格式是否正确
- 检查 URL 中的拼写错误
- 在浏览器中测试 URL 以确保可访问
- 删除可能破坏 URL 的任何特殊字符
顺序未持久化
Section titled “顺序未持久化”如果样式表顺序未持久化：
- 验证您在重新排序后点击了 “保存更改”
- 刷新页面以查看更新的顺序
- 检查更改是否已保存到数据库
- 验证您有管理员权限
- 检查系统日志中的错误
如果页面加载缓慢：
- 减少样式表数量
- 使用压缩的 CSS 文件
- 考虑合并样式表
- 使用 CDN 托管的样式表以获得更好的缓存
- 监控网络选项卡中加载缓慢的样式表
