Chapter 15: Web Client Development

其它内容

如果在管理异步运算时出现问题可参照如下文档：

• Odoo的RPC返回JavaScript的原生Promise对象。在解析好Promise对象之后就可获取到所请求数据。有关Promise的更多知识请参见https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise。

新建一个视图

我们在第九章 后端视图中学习到存在不同类型的视图，如表单视图、列表视图、看板视图等。本节中，我们将创建一个全新的视图。这个视图会显示作者列表及他们所著的图书。

准备工作

本节中我们使用前一小节的my_library模块。注意视图是非常复杂的结构，并且每种已有视图都有不同的目的和实现。本节旨在让读者了解MVC模式的视图及如何创建简单视图。本节中，我们将创建一个名为m2m_group的视图，目的是在组中展示记录。将记录分成不同组，视图将使用many2many字段数据。在my_library模块中，我们有author_ids字段。这里，我们根据作者分组图书并在卡片中进行显示。

此外，我们将向控制面板添加一个新按钮。借助于这个按钮，我们将能够新增一条图书记录。我们还将在作者的卡片中添加一个按钮，这样可以将用户重定向到另一个视图中。

如何实现…

按照如下步骤来添加一个名为m2m_group新视图：

1. 在ir.ui.view中添加一个新视图类型：

   class View(models.Model):
     _inherit = 'ir.ui.view'
     type = fields.Selection(selection_add=[('m2m_group', 'M2m Group')])
   

2. 在ir.actions.act_window.view中新增一个视图模式：

   class ActWindowView(models.Model):
       _inherit = 'ir.actions.act_window.view'
   
       view_mode = fields.Selection(selection_add=[('m2m_group', 'M2m group')],
                                    ondelete={'m2m_group': 'cascade'})
   

3. 通过继承base模型新增方法。该方法会通过JavaScript模型调用（参见第4步了解更多详情）:：

   class Base(models.AbstractModel):
     _inherit = 'base'
     
     @api.model
     def get_m2m_group_data(self, domain, m2m_field):
       records = self.search(domain)
       result_dict = {}
       for record in records:
         for m2m_record in record[m2m_field]:
           if m2m_record.id not in result_dict:
             result_dict[m2m_record.id] = {
               'name': m2m_record.display_name,
               'children': [],
               'model': m2m_record._name
             }
             result_dict[m2m_record.id]['children'].append({
               'name': record.display_name,
               'id': record.id,
             })
     return result_dict
   

4. 新增文件/static/src/js/m2m_group_model.js，并添加如下内容：

   odoo.define('m2m_group.Model', function (require) {
     'use strict';
   
     var AbstractModel = require('web.AbstractModel');
   
     var M2mGroupModel = AbstractModel.extend({
       get: function () {
         return this.data;
       },
       load: function (params) {
         this.modelName = params.modelName;
         this.domain = params.domain;
         this.m2m_field = params.m2m_field;
         return this._fetchData();
       },
       reload: function (handle, params) {
         if ('domain' in params) {
           this.domain = params.domain;
         }
         return this._fetchData();
       },
       _fetchData: function () {
         var self = this;
         return this._rpc({
           model: this.modelName,
           method: 'get_m2m_group_data',
           kwargs: {
             domain: this.domain,
             m2m_field: this.m2m_field
           }
         }).then(function (result) {
           self.data = result;
         });
       },
     });
   
     return M2mGroupModel;
   
   });
   

5. 新增文件/static/src/js/m2m_group_controller.js，并添加如下内容：

   odoo.define('m2m_group.Controller', function (require) {
     'use strict';
   
     var AbstractController = require('web.AbstractController');
     var core = require('web.core');
     var qweb = core.qweb;
     
     var M2mGroupController = AbstractController.extend({
       custom_events: _.extend({},
       AbstractController.prototype.custom_events, {
         'btn_clicked': '_onBtnClicked',
       }),
       renderButtons: function ($node) {
         if ($node) {
           this.$buttons =
           $(qweb.render('ViewM2mGroup.buttons'));
           this.$buttons.appendTo($node);
           this.$buttons.on('click', 'button',
           this._onAddButtonClick.bind(this));
         }
       },
       _onBtnClicked: function (ev) {
         this.do_action({
           type: 'ir.actions.act_window',
           name: this.title,
           res_model: this.modelName,
           views: [[false, 'list'], [false, 'form']],
           domain: ev.data.domain,
         });
       },
       _onAddButtonClick: function (ev) {
         this.do_action({
           type: 'ir.actions.act_window',
           name: this.title,
           res_model: this.modelName,
           views: [[false, 'form']],
           target: 'new'
         });
       },
     
     });
   
     return M2mGroupController;
   
   });
   

6. 新增文件/static/src/js/m2m_group_renderer.js，并添加如下内容：

   odoo.define('m2m_group.Renderer', function (require) {
     'use strict';
   
     var AbstractRenderer = require('web.AbstractRenderer');
     var core = require('web.core');
   
     var qweb = core.qweb;
     
     var M2mGroupRenderer = AbstractRenderer.extend({
       events: _.extend({},
       AbstractRenderer.prototype.events, {
         'click .o_primay_button': '_onClickButton',
       }),
       _render: function () {
         var self = this;
         this.$el.empty();
         this.$el.append(qweb.render('ViewM2mGroup', {
           'groups': this.state,
         }));
         return this._super.apply(this, arguments);
       },
       _onClickButton: function (ev) {
         ev.preventDefault();
         var target = $(ev.currentTarget);
         var group_id = target.data('group');
         var children_ids =
         _.map(this.state[group_id].children, function (group_id) {
           return group_id.id;
         });
         this.trigger_up('btn_clicked', {
           'domain': [['id', 'in', children_ids]]
         });
       }
     });
   
     return M2mGroupRenderer;
   
   });
   

7. 新增文件/static/src/js/m2m_group_view.js，并添加如下内容：

   odoo.define('m2m_group.View', function (require) {
     'use strict';
   
     var AbstractView = require('web.AbstractView');
     var view_registry = require('web.view_registry');
     var M2mGroupController = require('m2m_group.Controller');
     var M2mGroupModel = require('m2m_group.Model');
     var M2mGroupRenderer = require('m2m_group.Renderer');
   
     var M2mGroupView = AbstractView.extend({
       display_name: 'Author',
       icon: 'fa-id-card-o',
       config: {
         Model: M2mGroupModel,
         Controller: M2mGroupController,
         Renderer: M2mGroupRenderer,
       },
       viewType: 'm2m_group',
       groupable: false,
       init: function (viewInfo, params) {
         this._super.apply(this, arguments);
         var attrs = this.arch.attrs;
         
         if (!attrs.m2m_field) {
           throw new Error('M2m view has not defined
           "m2m_field" attribute.');
         }
   
         // Model Parameters
         this.loadParams.m2m_field = attrs.m2m_field;
       },
     });
   
     view_registry.add('m2m_group', M2mGroupView);
   
     return M2mGroupView;
    });
   

8. 在/static/src/xml/qweb_template.xml文件中为视图添加QWeb模板：

   <t t-name="ViewM2mGroup">
     <div class="row ml16 mr16">
       <div t-foreach="groups" t-as="group" class="col-3">
         <t t-set="group_data" t-value="groups[group]" />
         <div class="card mt16">
           <img class="card-img-top" t-attfsrc="/web/image/#{group_data.model}/#{group}/image"/>
           <div class="card-body">
             <h5 class="card-title mt8"><t tesc="group_data['name']"/></h5>
           </div>
           <ul class="list-group list-group-flush">
             <t t-foreach="group_data['children']" tas="child">
               <li class="list-group-item"><i class="fa fa-book"/> <t t-esc="child.name"/></li>
             </t>
           </ul>
           <div class="card-body">
             <a href="#" class="btn btn-sm btn-primary o_primay_button" t-att-data-group="group">View books</a>
           </div>
         </div>
       </div>
     </div>
   </t>
   <div t-name="ViewM2mGroup.buttons">
     <button type="button" class="btn btn-primary">
       Add Record
     </button>
   </div>
   

9. 向后台资源中添加所有的JavaScript文件：

   ...
   <script type="text/javascript" src="/my_library/static/src/js/m2m_group_view.js" />
   <script type="text/javascript" src="/my_library/static/src/js/m2m_group_model.js" />
   <script type="text/javascript" src="/my_library/static/src/js/m2m_group_controller.js" />
   <script type="text/javascript" src="/my_library/static/src/js/m2m_group_renderer.js" />
   ...
   

10. 最后，为library.book模型添加我们的新视图：

    <record id="library_book_view_author" model="ir.ui.view">
      <field name="name">Library Book Author</field>
      <field name="model">library.book</field>
      <field name="arch" type="xml">
        <m2m_group m2m_field="author_ids" color_field="color">
        </m2m_group>
      </field>
     </record>
    

11. 在图书动作中添加m2m_group：

    ...
    <field name="view_mode">tree,m2m_group,form</field>
    ...
    

更新my_library模块以打开图书视图，然后，通过视图切换图标，打开我们刚刚添加的的新视图。会长成下面这样：

图15.3 – Many2many分组视图

📝重要信息：Odoo视图非常易于使用也很灵活。但是，通常容易和灵活的事物背后都是复杂的实现。对于Odoo的JavaScript视图正是如此：很容易使用，但实现很复杂。它包含大量的组成部分，如模型、渲染器、控制器、视图、QWeb模板等等。在接下来的部分中，我们添加了所有视图所需的构件并使用了library.book模型中的新视图。如果不想要手动做所有的工作，可从本书的GitHub仓库中获取模块示例文件。

实现原理…

第1和第2步中，我们在 ir.ui.view和ir.actions.act_window.view中注册了一个新视图类型，名为m2m_group。

第3步中，我们在base中添加了get_m2m_group_data方法。在base中添加该方法会让其在所有模型中都可以使用。这个方法会在JavaScript视图中通过RPC调用。该视图传递两个参数 - domain和m2m_field。在domain参数中，domain值会是由搜索视图域和动作域拼接所生成的作用域。m2m_field是我们希望对记录分组的字段名。这个字段在视图定义中进行设置。

在接下来的几步中，我们添加了要求构成视图的JavaScript文件。Odoo的JavaScript视图由视图、模型、渲染器和控制器组成。视图在Odoo的代码中有一些历史含义，因此在Odoo中模型、视图、控制器（MVC）变成了模型、渲染器和控制器（MRC）。总的来说，视图设置模型、渲染器和控制器，并设置MVC等级来变成下面这样：

图15.4 – 视图组件

我们来看一下模型、渲染器、控制器和视图的角色。模型、渲染器、控制器和视图的抽象版本拥有构成视图所需的所有基础部分。因此，在我们的示例中通过继承它们创建了模型、渲染器、控制器和视图。

这里有一些用于创建视图的不同部分的深入讲解：

• Model：模型的角色是存放视图状态。它向数据服务器发送RPC请求，然后向控制器和渲染器传递数据。然后我们重载__load和__reload方法。在视图初始化时，它调用__load()方法来获取数据，在搜索条件修改了或视图需要新状态时，会调用__reload()方法。在本例中，我们创建了通用的_fetchData()方法来做RPC调用获取数据。注意我们使用了在第3步中添加的get_m2m_group_data方法。会从控制器调用__get()方法来获取模型的状态。

• Controller：控制器的角色是管理模型和渲染器之间的调度、在渲染器中发生动作时，它传递该信息到控制器中并相应地执行动作。有时，它还会在模型中调用一些方法。此外，它管理控制面板中的按钮。在本例中，我们添加了一个新增记录的按钮。为进行实现，我们重载了AbstractController的renderButtons() 方法。我们还注册了custom_events，这样在点击了作者卡片中的按钮时，渲染器会触发控制器的事件来让其执行动作。

• Renderer：渲染器的角色是管理视图的DOM元素。每个视图可以按不同的方式渲染数据。在渲染器中，我们可以在变量state中获取模型的状态。它调用进行渲染的render() 方法。在本例中，我们通过显示视图的当前状态渲染了ViewM2mGroup QWeb模板。我们还将JavaScript的事件映射到了用户的动作。本节中我们还绑定了卡片中按钮的点击事件。在点击作者卡片按钮时，它会触发btn_clicked事件给控制器，并且会打开该作者是的图书列表。

  📝重要信息：注意事件和custom_events是不同的。事件是常规的JavaScript事件，而custom_events事件来自Odoo的JavaScript框架。自定义事件可以由trigger_up方法调用。

• View：视图的角色是获取所有要求构建视图的基本内容，如一组字段、上下文、视图结构和一些其它参数。然后，视图会初始化控制器、渲染器和模型三剑客。它会在MVC等级中进行设置。通常，它设置模型、视图和控制器所需要的参数。在本例中，我们需要m2m_field名称来获取模型中适当的分组数据，因此在其中设置了模型参数。以同样的方式，this.controllerParams和this.rendererParams可用于设置控制器和渲染器中的参数。

第8步中，我们添加了视图和控制面板按钮的QWeb模板。要了解有关QWeb模板更多的知识，请参见本章中的使用客户端QWeb模板一节。

**📝重要信息：**Odoo视图有大量不同用途的方法，我们在本节中学习了一些最重要的部分。如果想要更深入地学习视图，可以进入/addons/web/static/src/js/views/目录做更进一步的探索。该目录还包含抽象模型、控制器、渲染器和视图的代码。

第9步中，我们在资源中添加了JavaScript文件。

在最后的两步中，我们添加了针对library.book模型的视图定义。第10步中，我们对视图使用了<m2m_group>标签，并且我们还传递了m2m_field属性来作为一个选项。它会传递给模型来从服务端获取数据。

扩展知识…

如果你不想要引入新视图类型，而只是想要在视图中修改一些内容，可以在视图中使用js_class。例如，如果我们想要类似我们创建的看板的视图，可以像下面这样进行继承：

var CustomRenderer = KanbanRenderer.extend({
  ...
});

var CustomRendererModel = KanbanModel.extend({
  ...
});

var CustomRendererController = KanbanController.extend({
  ...
});

var CustomDashboardView = KanbanView.extend({
  config: _.extend({}, KanbanView.prototype.config, {
    Model: CustomDashboardModel,
    Renderer: CustomDashboardRenderer,
    Controller: CustomDashboardController,
  }),
});

var viewRegistry = require('web.view_registry');
viewRegistry.add('my_custom_view', CustomDashboardView);

然后我们可以通过js_class使用看板视图（注意服务端仍会将其看作一个看板视图）：

...
<field name="arch" type="xml">
  <kanban js_class="my_custom_view">
    ...
  </kanban>
</field>
...

调试客户端代码

关于调试服务端的代码，本书中有单独的一整章第七章 调试模块进行讲解。而对于客户端，本节会做一些初步讲解。

准备工作

本节并不依赖于具体的代码，但如果你希望能够重现其中的内容，请使用前一小节中的代码。

如何实现…

客户端脚本调试困难的原因在于网页客户端重度依赖于jQuery的异步事件。既然断点会中断执行，在调试时由定时问题会引起的bug很大机率不会发生。稍后我们会讨论一些策略。

1. 对于客户端调试，我们需要激活带资源的调试模式。如果不知道如何启用带资源的调试模式，请参见第一章 安装Odoo开发环境中的启用Odoo开发者工具一节。

2. 在需要调试的JavaScript函数中调用调试器：

   debugger;
   

3. 如果存在定时问题，通过JavaScript函数在控制台打印记录：

   console.log("I'm in function X currently");
   

4. 如果希望在模板渲染时进行调试，在QWeb中调用调试器：

   <t t-debug="" />
   

5. 也可以让QWeb在控制台中打印记录，如下所示：

   <t t-log="myvalue" />
   

所有这些依赖于浏览器为调试提供适当的功能。而所有主流浏览器都有相关支持，这里我们仅使用Chromium来作为演示。要使用调试工具，请点击右上角菜单按钮并选择More tools > Developer tools（译者注：通常可通过右击>检查元素或快捷键F12/Fn+F12进行调取）：

图15.5 – 在Chrome中打开开发者工具

实现原理…

打开调试器时，应该会看到类似下图的内容：

图15.6 – 暂停状态的调试器

这里我们可以在不同的标签页上访问大量的工具。下图中当前开启的标签为JavaScript调试器，我们通过点击行号在第31行设置了断点。每次我们的微件获取用户列表时，执行会停止在这一行，调试器让我们可以查看变量或修改它们的值。在右侧的查看列表中，我们还可以调用函数来测试它们的效果而无需持续保存脚本文件并重新加载页面。

我们前面所提到的debugger语句在打开开发者工具时会进行同样的中断。执行会停止，而浏览器会切换到Sources标签，打开所调试的文件并在有debugger的那一行高亮显示。

前面可能会打印日志的两处会出现在Console标签中。在遇到问题时这应该是第一个要去查看的标签，因为如果JavaScript因语法错误而完全没有加载或是类似的基本错误，都会在这个标签中看到说明情况的错误信息。

扩展知识…

使用Elements标签来查看浏览器当前显示页面的DOM结构。在对于熟悉已有微件生成的HTML代码非常有帮助，并且它通常还让我们可以调整类和CSS属性。对于测试布局调整非常有帮助。

Network标签给出对当前页面请求及时长的总览。这对于调试加载速度慢的页面很有帮助，因为在Network标签中我们可以看到请求的详情。如果选择一个具体的请求，可以查看其传递给服务器的负载及返回的结果，有助于在客户端弄清楚意料外行为产生的原因。还会看到所做请求的状态码，如因拼错文件名而找不到资源时显示404，

通过引导提升用户上手体验

在开发完大应用之后，向终端用户说明软件流程非常关键。Odoo框架包含一个内置的导览管理器。通过它，我们可以让用户通过了解具体的流程来得到指导。本节中，我们将创建一个在图书馆中创建图书的引导。

准备工作

我们将使用前面小节的my_library模块。导览仅在没有演示数据的数据库中显示，因此如果你使用的是带有demo数据的数据库，请为本节创建一个没有演示数据的数据库。

如何实现…

执行如下步骤来为图书馆添加引导：

1. 新增一个/static/src/js/my_library_tour.js文件并添加如下代码：

   odoo.define('my_library.tour', function (require) {
     "use strict";
     var core = require('web.core');
     var tour = require('web_tour.tour');
     var _t = core._t;
       tour.register('library_tour', {
       url: "/web",
     }, [tour.STEPS.SHOW_APPS_MENU_ITEM, {
         trigger: '.o_app[data-menuxmlid="my_library.library_base_menu"]',
         content: _t('Manage books and authors in<b>Library app</b>.'),
         position: 'right'
       }, {
         trigger: '.o_list_button_add',
         content: _t("Let's create new book."),
         position: 'bottom'
       }, {
         trigger: 'input[name="name"]',
         extra_trigger: '.o_form_editable',
         content: _t('Set the book title'),
         position: 'right',
       }, {
         trigger: '.o_form_button_save',
         content: _t('Save this book record'),
         position: 'bottom',
       }
     ]);
   });
   

2. 在后台资源中添加导览JavaScript文件：

   ...
   <script type="text/javascript" src="/my_library/static/src/js/my_library_tour.js" />
   ...
   

更新该模块并打开Odoo后台。此时就会看到一个如下图所示的引导：

图15.7 – 新手用户的引导步骤

请确保在Odoo实例中禁用了演示数据。带有演示数据的实例不会显示导览。

译者注：命令行安装可使用--without-demo=all -i base,my_library来不安装演示数据并且自动安装图书应用

实现原理…

引导管理器在web_tour.tour命名空间下。

第1步中，我们导入了web_tour.tour。然后就可以通过register()函数新增引导了。我们通过library_tour名称注册了导览并传递了运行导览的URL。

下一个参数是一个导览步骤的列表。每个导览步骤需要3个值。trigger用于选择引导显示在哪个元素中。这是一个JavaScript选择器。我们使用了菜单的XML ID， 因为它存在于DOM中。

第1步**tour.stepUtils.showAppsMenuItem()**是为主菜单预定义的导览步骤。下一个键是content，在用户鼠标悬停在引导水滴图标上时显示该内容。我们使用了_t()函数，因为希望翻译该字符串，而position键用于决定引导图标的位置。可以选择的值有top, right, left和bottom。

📝重要信息：引导会提升用于使用体验以及对集成测试的管理。在内部以测试模式运行Odoo时，也会运行引导并在导览未能完成时引发测试用例失败。

移动应用JavaScript（企业版）

Odoo 10引入了Odoo移动应用。它提供执行移动端动作的小工具，如震动手机、显示toast弹出消息、扫描二维码等等。

准备工作

我们将使用前一节的my_library模块。我们将通过移动应用在修改了color字段值时显示toast消息。

⚠️警告：Odoo移动应用仅支持企业版，因此如果你没有企业版，则无法进行测试。

如何实现…

执行如下步骤来在Odoo移动应用中显示弹出消息：

1. 在field_widget.js中导入web_mobile.rpc：

   var mobile = require('web_mobile.rpc');
   

2. 修改clickPill方法来让用户在移动设备上修改颜色时显示弹出消息:：

   clickPill: function (ev) {
       var $target = $(ev.currentTarget);
       var data = $target.data();
       this._setValue(data.val.toString());
       if (mobile.methods.showToast) {
           mobile.methods.showToast({'message': 'Color changed'});
       }
   }
   

升级模块并在移动应用中打开library.book模型的表单视图。在修改颜色时，会看到如下所示的弹出消息：

图15.8 – 修改颜色的Toast消息

译者注：企业版自定义模块需在menu_item中指定web_icon才能正常显示应用的图标。

实现原理…

web_mobile.rpc提供了移动设备与Odoo JavaScript之间的桥梁。它暴露一些基本移动工具。本例中，我们使用了showToast方法来在移动应用中显示弹窗信息。我们还需要检查该函数的可用性。背后的原因是一些手机可能不支持某些功能，例如在设备没有摄像头时，就无法使用scanBarcode()方法。在这种情况下，为避免错误，我们需要将代码包裹在 if 条件中。

扩展知识…

Odoo中的移动端工具有如下这些：

• showToast(): 显示弹出消息
• vibrate(): 手机震动
• showSnackBar(): 显示带有按钮的滑动栏
• showNotification(): 显示手机提示消息
• addContact(): 在电话薄中新增联系人
• scanBarcode(): 扫描二维码
• switchAccount(): 在Android中打开账号切换窗口

学习更多有关移动端的JavaScript知识，请参见：https://www.odoo.com/documentation/14.0/developer/reference/mobile.html。