字段与小部件

字段结构化数据库模型。如果把模型想象成一张表或电子表格，字段就是用于存储记录（即行）数据的列。字段还定义了其中存储的数据类型。数据在 UI（用户界面） 上的呈现和格式由其小部件（widget）决定。

从技术角度看，Odoo 中有 15 种字段类型。但在 Studio 中可以选择 20 种字段，因为某些字段类型会以不同的默认小部件出现多次。

:::: tip ::: title 提示 :::

New Fields（新字段）只能添加到 studio/views/general/form 和 studio/views/multiple-records/list 视图中。其他视图只能添加 Existing Fields（模型中已有的字段）。 ::::

简单字段包含基本值，如文本、数字、文件等。

:::: note ::: title 备注 :::

非默认小部件（如有）会以下列项目符号或子标题形式展示。 ::::

Text 字段用于存放任意字符的短文本。填写时仅显示一行文本。

  • Badge：在圆形标签中显示值，值不可在 UI 上编辑，但可设默认值。

  • Copy to Clipboard：用户点击按钮即可复制值。

  • E-mail：值会变为可点击的 mailto 链接。

  • Image：使用 URL 显示图片。值不可手动编辑，但可设默认值。

    :::: note ::: title 备注 :::

    这与直接选择 Image field <studio/fields/simple-fields-image> 不同，因为使用 Text 字段配合 Image 小部件时，图片并未存入 Odoo，适用于节省磁盘空间的场景。 ::::

  • Phone：值会变为可点击的 tel 链接。

    :::: tip ::: title 提示 :::

    勾选 Enable SMS 可在字段旁添加直接发送短信的选项。 ::::

  • URL：值会变为可点击的 URL。

::: example :::

Multiline Text 字段用于存放较长文本，支持任意字符。填写时 UI 上会显示两行文本。

  • Copy to Clipboard：用户点击按钮即可复制值。

::: example :::

Integer 字段用于所有整数（正、负或零，且不含小数）。

  • Percentage Pie：在百分比圆环中显示值，通常用于计算值；值不可编辑，但可设默认值。
  • Progress Bar：在百分比进度条旁显示值，通常用于计算值；字段不可手动编辑，但可设默认值。
  • Handle：在 List view <studio/views/multiple-records/list> 中显示拖拽图标，以手动排序记录。

::: example :::

Decimal 字段用于所有小数（正、负或零，且带小数位）。

:::: note ::: title 备注 :::

UI 上默认显示两位小数，但在数据库中保存更高精度。 ::::

  • Monetary：类似 Monetary field <studio/fields/simple-fields-monetary>，建议直接使用后者以获得更多功能。
  • Percentage：在值后显示 % 符号。
  • Percentage Pie：在百分比圆环中显示值，通常用于计算值；不可编辑，可设默认值。
  • Progress Bar：在进度条旁显示值，通常用于计算值；不可编辑，可设默认值。
  • Time：值必须符合 hh:mm 格式，分钟上限为 59。

::: example :::

Monetary 字段用于所有货币值。

:::: note ::: title 备注 :::

首次添加 Monetary 字段时，如果模型中尚未存在 Currency 字段，系统会提示添加。Odoo 可自动为你添加 Currency 字段，随后再添加 Monetary 字段。 ::::

::: example :::

Html 字段用于添加可通过 Odoo HTML 编辑器编辑的文本。

  • Multiline Text：禁用 Odoo HTML 编辑器，以编辑原始 HTML。

::: example :::

Date 字段用于在日历中选择日期。

  • Remaining Days：显示距选定日期的剩余天数（如 “In 5 days”），基于当前日期。该字段应设为 Read only。

::: example :::

Date & Time 字段用于在日历中选择日期并在时钟上选择时间。若未设置时间，则自动使用用户当前时间。

:::: tip ::: title 提示 :::

除了 general properties <studio/fields/properties>，Date & Time 字段在使用 Date & Time 或 Date Range 小部件时，还提供 specific properties <studio/fields/properties-date-datetime>。 ::::

Date Range 小部件在单行中显示由开始日期和结束日期定义的时间段。可设为必须提供开始/结束日期（如多日活动），或允许可选的开始或结束日期（如现场服务或项目任务）。

添加日期范围需要两个字段：一个设置了 Date Range 小部件的 Date & Time 字段，以及另一个作为 开始日期 或 结束日期 的字段。该基础字段可以是已有的 Date、Date & Time，或专为此创建的字段。

添加步骤：

  1. 选取已有的 Date 或 Date & Time 字段作为基础开始/结束日期字段，或新建一个。如果日期范围：

    • 必须提供开始和结束日期，则该字段可作为开始或结束日期，效果相同；
    • 允许可选的开始或结束日期，则该字段分别对应开始或结束日期。

    :::: tip ::: title 提示 :::

    为避免信息重复显示，可通过勾选 Invisible 将基础字段设为不可见，或在视图中点击 Remove from view 将其移除。 ::::

  2. 添加一个 Date & Time 字段，并将其 Widget 设置为 Date Range。

  3. 输入合适的 Label。

  4. 在 Start date field 或 End date field 下拉框中选择对应的基础字段。

  5. 若日期范围必须提供开始和结束日期，勾选 Always range。

  6. 根据需要更新 general properties 或 properties for Date & Time fields，完成后点击右上角 Close。

::: example :::

Remaining Days 小部件显示距选定日期的剩余天数（如 “In 5 days”），基于当前日期和时间。该字段应设为 Read only。

Checkbox 字段用于布尔值（真/假），通过勾选或取消勾选实现。

  • Button：显示单选按钮，且无需进入编辑模式。
  • Toggle：显示切换按钮，同样无需进入编辑模式。

::: example :::

Selection 字段用于用户从预定义值列表中选择单一值。

  • Badge：在圆形标签中显示值，值不可编辑，可设默认值。

  • Badges：将所有可选值以矩形标签水平排列显示。

  • Priority：用星号代替文字显示，可用于表示重要程度或满意度。效果同 Priority field <studio/fields/simple-fields-priority>，后者预定义四个优先级值。

  • Radio：以单选按钮形式一次性显示所有可选值。

    :::: tip ::: title 提示 :::

    默认单选按钮垂直排列，勾选 Display horizontally 可改为水平排列。 ::::

  • Status Bar：以进度条形式一次性显示所有可选值。

    :::: tip ::: title 提示 :::

    默认状态栏的值可点击编辑，勾选 Clickable 可禁用编辑。 ::::

::: example :::

Priority 字段用于显示三颗星的评分系统，可表示重要程度或满意度。该字段本质上是带有 Priority 小部件的 Selection，并预定义四个值（0‑3 星）。因此 Badge、Badges、Radio、Selection 小部件的效果与 Selection 中描述相同。

:::: tip ::: title 提示 :::

通过点击 Edit Values 可增删星级对应的值。注意第一个值对应 0 星（即未选择），因此四个值实际呈现为三颗星的评分。 ::::

::: example :::

File 字段用于上传任意文件，或使用 Sign 小部件进行表单签名。

  • Image：上传图片并在 Form view <studio/views/general/form> 中显示，效果同 Image field <studio/fields/simple-fields-image>。
  • PDF Viewer：上传 PDF 文件，可在表单视图中浏览。
  • Sign：电子签名，效果同 Sign field <studio/fields/simple-fields-sign>。

::: example :::

Image 字段用于上传图片并在 Form view 中显示。该字段本质上是带有 Image 小部件的 File 字段，因此 File、PDF Viewer、Sign 小部件的效果相同。

:::: tip ::: title 提示 :::

可在 Size 选项中选择 Small、Medium、Large 来调整显示尺寸。 ::::

Sign 字段用于电子签名。该字段本质上是带有 Sign 小部件的 File 字段，故 File、Image、PDF Viewer 小部件的效果相同。

:::: tip ::: title 提示 :::

若希望在用户绘制签名时提供 Auto 选项，可在模型中选择 Auto-complete with 的字段（如 Text、Many2One、Related Field），系统会根据所选字段的数据自动生成签名。 ::::

关系字段用于关联并显示来自另一模型记录的数据。

:::: note ::: title 备注 :::

非默认小部件（如有）会以下列项目符号形式展示。 ::::

Many2One 字段用于将另一模型的记录关联到当前正在编辑的记录。关联记录的名称会显示在当前记录中。

::: example 在 Sales Order（销售订单）模型中，Customer（客户）字段是指向 Contact（联系人）模型的 Many2One 字段，实现 多个销售订单关联到 一个客户。 :::

:::: tip ::: title 提示 :::

  • 勾选 Disable creation 可阻止用户在关联模型中创建新记录。

  • 勾选 Disable opening 可阻止用户在弹窗中打开记录。

  • 使用 Domain 可为用户创建过滤条件，仅显示符合条件的记录。

  • 在 Typeahead search 中设置字符数阈值，可在输入一定字符后才触发搜索，提升大数据集的搜索性能。
    ::::

  • Badge：在圆形标签中显示值，值不可编辑。

  • Radio：以单选按钮形式一次性显示所有可选值。

One2Many 字段用于显示当前模型记录与另一模型多条记录之间的已有关联。

::: example 在 Contact（联系人）模型上添加 One2Many 字段，可查看 一个客户的 多个销售订单。 :::

:::: note ::: title 备注 :::

使用 One2Many 字段前，两个模型必须已通过 Many2One 建立关联。One2Many 本身不独立存在，而是通过反向查询已有的 Many2One 关系实现。 ::::

Lines 字段用于创建包含行列的表格（如销售订单的产品明细行）。

:::: tip ::: title 提示 :::

点击 Lines 字段后选择 Edit List View 可修改列；若要编辑点击 “Add a line” 后弹出的表单，点击 Edit Form View。 ::::

::: example :::

Many2Many 字段用于在当前模型与另一模型之间建立多对多关联。该字段同样支持 Disable creation、Disable opening、Domain 等设置。

::: example 在 Task（任务）模型中，Assignees（负责人）字段指向 Contact（联系人）模型，实现 多个用户可被分配到 多个任务，反之亦然。 :::

:::: tip ::: title 提示 :::

在 Typeahead search 中设置字符阈值，可在大数据集下提升搜索相关性与性能。 ::::

  • Checkboxes：使用复选框多选值。
  • Tags：以圆形标签（即 tags）形式多选，效果同 Tags field <studio/fields/relational-fields-tags>。

Tags 字段用于以圆形标签形式显示来自另一模型的多个值。该字段本质上是带有 Tags 小部件的 Many2Many 字段，因此 Checkboxes 与 Many2Many 小部件的效果相同。

:::: tip ::: title 提示 :::

勾选 Use colors 可为不同标签设置不同背景颜色。 ::::

::: example :::

Related Field 并非真正的关系字段，它不创建模型间的关联，而是利用已有的关联，从另一