主题编辑器

说明

调查主题决定了您的调查在参与者眼中的外观：页面布局、颜色、字体、徽标以及每个问题的样式。主题使用 Twig 模板、CSS 和 JavaScript 构建，并以 Bootstrap 5 作为其 CSS 框架。

许多常见的更改完全不需要编写代码。徽标、颜色、字体和若干显示设置都可以通过主题选项进行更改。如果您想进一步定制，请使用本页介绍的主题编辑器：添加您自己的 CSS 或 JavaScript、修改页面的 HTML，或为您的主题上传图片和其他文件。

LimeSurvey 自带以下内置调查主题：

• Fruity TwentyThree（fruity_twentythree）：默认主题。
• Bootstrap Vanilla（vanilla）：一个简洁的基础主题，适合想要构建自己的 Bootstrap 主题的开发人员。
• Fruity（fruity）和 Bootswatch（bootswatch）：二者均扩展自 Bootstrap Vanilla。

各个问题类型的外观由问题主题控制，而不是由调查主题控制。如需更改某个问题类型的 HTML，请创建一个问题主题。

开始之前

要使用主题编辑器，您需要拥有全局主题权限（参见全局权限），或者是超级管理员。扩展主题需要创建权限，保存更改需要更新权限，删除主题或重置文件需要删除权限。

  存在错误的主题可能会导致所有使用该主题的调查无法使用。在将主题用于正式调查之前，请先通过调查预览测试您的更改。

内置主题无法编辑：请扩展它们

内置主题会随 LimeSurvey 一起更新，因此您无法直接修改它们。如需自定义，请扩展该主题。扩展会创建一个新的用户主题，它继承其父主题的所有内容。您的主题只包含您修改过的文件，其余一切均取自父主题。这样，当 LimeSurvey 更新父主题时，您的主题仍然可以获得错误修复和改进。

要扩展主题，请执行以下任一操作：

• 转到配置 > 主题，打开该主题所在行末尾的操作菜单（⋯），然后点击扩展，或者
• 在主题编辑器中打开该主题，然后点击工具栏中的扩展。

为新主题输入一个名称。随后主题编辑器会打开您的新主题。

主题的存储位置

• 内置主题：位于您的 LimeSurvey 安装目录中的 themes/survey/。
• 用户主题（扩展、上传或导入的主题）：upload/themes/survey/。

您也可以使用自己的编辑器直接在服务器上编辑用户主题的文件。请确保之后 Web 服务器仍然可以读取和写入这些文件，以便您还能继续使用主题编辑器。

LimeSurvey 主题编辑器

要打开主题编辑器，请转到配置 > 主题，打开该主题所在行末尾的操作菜单（⋯），然后点击主题编辑器。

如果您打开的是内置主题，会出现一条提示，说明这是标准主题，并提供扩展它的链接。您可以查看其文件和预览，但无法保存更改。

工具栏

• 导出：将主题下载为 ZIP 文件。
• 扩展：创建一个继承自此主题的新主题（参见上文）。
• 重命名：重命名主题。仅适用于用户主题。
• 删除：删除主题。您无法删除被设置为默认主题的主题。
• 主题：将主题编辑器切换到另一个主题。
• 界面：选择预览中显示哪个调查页面，以及列出哪些文件供编辑。可选界面包括：问题、调查列表、欢迎、已完成、评估、错误、全部清除、加载、保存、注册、打印答案、公开统计数据、PDF、超出配额、导航和参与者。

编辑文件

右侧的面板列出了所选界面使用的文件：

• 屏幕区域文件：构建页面的 Twig 模板。
• JavaScript 文件
• CSS 文件
• 其它文件：图片、字体以及主题的任何其他文件。

点击文件名即可在编辑器中打开该文件。标记为已继承的文件来自父主题。您仍然可以编辑已继承的文件：此时编辑器下方的按钮显示为复制为本地主题并保存更改，保存时会将该文件连同您的更改一起复制到您的主题中。此后将使用您的副本，而不是父主题的文件。

属于您的主题的文件带有重置按钮。重置会删除您的副本，从而重新使用父主题中的文件。

上传文件

使用其它文件面板底部的上传字段，可以向您的主题添加图片、字体或其他文件。上传的文件存储在主题的 files/ 文件夹中。默认情况下，您可以上传图片（gif、ico、jpg、jpeg、png）以及以下文件类型：css、js、map、json、eot、otf、ttf、woff、woff2、txt、md、xml、twig、lss、lsa、lsq 和 lsg。您的管理员可以通过 config.php 中的 allowedthemeimageformats 和 allowedthemeuploads 设置来更改这些列表。

要在 Twig 文件中显示已上传的图片，请使用 image() 函数：

{{ image('./files/myfile.png', 'Alternative text for the picture', {"class": "myclass"}) }}

在 CSS 文件中，请使用相对于 css 文件夹的路径来引用已上传的文件，例如 url('../files/background.jpg')。

预览

在编辑器下方，预览会使用示例内容显示所选界面。使用手机、640x480、800x600、1024x768 和完整按钮，可以在不同屏幕尺寸下检查页面。

预览使用的是示例数据，可能无法完全按照真实调查的样子显示每种样式。请务必同时在真实的调查预览中检查您的更改。

导入和导出主题

• 若要将主题迁移到另一个 LimeSurvey 安装,请在主题编辑器工具栏中点击导出。主题将以 ZIP 文件的形式下载。
• 若要从 ZIP 文件安装主题,请前往配置 > 主题,然后点击上传并安装。

主题的构成

主题文件夹

主题文件夹包含:

• config.xml:主题清单:名称、父主题、CSS 和 JavaScript 文件、主题选项以及在主题编辑器中显示的界面。
• views/:Twig 模板。layout_global.twig 是大多数调查页面的主布局。其他布局用于特殊页面,例如 layout_survey_list.twig 用于公开调查列表,layout_errors.twig 用于错误页面。views/subviews/ 文件夹存放布局所包含的较小模板。
• css/ 和 scripts/:主题的 CSS 和 JavaScript 文件。
• files/:主题使用的图片和其他文件。
• options/:主题选项页面。

Twig 模板

模板通过 aSurveyInfo 变量接收调查数据。若要查看其包含的全部内容,请在 application/config/config.php 中开启调试模式,并将下面这一行添加到 layout_global.twig 中 body 元素的末尾:

{{ dump(aSurveyInfo) }}

有关可在模板中使用的函数,请参阅可用的 Twig 函数。出于安全原因,模板在沙盒中运行,因此只能使用这些函数。

config.xml

<files> 部分列出了在调查页面上加载的 CSS 和 JavaScript 文件:

• <add> 添加一个文件。如果父主题中已有同名文件,您的文件将替换它。
• <remove> 阻止加载父主题中的某个文件。

您无需再次列出父主题中的文件:它们仍会被加载。

LimeSurvey 在安装主题时读取 config.xml,并将设置存储在数据库中。更改已安装主题的 config.xml 后,请前往配置 > 主题,打开该主题的操作菜单(⋯)并点击重置以重新加载该文件。

添加您自己的 CSS 和 JavaScript

每个内置主题都有两个文件专门用于存放您自己的代码:

• css/custom.css:在所有其他 CSS 文件之后加载,因此其规则会覆盖主题的样式。
• scripts/custom.js:在主题自身的 JavaScript 之后加载。

扩展主题时,应修改这些文件。请将您的 CSS 添加到 custom.css,而不是编辑主题的主要 CSS 文件,这样您的主题就能持续获得父主题的更新。

若要添加更多文件,请上传它们并在主题 config.xml 的 <files> 部分列出。请使用父主题中不存在的文件名,否则您的文件会替换父主题的文件:

<files>
    <css>
        <add>css/my-styles.css</add>
    </css>
    <js>
        <add>scripts/my-script.js</add>
    </js>
</files>

调查页面默认通过 Ajax 加载,因此参与者进入下一页时,浏览器不会重新加载整个页面。请让您的 JavaScript 在首次页面加载和每次 Ajax 页面加载时都运行:

$(document).on('ready pjax:scriptcomplete', function () {
    // Your code here
});

样式表的样式问题

本节中的所有示例都应放入您主题的 custom.css 文件中。

页面类

<html> 和 <body> 元素带有可用于设置整个页面样式的类:

• html:语言代码(例如 en)和文字方向(dir-ltr 或 dir-rtl)。
• body:主题及每个父主题的名称(例如 fruity_twentythree)、字体(例如 font-ibm-sans)、语言(例如 lang-en),以及显示徽标时的 brand-logo。

问题容器类

每个问题都包裹在一个带有 question-container 类的元素中。它还带有:

• 问题类型的类(参见下表)。
• mandatory:该问题为必答或软必答。
• input-error:答案未通过验证,或必答问题未作答。
• missing:该问题仍有未回答的部分,且参与者已经越过了它。
• ls-hidden 和 ls-irrelevant:该问题因其条件而被隐藏。
• ls-hidden-attribute:该问题因“始终隐藏本题”设置而被隐藏。
• 在问题的CSS(类型):设置(位于显示下)中输入的任何类。可用它来设置单个问题的样式。

例如,一个未作答的必答列表(单选)问题:

<div id="question123" class="row list-radio mandatory input-error question-container">
    ...
</div>

问题类的完整列表

问题类型	类	类型代码
5分制选择题	.choice-5-pt-radio	5
阵列	.array-flexible-row	F
阵列(5分制选择题)	.array-5-pt	A
阵列(10分制选择题)	.array-10-pt	B
阵列 (增加,不变,减少)	.array-increase-same-decrease	E
阵列(数字)	.array-multi-flexi	:
阵列 (文本)	.array-multi-flexi-text	;
阵列(是/不确定/否)	.array-yes-uncertain-no	C
按列阵列	.array-flexible-column	H
阵列双尺度	.array-flexible-dual-scale	1
日期/时间	.date	D
方程式	.equation	*
文件上传	.upload-files	|
性别	.gender	G
巨大自由文本	.text-huge	U
语言切换	.language	I
列表(下拉)	.list-dropdown	!
列表(单选)	.list-radio	L
带评论的列表	.list-with-comment	O
长自由文本	.text-long	T
多选题	.multiple-opt	M
带评论的多选题	.multiple-opt-comments	P
多数字输入	.numeric-multi	K
多短文本	.multiple-short-txt	Q
数字输入	.numeric	N
排序	.ranking	R
短自由文本	.text-short	S
文本显示	.boilerplate	X
是/否	.yes-no	Y

问题相关的全局类

在问题容器内部,答案区域使用以下类。其中一些取决于问题的显示设置:例如,阵列(数字)在显示复选框而不是下拉列表时会使用不同的类。

类	用途	使用者(示例)
.ls-answers	包含所有答案选项的元素	所有问题类型
.answers-list	答案选项的列表或行	列表(单选)、多选题、排序、大多数阵列的行
.subquestion-list, .questions-list	子问题的列表或表格	阵列、多短文本、多数字输入
.answer-item	一个答案选项或输入项	几乎所有问题类型
.noanswer-item	“拒答”选项	阵列、5分制选择题、带评论的列表
.question-item	同时也是答案的子问题	多选题、多短文本、多数字输入
.radio-list	单选按钮的列表或行	列表(单选)、5分制选择题、带评论的列表、单选阵列的行
.radio-array	单选按钮的表格	阵列、阵列(5分制选择题)、阵列(10分制选择题)、阵列 (增加,不变,减少)、阵列(是/不确定/否)
.radio-item	一个带标签的单选按钮	列表(单选)、5分制选择题、带评论的列表、单选阵列
.checkbox-list	复选框列表	多选题、带评论的多选题
.checkbox-array	复选框表格	采用复选框布局的阵列(数字)
.checkbox-item	一个带标签的复选框	多选题、带评论的多选题、采用复选框布局的阵列(数字)
.checkbox-text-item	带文本字段的复选框	带评论的多选题
.comment-item	复选框旁边的评论字段	带评论的多选题
.text-list	文本输入列表	多短文本、多数字输入
.text-item	一个文本输入	短自由文本、长自由文本和巨大自由文本、多短文本、阵列 (文本)
.number-list, .numeric-item	数字输入	多数字输入、数字输入
.number-array	数字输入表格	阵列(数字)、阵列 (文本)
.text-array	文本输入表格	阵列 (文本)、阵列(数字)
.dropdown-array, .dropdown-list, .dropdown-item	带下拉列表的表格、行和单元格	阵列(数字)、带下拉列表的阵列双尺度
.date-item	日期输入	日期/时间
.upload-item	文件上传区域	文件上传
.answertext	阵列行中的子问题文本	阵列
.col-answers	子问题文本所在的列	阵列
.ls-heading	带有答案选项的标题行	阵列
.ls-odd, .ls-even	交替行	阵列
.ls-label-xs-visibility	仅在小屏幕上以及对屏幕阅读器可见的标签	阵列的单元格
.ls-input-group-extra	输入项的前缀或后缀	短自由文本、数字输入、多短文本、多数字输入
.ls-js-hidden	JavaScript 启用时隐藏	阵列双尺度、列表(单选)
.ls-no-js-hidden	JavaScript 未启用时隐藏	排序
.ls-js-hidden-sr	JavaScript 启用时隐藏,但仍会被屏幕阅读器读取	排序

在列表(单选)中,“拒答”选项使用的类是 no-anwser-item(拼写如此),而不是 noanswer-item。

例如,下面是列表(单选)问题答案的 HTML:

<ul class="ls-answers answers-list radio-list list-unstyled" role="radiogroup">
    <li id="javatbdQ123_S456" class="answer-item radio-item">
        <input type="radio" value="A" name="Q123" id="answerQ123A">
        <label for="answerQ123A" class="control-label radio-label">Option A</label>
    </li>
    ...
</ul>

验证类的完整列表

验证提示(例如“请选择一个符合的选项”或“请输入 1 到 10 之间的数字”)始终带有 ls-em-tip 类。在参与者作答时,当满足提示规则时,LimeSurvey 会添加 ls-em-success,不满足时会添加 ls-em-error,这样您就可以为这两种状态设置不同的样式。通过问题的隐藏提示设置隐藏的提示会获得 hide-tip 类。

每个提示还带有一个表示其类型的类:

类	提示
.em_default	问题类型的默认提示(例如“请选择一个符合的选项”)
.em_num_answers	答案的最少或最多数量
.em_value_range	最小值或最大值
.em_sum_range	数值总和的最小值或最大值
.em_sum_equals	数值之和必须等于指定的总数
.em_value_integer	只允许输入整数
.em_numbers_only	只允许输入数字
.em_other_numbers_only	“其它”字段中只允许输入数字
.em_other_comment_mandatory	已选择“其它”选项,但其文本字段为空
.em_regex_validation	答案必须符合验证模式
.em_q_fn_validation	问题验证等式
.em_sq_fn_validation	子问题验证公式

反方向语言（RTL）和调整

对于从右到左的语言，<html> 元素带有 dir-rtl 类，内置主题会加载其主 CSS 文件的 RTL 版本。如果某些规则仅适用于从右到左的语言，请在 CSS 中使用 .dir-rtl。

提示与技巧

这些方案适用于从内置主题扩展而来的主题的 custom.css（或注明的 Twig 文件）。在示例中，请将 #c0392b 替换为您自己的颜色。

更改单选按钮和复选框的颜色

若要使用 Fruity TwentyThree 自带的颜色之一，请在主题选项中选择一个Theme color。您也可以在主题选项中选择不同的勾选图标。

如需其他颜色，请将 CSS 添加到 custom.css。内置主题使用自己绘制的单选按钮和复选框，而不是浏览器的默认样式，因此更改颜色就是更改这些绘制的元素。

Fruity TwentyThree：

.radio-item input[type=radio]:checked + label::before,
.checkbox-item input[type=checkbox]:checked + label::before {
    border-color: #c0392b;
}
.radio-item input[type=radio]:checked + label::after {
    background-color: #c0392b;
}
.checkbox-item input[type=checkbox]:checked + label::after {
    color: #c0392b;
}
/* The text of the selected answer */
.radio-item input[type=radio]:checked + label,
.checkbox-item input[type=checkbox]:checked + label {
    color: #c0392b;
}

Bootstrap Vanilla、Fruity 和 Bootswatch：

.radio-item input[type=radio]:checked + label::after {
    background-color: #c0392b;
}
.checkbox-item input[type=checkbox]:checked + label::after {
    background-color: #c0392b;
    border-color: #c0392b;
    color: #ffffff;
}

请确保颜色与背景之间有足够的对比度，以便视力较弱的参与者仍能看出哪些答案已被选中。

放大单选按钮和复选框

更大的单选按钮和复选框更便于在手机和平板电脑上点按。这适用于所有内置主题：

.radio-item label::before,
.radio-item label::after,
.checkbox-item label::before,
.checkbox-item label::after {
    scale: 1.3;
}

在 Fruity TwentyThree 中，还需在单选按钮与答案文本之间添加一些间距：

.radio-item label {
    padding-left: 14px;
}

最大约 1.4 的值无需其他更改即可正常使用。数值更大时，在小屏幕上控件会开始与答案文本和阵列行的边缘重叠，因此您还需要在它们周围添加更多间距。

进度条的样式

.progress-bar {
    background-color: #c0392b;
}

特殊字符

<body> 元素带有表示当前语言的类，例如 lang-en 或 lang-fr。您可以利用它按语言显示不同的内容，例如页脚中的一行帮助文字。请将每种语言的文本添加到主题的 Twig 文件中，例如 subviews/footer/footer.twig：

<div class="help-fr" lang="fr">Pour de l'aide, appelez le 000000</div>
<div class="help-en" lang="en">For help, please call 000000</div>

然后在 custom.css 中隐藏其他语言的文本：

body:not(.lang-fr) .help-fr,
body:not(.lang-en) .help-en {
    display: none;
}

相同模板使用不同标识

您无需为每个图标单独创建主题。主题选项可以针对单个调查进行设置：打开调查，在调查设置菜单中点击主题选项，然后选择不同的图标文件。参见主题选项。

显示自定义图标

网站图标（favicon）是显示在浏览器标签页和书签中的小图标。内置主题会显示主题的 files/favicon.ico 文件。若要使用您自己的图标，请将其命名为 favicon.ico，并在扩展主题的其它文件面板中上传。它将替换父主题的图标。

在 Fruity TwentyThree 中使图标居中

在主题选项中开启图标，然后将以下内容添加到 custom.css：

#survey-nav .container-fluid {
    position: relative;
}
#survey-nav .logo-container {
    position: absolute;
    left: 50%;
    transform: translateX(-50%);
}

添加标识 ^{(New in 3.0 )}

公开调查列表默认显示 LimeSurvey 图标。若要显示您自己的图标：

1. 扩展 Fruity TwentyThree，并在主题编辑器中打开您的主题。
2. 在其它文件面板中上传您的图标。
3. 选择调查列表界面，并打开 layout_survey_list.twig。
4. 找到包含 {{ include('./ls_logo_svg.twig') }} 的 <div>。将整个 <div>（包括 include 行）替换为这些步骤下方显示的代码。
5. 点击复制为本地主题并保存更改。
6. 转到配置 > 全局设置 > 常规，并将您的主题选为Theme for public survey list and error pages。

请使用您上传的文件名，并将贵组织的名称作为替代文本：

{{ image('./files/mylogo.png', 'Name of your organisation', {"class": "img-fluid mx-auto d-block"}) }}

为双尺度阵列创建垂直分隔线边框

若要在阵列双尺度问题的两个尺度之间绘制一条垂直线：

.array-flexible-dual-scale .header_separator,
.array-flexible-dual-scale .dual_scale_separator {
    border-right: 1px solid #00a8e1;
}

供开发者使用的高级功能

若要在调查的所有页面上运行 JavaScript，请将其放入主题的 custom.js 中（参见上文）。

您也可以将脚本添加到单个问题或组的文本中。除非您的用户已关闭 XSS 过滤器，否则 LimeSurvey 会从这些文本中移除脚本。该过滤器从不适用于超级管理员。对于其他用户，必须在配置 > 全局设置 > 安全中关闭为XSS过滤HTML：。仅当您信任所有可以编辑调查的人时才这样做。有关详细信息和示例，请参见Workarounds: Manipulating a survey at runtime using Javascript。