Skip to content

布局自定义

使用 HTML 模板和 CSS 为标注任务创建自定义视觉布局。

布局自定义

v2.1.0 新增

Potato 提供两种方法来自定义标注界面布局：

  1. 自动生成布局：Potato 生成一个 HTML 布局文件，你可以编辑它
  2. 自定义布局文件：创建你自己的 HTML 模板，完全控制样式

快速开始

使用自动生成布局

  1. 运行一次服务器——Potato 创建 layouts/task_layout.html
  2. 编辑生成的文件来自定义样式
  3. 你的更改在服务器重启后仍然有效（除非你修改了配置中的 annotation_schemes）

使用自定义布局文件

  1. 创建你的布局文件（例如 layouts/custom_task_layout.html）
  2. 在配置中引用它：
yaml
task_layout: layouts/custom_task_layout.html

布局文件结构

自定义布局文件必须包含：

html
<style>
    /* Your custom CSS */
</style>
 
<div class="annotation_schema">
    <!-- Your annotation forms -->
    <form id="schema_name" class="annotation-form radio" data-annotation-id="0">
        <fieldset schema="schema_name">
            <legend>Question text</legend>
            <!-- Input elements -->
        </fieldset>
    </form>
</div>

必需的表单属性

每个标注模式需要：

属性描述
id必须匹配配置中 annotation_schemes 的 name
class包含 annotation-form 和类型（如 radio、multiselect）
data-annotation-id顺序索引（0, 1, 2...）
schemafieldset 和 input 上的属性，匹配模式名称

必需的输入属性

html
<input class="schema_name annotation-input"
       type="radio"
       name="schema_name"
       value="label_value"
       schema="schema_name"
       label_name="label_value"
       onclick="onlyOne(this);registerAnnotation(this);">

示例布局

Potato 包含三个示例布局，展示高级自定义：

1. 内容审核仪表板

位置：project-hub/layout-examples/content-moderation/

特点包括带内容元数据的警告横幅头部、违规类别的 2 列网格、颜色编码的严重程度级别和专业的审核工作流。

bash
python -m potato start project-hub/layout-examples/content-moderation/config.yaml -p 8000

2. 客户服务对话质量保证

位置：project-hub/layout-examples/dialogue-qa/

特点包括带元数据徽章的案例头部、分组评估部分、圆形 Likert 量表评分、质量问题清单和颜色编码的解决方案指标。

bash
python -m potato start project-hub/layout-examples/dialogue-qa/config.yaml -p 8000

3. 医学图像审核

位置：project-hub/layout-examples/medical-review/

特点包括专业的医疗 UI 样式、位置/严重程度的双列布局、分组检查结果部分、结构化的医疗报告和带描述的建议卡片。

bash
python -m potato start project-hub/layout-examples/medical-review/config.yaml -p 8000

CSS 技巧

网格布局

创建多列布局：

css
.annotation-grid {
    display: grid;
    grid-template-columns: repeat(2, 1fr);
    gap: 16px;
}
 
.full-width {
    grid-column: 1 / -1;
}
 
@media (max-width: 768px) {
    .annotation-grid {
        grid-template-columns: 1fr;
    }
}

颜色编码选项

使用严重程度颜色样式化单选按钮：

css
.severity-option input[type="radio"] {
    position: absolute;
    opacity: 0;
}
 
.severity-label {
    display: block;
    padding: 10px;
    border-radius: 6px;
    border: 2px solid transparent;
    cursor: pointer;
    transition: all 0.2s;
}
 
/* Green for "None" */
.severity-none .severity-label {
    background: #dcfce7;
    color: #166534;
}
.severity-none input:checked + .severity-label {
    background: #22c55e;
    color: white;
}
 
/* Red for "Severe" */
.severity-severe .severity-label {
    background: #fee2e2;
    color: #991b1b;
}
.severity-severe input:checked + .severity-label {
    background: #ef4444;
    color: white;
}

区块样式

创建视觉分组：

css
.annotation-section {
    background: #f8fafc;
    border: 1px solid #e2e8f0;
    border-radius: 8px;
    padding: 16px;
    margin-bottom: 16px;
}
 
.section-title {
    font-size: 13px;
    font-weight: 600;
    text-transform: uppercase;
    letter-spacing: 0.05em;
    margin-bottom: 12px;
    padding-bottom: 8px;
    border-bottom: 2px solid #3b82f6;
}

圆形 Likert 评分

css
.likert-circle {
    width: 36px;
    height: 36px;
    border-radius: 50%;
    border: 2px solid #e2e8f0;
    display: flex;
    align-items: center;
    justify-content: center;
    cursor: pointer;
}
 
.likert-option input:checked + .likert-circle {
    background: #8b5cf6;
    color: white;
    border-color: #7c3aed;
}

与实例显示结合

自定义布局与 instance_display 配置一起工作。实例内容（图像、文本、对话）在标注表单上方单独渲染。

yaml
instance_display:
  fields:
    - key: image_url
      type: image
      display_options:
        zoomable: true
 
task_layout: layouts/custom_task_layout.html
 
annotation_schemes:
  - annotation_type: radio
    name: category
    labels: [A, B, C]

最佳实践

  1. 匹配模式名称：表单 id 必须与 annotation_schemes 中的 name 完全匹配
  2. 顺序标注 ID：data-annotation-id 使用 0, 1, 2...
  3. 包含必需的处理程序：单选使用 onclick="onlyOne(this);registerAnnotation(this);"，复选框使用 onclick="registerAnnotation(this);"
  4. 测试响应性：使用媒体查询支持移动端
  5. 保持可访问性：使用正确的标签并保持键盘导航

故障排除

标注未保存

检查：

  • 表单 id 是否匹配标注模式 name
  • 输入是否有 schema 和 label_name 属性
  • 是否有点击处理程序（registerAnnotation）

样式未生效

  • 确保 CSS 特异性足够高以覆盖默认值
  • 检查 <style> 块是否在布局文件内
  • 使用浏览器开发工具检查应用的样式

布局未加载

  • 验证 task_layout 中的路径相对于配置文件
  • 检查 HTML 语法错误
  • 查看服务器日志中的错误信息

延伸阅读

有关实现细节，请参阅源代码文档。