Chapter 5: Finally, Some UI To Play With
第五章：终于可以操作用户界面了

原文来自：
https://www.odoo.com/documentation/17.0/zh_CN/developer/tutorials/server_framework_101/05_firstui.html
使用通义千问翻译。

测试代码：https://gitee.com/zhang-wei918/estate

Now that we’ve created our new model and its corresponding access rights, it is time to interact with the user interface.
在创建了新模型及其相应的访问权限之后，现在是时候与用户界面进行互动了。

At the end of this chapter, we will have created a couple of menus in order to access a default list and form view.
本章结束时，我们将创建几个菜单，以便访问默认的列表视图和表单视图。

Data Files (XML) 数据文件（XML）

Reference: the documentation related to this topic can be found in Data Files.
参考：关于这一主题的文档可以在《数据文件》中找到。

In Chapter 4: Security – A Brief Introduction, we added data through a CSV file. The CSV format is convenient when the data to load has a simple format. When the format is more complex (e.g. load the structure of a view or an email template), we use the XML format. For example, this help field contains HTML tags. While it would be possible to load such data through a CSV file, it is more convenient to use an XML file.
在第4章《安全入门》中，我们通过CSV文件添加了数据。当加载数据的格式较为简单时，CSV格式非常便利。但是，当格式更加复杂（例如，加载视图结构或电子邮件模板）时，我们会使用XML格式。例如，帮助文本字段可能包含HTML标签。尽管通过CSV文件加载此类数据是可行的，但使用XML文件更为便捷。

The XML files must be added to the same folders as the CSV files and defined similarly in the __manifest__.py. The content of the data files is also sequentially loaded when a module is installed or updated, therefore all remarks made for CSV files hold true for XML files. When the data is linked to views, we add them to the views folder.
XML文件必须像CSV文件一样，添加到相同的文件夹中，并在__manifest__.py中以相似的方式定义。当模块被安装或更新时，数据文件的内容也会按顺序加载，因此适用于CSV文件的所有注意事项同样适用于XML文件。当数据与视图相关联时，我们将它们添加到views文件夹中。

In this chapter, we will load our first action and menus through an XML file. Actions and menus are standard records in the database.
在本章中，我们将通过XML文件加载我们的第一个操作和菜单。操作和菜单是数据库中的标准记录。

注解

When performance is important, the CSV format is preferred over the XML format. This is the case in Odoo where loading a CSV file is faster than loading an XML file.
当性能成为关键因素时，相比XML格式，优先推荐使用CSV格式。在Odoo中尤其如此，因为加载CSV文件的速度要比加载XML文件快。

In Odoo, the user interface (actions, menus and views) is largely defined by creating and composing records defined in an XML file. A common pattern is Menu > Action > View. To access records the user navigates through several menu levels; the deepest level is an action which triggers the opening of a list of the records.
在Odoo中，用户界面（包括操作、菜单和视图）很大程度上是通过在XML文件中创建和组合定义的记录来定义的。一个常见的模式是“菜单>操作>视图”。为了访问记录，用户需要通过多个菜单层级进行导航；最深层级的操作将触发记录列表的打开。

Actions 动作

Reference: the documentation related to this topic can be found in Actions.
参考：有关此话题的文档可以在《动作》中找到。

注解

Goal: at the end of this section, an action should be loaded in the system. We won’t see anything yet in the UI, but the file should be loaded in the log:
目标：本节末尾，系统中应已加载一个动作。虽然在用户界面暂时还看不到任何变化，但应在日志中看到文件被加载的记录：

INFO rd-demo odoo.modules.loading: loading estate/views/estate_property_views.xml

Actions can be triggered in three ways: 动作可以通过以下三种方式触发：

1. by clicking on menu items (linked to specific actions)
   通过点击菜单项（链接到特定动作）
2. by clicking on buttons in views (if these are connected to actions)
   通过点击视图中的按钮（如果这些按钮与动作关联）
3. as contextual actions on object
   作为对象的上下文动作

We will only cover the first case in this chapter. The second case will be covered in a later chapter while the last is the focus of an advanced topic. In our Real Estate example, we would like to link a menu to the estate.property model, so we are able to create a new record. The action can be viewed as the link between the menu and the model.
本章仅涵盖第一种情况。第二种情况将在后续章节讨论，而最后一种则是高级主题的重点。在我们的房地产示例中，我们希望将一个菜单链接到estate.property模型，以便能够创建新记录。动作可以看作是菜单和模型之间的桥梁。

A basic action for our test_model is: 我们的test_model的基本动作如下：

<record id="test_model_action" model="ir.actions.act_window">
    <field name="name">Test action</field>
    <field name="res_model">test_model</field>
    <field name="view_mode">tree,form</field>
</record>

• id is an external identifier. It can be used to refer to the record (without knowing its in-database identifier).
  id 是一个外部标识符，可以用来引用记录（而不必知道其在数据库中的实际标识符）。
• model has a fixed value of ir.actions.act_window (Window Actions (ir.actions.act_window)).
  model 的值固定为ir.actions.act_window，表示这是一个窗口动作记录。
• name is the name of the action. name 表示动作的名称。
• res_model is the model which the action applies to.
  res_model 指明动作作用于哪个模型。
• view_mode are the views that will be available; in this case they are the list (tree) and form views. We’ll see later that there can be other view modes.
  view_mode 定义了可用的视图模式，在这个例子中是列表视图（tree）和表单视图。稍后我们会了解到还有其他视图模式。

Examples can be found everywhere in Odoo, but this is a good example of a simple action. Pay attention to the structure of the XML data file since you will need it in the following exercise.
Odoo中充满了这样的实例，但这是理解简单动作的一个良好示例。请留意XML数据文件的结构，因为在接下来的练习中你将需要用到它。

Exercise

Add an action. 添加一个动作。

Create the estate_property_views.xml file in the appropriate folder and define it in the __manifest__.py file.
在相应的文件夹中创建estate_property_views.xml文件，并在__manifest__.py文件中定义它。

Create an action for the model estate.property.
为estate.property模型创建一个动作。

Restart the server and you should see the file loaded in the log.
重启服务器后，你应该能在日志中看到该文件已被加载的信息。

Menus 菜单项

Reference: the documentation related to this topic can be found in Shortcuts.
参考文献：有关此主题的文档可以在《快捷方式》中找到。

注解

Goal: at the end of this section, three menus should be created and the default view is displayed:
目标：本节完成后，应创建三个层次的菜单，并且默认视图将得到展示：

To reduce the complexity in declaring a menu (ir.ui.menu) and connecting it to the corresponding action, we can use the <menuitem> shortcut .
为了简化声明菜单（ir.ui.menu）及将其与相应操作关联的过程，我们可以使用 <menuitem> 快捷方式。

A basic menu for our test_model_action is:
针对我们的示例test_model_action，一个基本的菜单项定义如下：

<menuitem id="test_model_menu_action" action="test_model_action"/>

The menu test_model_menu_action is linked to the action test_model_action, and the action is linked to the model test_model. As previously mentioned, the action can be seen as the link between the menu and the model.
菜单test_model_menu_action与操作test_model_action相关联，而该操作又与模型test_model相连。如前所述，这个操作可以被视为菜单和模型之间的纽带。

However, menus always follow an architecture, and in practice there are three levels of menus:
然而，菜单总是遵循一种架构，在实际应用中有三层菜单：

1. The root menu, which is displayed in the App switcher (the Odoo Community App switcher is a dropdown menu)
   根菜单：显示在应用切换器中（在Odoo社区版中，应用切换器是一个下拉菜单）。
2. The first level menu, displayed in the top bar
   第一级菜单：在顶部工具栏中展示。
3. The action menus 动作菜单：与具体操作相关的菜单。

The easiest way to define the structure is to create it in the XML file. A basic structure for our test_model_action is:
定义这种结构的最简便方法是在XML文件中创建。针对我们的test_model_action，一个基本的结构如下所示：

<menuitem id="test_menu_root" name="Test">
    <menuitem id="test_first_level_menu" name="First Level">
        <menuitem id="test_model_menu_action" action="test_model_action"/>
    </menuitem>
</menuitem>

The name for the third menu is taken from the name of the action.
第三个菜单的名称直接取自其关联的动作名称。

Exercise

Add menus. 添加菜单

Create the estate_menus.xml file in the appropriate folder and define it in the __manifest__.py file. Remember the sequential loading of the data files 😉
在相应的文件夹中创建estate_menus.xml文件，并在__manifest__.py文件中定义它。别忘了数据文件是按顺序加载的哦 😉

Create the three levels of menus for the estate.property action created in the previous exercise. Refer to the Goal of this section for the expected result.
为前一练习中创建的estate.property动作设计三级菜单结构。预期成果应参考本节的目标描述。

Restart the server and refresh the browser1. You should now see the menus, and you’ll even be able to create your first real estate property advertisement!
重启服务器，并刷新浏览器。此时，你应该能看到新创建的菜单了，而且你将能够创建你的第一条房地产物业广告信息！

Fields, Attributes And View
字段、属性与视图

注解

Goal: at the end of this section, the selling price should be read-only and the number of bedrooms and the availability date should have default values. Additionally the selling price and availability date values won’t be copied when the record is duplicated.
目标： 在本节结束时，销售价格应设置为只读状态，卧室数量和可获取日期应具有默认值。此外，当记录被复制时，销售价格和可获取日期的值不应被复制。

The reserved fields active and state are added to the estate.property model.
在estate.property模型中添加了保留字段active和state。

So far we have only used the generic view for our real estate property advertisements, but in most cases we want to fine tune the view. There are many fine-tunings possible in Odoo, but usually the first step is to make sure that:
到目前为止，我们仅为房地产广告使用了通用视图，但在大多数情况下，我们希望对视图进行精细化调整。Odoo中有很多可能的微调方式，但通常第一步是确保：

• some fields have a default value 某些字段具有默认值
• some fields are read-only 某些字段为只读
• some fields are not copied when duplicating the record 某些字段在复制记录时不被复制

In our real estate business case, we would like the following:
在我们的房地产业务案例中，我们希望实现以下几点：

• The selling price should be read-only (it will be automatically filled in later)
  销售价格应设为只读（稍后将自动填充）
• The availability date and the selling price should not be copied when duplicating a record
  复制记录时，可获取日期和销售价格不应被复制
• The default number of bedrooms should be 2
  卧室数量的默认值应为2
• The default availability date should be in 3 months
  可获取日期的默认值应设置为3个月后

Some New Attributes 一些新属性

Before moving further with the view design, let’s step back to our model definition. We saw that some attributes, such as required=True, impact the table schema in the database. Other attributes will impact the view or provide default values.
在进一步进行视图设计之前，让我们先回顾一下模型定义。我们了解到，像required=True这样的某些属性会影响到数据库中的表结构。而其他属性则会影响视图或提供默认值。

 Exercise

Add new attributes to the fields. 向字段添加新属性。

Find the appropriate attributes (see Field) to:
寻找合适的属性（参见字段文档）以实现：

• set the selling price as read-only 将销售价格设置为只读
• prevent copying of the availability date and the selling price values
  防止复制可获取日期和销售价格的值

Restart the server and refresh the browser. You should not be able to set any selling prices. When duplicating a record, the availability date should be empty.
重启服务器并刷新浏览器。此后，你应该无法设定任何销售价格了。当复制一条记录时，可获取日期应当是空白的。

Default Values 默认值

Any field can be given a default value. In the field definition, add the option default=X where X is either a Python literal value (boolean, integer, float, string) or a function taking a model and returning a value:
任何字段都可以被赋予一个默认值。在字段定义中，添加选项default=X，其中X可以是Python的字面量值（布尔值、整数、浮点数、字符串）或是一个接受模型参数并返回一个值的函数：

name = fields.Char(default="Unknown")
last_seen = fields.Datetime("Last Seen", default=fields.Datetime.now)

The name field will have the value ‘Unknown’ by default while the last_seen field will be set as the current time.
这样，name字段的默认值就会是“未知”，而last_seen字段则会被设置为当前时间。

Exercise

Set default values. 设置默认值

Add the appropriate default attributes so that:
添加适当的默认属性，以便：

• the default number of bedrooms is 2 卧室数量的默认值为2
• the default availability date is in 3 months 可获取日期的默认值为3个月后

Tip: this might help you: today() 提示：这个函数可能会对你有帮助：today()

Check that the default values are set as expected.
检查默认值是否如预期设置好了。

Reserved Fields 保留字段

Reference: the documentation related to this topic can be found in Reserved Field names.
参考：关于此主题的文档可以在“保留字段名”中找到。

A few field names are reserved for pre-defined behaviors. They should be defined on a model when the related behavior is desired.
有一些字段名称是为预定义的行为保留的。当需要相关行为时，应在模型上定义这些字段。

 Exercise

Add active field. 添加active字段。

Add the active field to the estate.property model.
将active字段添加到estate.property模型中。

Restart the server, create a new property, then come back to the list view… The property will not be listed! active is an example of a reserved field with a specific behavior: when a record has active=False, it is automatically removed from any search. To display the created property, you will need to specifically search for inactive records.
重启服务器后，创建一个新的房产记录，然后回到列表视图……你会发现该房产记录没有列出！active是一个具有特定行为的保留字段示例：当一条记录的active=False时，它会自动从任何搜索结果中移除。为了显示创建的房产记录，你需要特别搜索不活动的记录。

 Exercise

Set a default value for active field. 为active字段设置默认值。

Set the appropriate default value for the active field so it doesn’t disappear anymore.
为active字段设置一个合适的默认值，以防止它再次消失。

Note that the default active=False value was assigned to all existing records.
请注意，active=False的默认值已分配给所有现有记录。

 Exercise

Add state field. 添加state字段。

Add a state field to the estate.property model. Five values are possible: New, Offer Received, Offer Accepted, Sold and Canceled. It must be required, should not be copied and should have its default value set to ‘New’.
在estate.property模型中添加一个state字段。可能的五个值为：新（New）、收到报价（Offer Received）、接受报价（Offer Accepted）、已售（Sold）和已取消（Canceled）。此字段必须是必填项，不应在复制记录时被复制，并且其默认值应设置为“新（New）”。

Make sure to use the correct type! 确保使用正确的类型！

The state will be used later on for several UI enhancements.
稍后，我们将使用state字段来进行多项用户界面增强。

Now that we are able to interact with the UI thanks to the default views, the next step is obvious: we want to define our own views.
现在，我们能够通过默认视图与用户界面进行交互，下一步很明显：我们想要定义自己的视图。

1.A refresh is needed since the web client keeps a cache of the various menus and views for performance reasons.
由于性能原因，Web客户端会缓存各种菜单和视图，所以在进行上述更改后，可能需要刷新一下界面才能看到效果。