Odoo Javascript 參考指南

本篇文章轉載自：https://www.jianshu.com/p/1a47fac01077   ，僅用來自己記錄學習。

 

本文介紹了odoo javascript框架。從代碼行的角度來看，這個框架不是一個大的應用程序，但它是非常通用的，因為它基本上是一個將聲明性接口描述轉換為活動應用程序的機器，能夠與數據庫中的每個模型和記錄交互。甚至可以使用Web客戶端修改Web客戶端的接口。

這里有一個有用的html版本的文檔：Javascript API

概覽

這個Javascript框架主要設計用於三個地方使用：

• web客戶端：這是一個私有的web應用，可以在其中查看和編輯業務數據。這是一個單頁應用程序（永遠不會重新加載該頁，只在需要時從服務器提取新數據）。
• 網站：這是Odoo的公共部分。它允許身份不明的用戶作為客戶端瀏覽某些內容、購物或執行許多操作。這是一個經典的網站：各種各樣的帶有控制器的路由和共同協作的Javascript代碼。
• POS：這是銷售點的接口。它是一個特定的但也應用程序。

Web客戶端

單頁應用

簡而言之，webclient實例是整個用戶界面的根組件。它的職責是協調所有的子組件，並提供服務，如RPC、本地存儲等等。

在運行時，Web客戶端是單頁應用程序。每次用戶執行操作時，它不需要從服務器請求整頁。相反，它只請求它所需要的，然后替換/更新視圖。此外，它還管理URL：它與Web客戶機狀態保持同步。

這意味着，當用戶在處理odoo時，Web客戶機類（和動作管理器）實際上創建並銷毀了許多子組件。狀態是高度動態的，每個小部件都可以隨時銷毀。

Web客戶端JS代碼概覽

這里，我們在web/static/src/js插件中快速概述了web客戶機代碼。注意，這是故意不詳盡的，我們只涉及最重要的文件/文件夾。

• boot.js : 這是定義模塊系統的文件,它需要首先加載。
• core/ : 這是較低級別的構建基塊的集合。值得注意的是，它包含類系統、小部件系統、並發實用程序和許多其他類/函數。
• chorm/ :在這個文件夾中，我們有大多數大的小部件，它們構成了大部分用戶界面。
• chrome/abstract_web_client.js and chrome/web_client.js : 這些文件一起定義了WebClient小部件(widget)，它是Web客戶機的根小部件（wideget）。
• chrome/action_manager.js : 這是將動作（action）轉換為小部件(widget)（例如看板或表單視圖）的代碼。
• chrome/search_X.js : 所有這些文件定義了搜索視圖（它不是Web客戶機視圖中的視圖，僅從服務器視圖）
• fields : 這里定義了所有主要字段視圖小部件（widget）
• views : 這是視圖所在的位置

資源管理

在Odoo中管理資源並不像在其他應用程序中那樣簡單。其中一個原因是，在其中一些情況中我們有各種各樣的狀態，但不是所有的資源都是必需的。例如，Web客戶端、銷售點、網站甚至移動應用程序的需求是不同的。此外，有些資源可能很大，但很少需要。在這種情況下，我們有時希望它們被懶惰地加載。

主要思想是我們用XML定義一組包。捆綁包在這里定義為一組文件（javascript、css、scss）。在odoo中，最重要的包在addons/web/views/webclient_templates.xml文件中定義。看起來是這樣的：

<template id="web.assets_common" name="Common Assets (used in backend interface and website)"> <link rel="stylesheet" type="text/css" href="/web/static/lib/jquery.ui/jquery-ui.css"/> ... <script type="text/javascript" src="/web/static/src/js/boot.js"></script> ... </template> 

然后，可以使用t-call-assets指令將捆綁包中的文件插入到模板中：

<t t-call-assets="web.assets_common" t-js="false"/> <t t-call-assets="web.assets_common" t-css="false"/> 

下面是當服務器使用以下指令呈現模板時發生的情況：

• 包中描述的所有SCSS文件都編譯為CSS文件。名為file.scss的文件將編譯在名為file.scss.css的文件中。
• 如果我們在debug=assets模式：
     * t-js屬性設置為false的t-call-assets指令將替換為指向css文件的樣式表標記列表。
     * t-css屬性設置為false的t-call-assets指令將替換為指向JS文件的腳本標記列表。
• 如果我們不在debug=assets模式
     * CSS文件將被連接並縮小，然后拆分為不超過4096個規則的文件（以繞過IE9的舊限制）。然后，我們根據需要生成盡可能多的樣式表標簽
     * JS文件被連接並縮小，然后生成一個腳本標記。

請注意，資源文件是緩存的，因此從理論上講，瀏覽器應該只加載它們一次。

主包

當odoo服務器啟動時，它檢查包中每個文件的時間戳，如果需要，它將創建/重新創建相應的包。

以下是大多數開發人員需要知道的一些重要包：

• web.assets_common : 此包包含Web客戶端、網站以及銷售點（POS）所共有的大多數資源。這應該包含用於Odoo框架的較低級別的構建塊。注意，它包含boot.js文件，它定義了odoo模塊系統。
• web.assets_backend :這個包包含特定於Web客戶端的代碼（特別是Web客戶端/動作管理器/視圖）
• web.assets_frontend :這個包是關於所有特定於公共網站的：電子商務、論壇、博客、事件管理…

在一個資源包里添加文件

將位於addons/web中的文件添加到bundle的正確方法很簡單：只需將腳本或樣式表標記添加到文件webclient_templates.xml中的bundle即可。但是當我們使用不同的插件（addon）時，我們需要從該插件添加一個文件。在這種情況下，應分三步進行：

1. 添加一個 assets.xml 文件到views/文件夾
2. 添加字符'views/assets.xml' 到manifest文件的鍵'data'的值里
3. 創建所需包的繼承視圖，並使用xpath表達式添加文件。例如：

<template id="assets_backend" name="helpdesk assets" inherit_id="web.assets_backend"> <xpath expr="//script[last()]" position="after"> <link rel="stylesheet" type="text/scss" href="/helpdesk/static/src/scss/helpdesk.scss"/> <script type="text/javascript" src="/helpdesk/static/src/js/helpdesk_dashboard.js"></script> </xpath> </template> 

請注意，當用戶加載odoo web客戶端時，包中的所有文件都會立即加載。這意味着每次通過網絡傳輸文件（瀏覽器緩存處於活動狀態時除外）。在某些情況下，最好使用Lazyload的一些資產。例如，如果一個小部件需要一個大的庫，而這個小部件不是體驗的核心部分，那么在實際創建小部件時，最好只加載庫。widget類實際上已經為這個用例內置了支持。(查閱QWeb模板引擎部分)

如果文件沒有加載/更新應該怎么辦

文件可能無法正確加載有許多不同的原因。您可以嘗試以下幾點來解決此問題：

• 一旦服務器啟動，它就不知道資源文件是否已被修改。因此，您可以簡單地重新啟動服務器來重新生成資源。
• 檢查控制台（在開發工具中，通常用F12打開），確保沒有明顯的錯誤
• 嘗試在文件的開頭添加console.log（在任何模塊定義之前），這樣您就可以查看文件是否已加載。
• 在用戶界面中，在調試模式下（在此處插入鏈接到調試模式），有一個選項可以強制服務器更新其資源文件。
• 使用debug=assets模式。這實際上會繞過資源包（請注意，它實際上並不能解決問題，服務器仍然使用過時的包）
• 最后，對於開發人員來說，最方便的方法是使用--dev=all選項啟動服務器。這將激活文件監視程序選項，必要時將自動使資源無效。請注意，如果操作系統是Windows，它就不能很好地工作。
• 記住刷新頁面！
• 或者保存代碼文件…

重新創建資源文件后，需要刷新頁面，重新加載正確的文件（如果不起作用，文件可能被緩存了）。

Javascript模塊系統

一旦我們能夠將我們的javascript文件加載到瀏覽器中，我們就需要確保以正確的順序加載它們。為了實現這一點，odoo定義了一個小模塊系統（位於addons/web/static/src/js/boot.js文件中，需要首先加載該文件）。

在AMD的啟發下，odoo模塊系統通過在全局odoo對象上定義函數define來工作。然后我們通過調用該函數來定義每個javascript模塊。在odoo框架中，模塊是一段將盡快執行的代碼。它有一個名稱，可能還有一些依賴項。當它的依賴項被加載時，模塊也將被加載。模塊的值就是定義模塊的函數的返回值。

一個例子，看起來像這樣：

// in file a.js odoo.define('module.A', function (require) { "use strict"; var A = ...; return A; }); // in file b.js odoo.define('module.B', function (require) { "use strict"; var A = require('module.A'); var B = ...; // something that involves A return B; }); 

定義模塊的另一種方法是在第二個參數中明確地給出依賴項列表。

odoo.define('module.Something', ['module.A', 'module.B'], function (require) { "use strict"; var A = require('module.A'); var B = require('module.B'); // some code }); 

如果某些依賴項丟失/未就緒，那么模塊將不會被加載。幾秒鍾后控制台中將出現警告。

請注意，不支持循環依賴項。這是有道理的，但這意味着需要謹慎。

定義一個模塊

odoo.define 方法給了三個參數：

• moduleName: javascript模塊的名稱。它應該是一個唯一的字符串。慣例是在odoo插件（addon）的名字后面加上一個具體的描述。例如，“web.widget”描述在web插件中定義的模塊，該模塊導出一個widget類（因為第一個字母大寫）。
  如果名稱不唯一，將引發異常並顯示在控制台中
• dependencies : 第二個參數是可選的。如果給定，它應該是一個字符串列表，每個字符串對應一個JavaScript模塊。這描述了在執行模塊之前需要加載的依賴項。如果這里沒有明確地給出依賴項，那么模塊系統將通過調用ToString從函數中提取它們，然后使用regexp查找所有Require語句。
• 最后一個參數是定義模塊的函數。它的返回值是模塊的值，可以傳遞給其他需要它的模塊。注意，異步模塊有一個小的異常，請參見下一節。
  如果發生錯誤，將在控制台中記錄（在調試模式下）：
• Missing dependencies: 這些模塊不會出現在頁面中。可能是javascript文件不在頁面中或模塊名稱錯誤
• Failed Modules : 一個Javascript錯誤被檢測到
• Rejected modules ：塊返回拒絕的延遲。它（及其相關模塊）未加載。
• Rejected linked modules: 依賴被拒絕模塊的模塊
• Non loaded modules : 模塊依賴了一個缺失/失敗的模塊

異步模塊

模塊可能需要在准備就緒之前執行一些工作。例如，它可以做一個RPC來加載一些數據。在這種情況下，模塊只需返回一個deferred（promise）。在這種情況下，模塊系統只需等待deferred完成，然后注冊模塊。

odoo.define('module.Something', ['web.ajax'], function (require) { "use strict"; var ajax = require('web.ajax'); return ajax.rpc(...).then(function (result) { // some code here return something; }); }); 

最好的練習

• 記住模塊名的約定：插件名加上模塊名后綴
• 在模塊頂部聲明所有依賴項。此外，它們應該按模塊名稱的字母順序排序。這樣更容易理解您的模塊。
• 在末尾聲明所有導出的值
• 盡量避免從一個模塊導出過多的內容。通常最好在一個（小/更小）模塊中簡單地導出一件事情。
• 異步模塊可以用來簡化一些用例。例如，web.dom_ready模塊返回一個deferred ，當dom實際就緒時，這個deferred 將被解決。因此，另一個需要dom的模塊可以在某個地方簡單地有一個require（“web.dom_ready”）語句，並且只有當dom准備好時才會執行代碼。
• 盡量避免在一個文件中定義多個模塊。這在短期內可能很方便，但實際上很難維護。

類系統

Odoo是在ECMAScript 6類可用之前開發的。在ECMAScript 5中，定義類的標准方法是定義一個函數並在其原型對象上添加方法。這很好，但是當我們想要使用繼承、混合時，它稍微復雜一些。
出於這些原因，Odoo決定使用自己的類系統，這是受到約翰·雷西格的啟發。基類位於web.class文件class.js中。

創建一個子類

讓我們討論如何創建類。主要機制是使用extend方法（這或多或少相當於ES6類中的extend）。

var Class = require('web.Class'); var Animal = Class.extend({ init: function () { this.x = 0; this.hunger = 0; }, move: function () { this.x = this.x + 1; this.hunger = this.hunger + 1; }, eat: function () { this.hunger = 0; }, }); 

在本例中，init函數是構造函數。它將在創建實例時調用。通過使用new關鍵字創建實例。

繼承

可以方便地繼承現有的類。這只需在超類上使用extend方法即可完成。當調用一個方法時，框架會秘密地將一個特殊的方法_super重新綁定到當前調用的方法中。這允許我們在需要調用父方法時使用this._super。

var Animal = require('web.Animal'); var Dog = Animal.extend({ move: function () { this.bark(); this._super.apply(this, arguments); }, bark: function () { console.log('woof'); }, }); var dog = new Dog(); dog.move() 

混合

Odoo類系統不支持多重繼承，但是對於那些需要共享某些行為的情況，我們有一個混合系統：extend方法實際上可以接受任意數量的參數，並將它們組合到新的類中。

var Animal = require('web.Animal'); var DanceMixin = { dance: function () { console.log('dancing...'); }, }; var Hamster = Animal.extend(DanceMixin, { sleep: function () { console.log('sleeping'); }, }); 

在這個例子中，Hamter 類是Animal的子類，但是它也混合了DanceMixin.

修改現有的類

這並不常見，但有時我們需要在適當的位置修改另一個類。目標是有一個機制來改變一個類和所有未來/現在的實例。這是通過使用include方法完成的：

var Hamster = require('web.Hamster'); Hamster.include({ sleep: function () { this._super.apply(this, arguments); console.log('zzzz'); }, }); 

這顯然是一個危險的操作，應該小心操作。但是，按照odoo的結構，有時需要在一個插件中修改在另一個插件中定義的widget/class的行為。請注意，它將修改類的所有實例，即使它們已經創建。

小部件（Widget）

widget類實際上是用戶界面的一個重要構建塊。幾乎用戶界面中的所有內容都在小部件（widget）的控制之下。widget類在widget.js中的module web.widget中定義。
簡而言之，widget類提供的特性包括：

• 小部件之間的父/子關系（PropertiesMixin）
• **具有安全功能的廣泛生命周期管理 **（e.g. 在銷毀父級期間自動銷毀子窗口小部件）
• 自動渲染qweb模板
• 幫助與外部環境交互的各種實用功能。
  一個計數的小部件例子：

var Widget = require('web.Widget'); var Counter = Widget.extend({ template: 'some.template', events: { 'click button': '_onClick', }, init: function (parent, value) { this._super(parent); this.count = value; }, _onClick: function () { this.count++; this.$('.val').text(this.count); }, }); 

對於本例，假設模板some.template（並且正確加載：模板位於一個文件中，該文件在模塊清單中的qweb鍵中正確定義）如下：

<div t-name="some.template"> <span class="val"><t t-esc="widget.count"/></span> <button>Increment</button> </div> 

這個例子說明了小部件類的一些特性，包括事件系統、模板系統、帶有初始父參數的構造函數。

小部件的生命周期

與許多組件系統一樣，widget類有一個定義良好的生命周期。通常的生命周期如下：調用init，然后willStart，然后rendering，然后start，最后destroy。

Widget.init(parent)
這是構造函數。init方法應該初始化小部件的基本狀態。它是同步的，可以被重寫以從小部件的創建者/父對象獲取更多參數。

Arguments : parent（Widget（））–新的widget的父級，用於處理自動銷毀和事件傳播。對於沒有父級的小部件，可以為null。

Widget.willStart()
當一個小部件被創建並被附加到DOM的過程中，框架將調用這個方法一次。willstart方法是一個鈎子，它應該返回一個deferred。JS框架將等待這個deferred完成，然后再繼續渲染步驟。注意，此時小部件沒有dom根元素。willstart鈎子主要用於執行一些異步工作，例如從服務器獲取數據。

[Rendering]()
此步驟由框架自動完成。框架會檢查小部件上是否定義了template鍵。如果定義了，那么它將在呈現上下文中使用綁定到小部件的widget鍵呈現該模板（請參見上面的示例：我們在QWeb模板中使用widget.count來讀取小部件的值）。如果沒有定義模板，則讀取 tagName 鍵並創建相應的DOM元素。渲染完成后，我們將結果設置為小部件的$el屬性。在此之后，我們將自動綁定events和custom_events鍵中的所有事件。

Widget.start()
渲染完成后，框架將自動調用Start方法。這對於執行一些特殊的后期渲染工作很有用。例如，設置庫。
必須返回deferred以指示其工作何時完成。

Returns: deferred 對象

Widget.destroy()
這始終是小部件生命周期中的最后一步。當小部件被銷毀時，我們基本上執行所有必要的清理操作：從組件樹中刪除小部件，取消綁定所有事件，…
當小部件的父級被銷毀時自動調用，如果小部件沒有父級，或者如果它被刪除但父級仍然存在，則必須顯式調用。

請注意，不必調用willstart和start方法。可以創建一個小部件（將調用init方法），然后銷毀（destroy方法），而不需要附加到DOM。如果是這種情況，將不會調用will start和start。

Widget API

Widget.tagName
如果小部件沒有定義模板，則使用。默認為DIV，將用作標記名來創建要設置為小部件的dom根的dom元素。可以使用以下屬性進一步自定義生成的dom根目錄：

Widget.id
用於在生成的dom根上生成id屬性。請注意，這是很少需要的，如果一個小部件可以多次使用，這可能不是一個好主意。

Widget.className
用於在生成的dom根上生成class屬性。請注意，它實際上可以包含多個css類：“some-class other-class”

Widget.attributes
屬性名到屬性值的映射（對象文本）。這些k:v對中的每一個都將被設置為生成的dom根上的dom屬性。

Widget.el
將原始dom元素設置為小部件的根（僅在start lifecyle方法之后可用）

Widget.$el
jquery封裝的el，（僅在Start Lifecyle方法之后可用）

Widget.template
應設置為QWeb模板的名稱。如果設置了，模板將在小部件初始化之后但在其啟動之前呈現。模板生成的根元素將被設置為小部件的dom根。

Widget.xmlDependencies
呈現小部件之前需要加載的XML文件的路徑列表。這不會導致加載已加載的任何內容。如果您想延遲加載模板，或者想要在網站和Web客戶機界面之間共享一個小部件，這很有用。

var EditorMenuBar = Widget.extend({ xmlDependencies: ['/web_editor/static/src/xml/editor.xml'], ... 

Widget.events
事件是事件選擇器（由空格分隔的事件名稱和可選CSS選擇器）到回調的映射。回調可以是小部件方法或函數對象的名稱。在這兩種情況下，這都將設置為小部件：

    'click p.oe_some_class a': 'some_method',
    'change input': function (e) {
        e.stopPropagation();
    }
},

選擇器用於jquery的事件委托，回調只對與選擇器匹配的dom根的后代觸發。如果選擇器被省略（只指定了一個事件名），那么事件將直接設置在小部件的dom根上。
注意：不鼓勵使用內聯函數，將來可能會刪除它。

Widget.custom_events

returns: true 如果小部件正在或者已經被銷毀，否則false

Widget.$(selector)
將指定為參數的CSS選擇器應用於小部件的dom根:
this.$(selector);
功能上與以下相同：
this.$el.find(selector);

arguments: selector(string)-CSS選擇器
return:jQuery 對象

這個助手方法類似於Backbone.View.$

Widget.setElement(element)
將小部件的dom根重新設置為提供的元素，還處理重新設置dom根的各種別名以及取消設置和重新設置委托事件。

arguments: element(Element) -一個DOM元素或者jQuery對象設置為小部件的根DOM

在DOM中插入一個小部件

Widget.appendTo(element)
渲染小部件並將它作為子元素插入到目標元素后面，使用.appentTo()

Widget.prependTo(element)
渲染小部件並將它作為子元素插入到目標元素前面，使用.prependTo()

Widget.insertAfter(element)
渲染小部件並將它作為目標元素的前一個同級插入，使用.insertAfter()

Widget.insertBefore(element)
渲染小部件並將其作為目標的后一個同級插入，使用.insertBefore()

所有這些方法都接受相應jquery方法接受的任何內容（css選擇器、dom節點或jquery對象）。他們都會返回一個 deferred，並承擔三個任務：

• 通過以下方式呈現小部件的根元素：
  renderElement()
• 使用jquery在DOM中插入小部件的根元素
  匹配的方法
• 啟動小部件並返回啟動結果

小部件指南

• 在一般應用和模塊中中，標識 （id 屬性）應該避免使用，ID限制了組件的可重用性，並使代碼更加脆弱。大多數情況下，它們可以替換為Nothing、Classes或保留對dom節點或jquery元素的引用。
  如果ID是絕對必要的（因為第三方庫需要一個），則應使用_.uniqueId（）部分生成ID，例如：
  this.id = _.uniqueId('my-widget-');
• 避免使用可預測/通用的CSS類名。類名稱（如“content”或“navigation”）可能與所需的含義/語義匹配，但其他開發人員可能也有相同的需求，從而造成命名沖突和意外行為。通用類名的前綴應該是它們所屬組件的名稱（創建“非正式”名稱空間，就像在C或Objective-C中那樣）。
• 應避免使用全局選擇器。因為一個組件可以在一個頁面中多次使用（ODoo中的一個例子是儀表板），所以查詢應該限制在給定組件的范圍內。未篩選的選擇（如$(selector)或document.querySelectorAll（selector））通常會導致意外或錯誤的行為。odoo web的widget（）有一個提供dom根（_().)
• 更一般地說，不要假設您的組件擁有或控制任何超出其個人$el的東西（因此，避免使用對父部件的引用）。
• HTML模板/渲染應該使用QWeb，除非非常簡單。
• 所有交互組件（向屏幕顯示信息或截取DOM事件的組件）必須繼承自widget（），並正確實現和使用其API和生命周期。

Qweb模板引擎

Web客戶端使用QWeb模板引擎來呈現小部件（除非它們重寫renderelement方法來執行其他操作）。QWebJS模板引擎基於XML，主要與Python實現兼容。

現在，讓我們解釋如何加載模板。每當Web客戶端啟動時，都會對/web/web client/qweb路由進行RPC。然后，服務器將返回在每個已安裝模塊的數據文件中定義的所有模板的列表。正確的文件列在每個模塊清單的QWeb條目中。

在啟動第一個小部件之前，Web客戶機將等待加載該模板列表。

這個機制可以很好地滿足我們的需求，但有時我們希望懶加載模板。例如，假設我們有一個很少使用的小部件。在這種情況下，我們可能不希望將其模板加載到主文件中，以便使Web客戶機稍微輕一些。在這種情況下，我們可以使用小部件的xmlpendencies鍵：

var Widget = require('web.Widget'); var Counter = Widget.extend({ template: 'some.template', xmlDependencies: ['/myaddon/path/to/my/file.xml'], ... }); 

有了這個，計數器小部件將以willstart方法加載xmlpendencies文件，這樣在執行呈現時模板就可以准備好了。

事件系統

目前，odoo支持兩個事件系統：一個允許添加偵聽器和觸發事件的簡單系統，以及一個更完整的系統，它還可以使事件“冒泡”。

這兩個事件系統都在文件mixins.js的eventspatchemixin中實現。這個mixin包含在widget類中。

基礎事件系統

這是歷史上第一個事件系統。它實現了一個簡單的總線模式。我們有4種主要方法：

• on : 在一個事件上注冊監聽器
• off: 移除事件的監聽器
• once: 注冊一個只使用一次的監聽器
• trigger：跟蹤一個事件。這會調用所有監聽器。
  一下是一個怎么使用事件系統的例子：

var Widget = require('web.Widget'); var Counter = require('myModule.Counter'); var MyWidget = Widget.extend({ start: function () { this.counter = new Counter(this); this.counter.on('valuechange', this, this._onValueChange); var def = this.counter.appendTo(this.$el); return $.when(def, this._super.apply(this, arguments); }, _onValueChange: function (val) { // do something with val }, }); // in Counter widget, we need to call the trigger method: ... this.trigger('valuechange', someValue); 

不鼓勵使用此事件系統，我們計划用擴展事件系統中的trigger-up方法替換每個trigger方法。

擴展的事件系統

自定義事件小部件是一個更高級的系統，它模擬DOM事件API。每當一個事件被觸發時，它將“冒泡”組件樹，直到它到達根小部件，或者停止。

• trigger_up:這是一種方法，它將創建一個小的odooEvent並將其分派到組件樹中。請注意，它將從觸發事件的組件開始
• custom_events:這相當於事件字典，但是對於odoo事件來說。
  OdoEvent類非常簡單。它有三個公共屬性：target（觸發事件的小部件）、name（事件名稱）和data（有效負載）。它還有兩種方法：stopPropagation 和 is_stopped.。
  上一個示例可以更新為使用自定義事件系統：

var Widget = require('web.Widget'); var Counter = require('myModule.Counter'); var MyWidget = Widget.extend({ custom_events: { valuechange: '_onValueChange' }, start: function () { this.counter = new Counter(this); var def = this.counter.appendTo(this.$el); return $.when(def, this._super.apply(this, arguments); }, _onValueChange: function(event) { // do something with event.data.val }, }); // in Counter widget, we need to call the trigger_up method: ... this.trigger_up('valuechange', {value: someValue}); 

注冊

Odoo生態系統的一個常見需求是從外部擴展/更改基本系統的行為（通過安裝應用程序，即不同的模塊）。例如，可能需要在某些視圖中添加新的小部件類型。在這種情況下，以及其他許多情況下，通常的過程是創建所需的組件，然后將其添加到注冊表（注冊步驟），以使Web客戶機的其余部分知道它的存在。
一下是一些在系統中可用的注冊：

• 字段注冊表（由“web.field_registry”導出）。字段注冊表包含Web客戶端已知的所有字段小部件。每當視圖（通常是表單或列表/看板）需要字段小部件時，這就是它將要查找的地方。典型的用例如下所示：

var fieldRegistry = require('web.field_registry'); var FieldPad = ...; fieldRegistry.add('pad', FieldPad); 

注意，每個值都應該是AbstractField的子類

• 視圖注冊表：此注冊表包含Web客戶端已知的所有JS視圖

（尤其是視圖管理器）。此注冊表的每個值都應該是AbstractView的子類

• 動作注冊表：我們跟蹤此注冊表中的所有客戶端動作。這個是動作管理器在需要創建客戶端操作時查找的位置。在版本11中，每個值應該只是小部件的一個子類。但是，在版本12中，值必須是abstractAction。

小部件之間的通信

有許多組件之間的通信方式

• 從父級到它的子級
  一個簡單的例子。父不見可以簡單的調用子部件方法：
  this.someWidget.update(someInfo);

• 從一個小部件到它的父/某個祖先
  在這種情況下，小部件的工作只是通知其環境發生了什么事情。由於我們不希望小部件具有對其父部件的引用（這將使小部件與其父部件的實現相結合），因此繼續操作的最佳方法通常是使用觸發器trigger_up方法觸發一個事件，該事件將冒泡到組件樹中：
  this.trigger_up('open_record', { record: record, id: id});
  此事件將在小部件上觸發，然后將冒泡並最終被某些上游小部件捕獲：

var SomeAncestor = Widget.extend({ custom_events: { 'open_record': '_onOpenRecord', }, _onOpenRecord: function (event) { var record = event.data.record; var id = event.data.id; // do something with the event. }, }); 

• 交叉組件
  通過總線可以實現跨組件通信。這不是首選的通信形式，因為它有使代碼難以維護的缺點。但是，它具有分離組件的優勢。在這種情況下，這只是通過觸發和監聽總線上的事件來完成的。例如：

// in WidgetA var core = require('web.core'); var WidgetA = Widget.extend({ ... start: function () { core.bus.on('barcode_scanned', this, this._onBarcodeScanned); }, }); // in WidgetB var WidgetB = Widget.extend({ ... someFunction: function (barcode) { core.bus.trigger('barcode_scanned', barcode); }, }); 

在本例中，我們使用web.core導出的總線，但這不是必需的。可以為特定目的創建總線。

服務services

在11.0版中，我們引入了服務的概念。主要的想法是給子組件一種受控制的方式來訪問它們的環境，這種方式允許框架進行足夠的控制，並且是可測試的。
服務系統圍繞三個理念進行組織：services、service providers和widget。它的工作方式是小部件觸發（使用trigger_up）事件，這些事件冒泡到服務提供者，服務提供者將要求服務執行任務，然后可能返回一個答案。

服務service

服務是AbstractService類的實例。它基本上只有一個名稱和一些方法。它的工作是執行一些工作，通常是一些依賴於環境的工作。
例如，我們有Ajax服務（任務是執行RPC）、本地存儲（與瀏覽器本地存儲交互）和許多其他服務。
以下是有關如何實現Ajax服務的簡化示例：

var AbstractService = require('web.AbstractService'); var AjaxService = AbstractService.extend({ name: 'ajax', rpc: function (...) { return ...; }, }); 

這個服務被叫做‘ajax’而且定義了一個方法，rpc.

服務提供者Service Provider

為了使服務正常工作，有必要讓一個服務提供者准備好分派定制事件。在后端（Web客戶端），這是由主Web客戶端實例完成的。請注意，服務提供程序的代碼來自ServiceProviderMin。

部件widget

小部件是請求服務的部分。為了做到這一點，它只需觸發一個事件調用服務（通常通過使用helper函數調用）。此事件將冒泡並將意圖傳達給系統的其余部分。
在實踐中，有些函數被頻繁地調用，以至於我們有一些助手函數使它們更容易使用。例如，_rpc方法是幫助生成rpc的助手。

var SomeWidget = Widget.extend({ _getActivityModelViewID: function (model) { return this._rpc({ model: model, method: 'get_activity_view_id' }); }, }); 

如果一個小部件被銷毀，它將從主組件樹中分離出來，並且沒有父組件。在這種情況下，事件不會冒泡，這意味着工作不會完成。這通常正是我們從一個被破壞的小部件中想要的。

RPCs

RPC功能由Ajax服務提供。但大多數人可能只會與_rpc助手進行交互。
在處理odoo時，通常有兩個用例：一個需要在（python）模型上調用方法（這需要通過控制器call_kw），或者一個需要直接調用控制器（在某些路由上可用）。

• 在python模型中調用方法

return this._rpc({ model: 'some.model', method: 'some_method', args: [some, args], }); 

• 直接調用控制器

return this._rpc({ route: '/some/route/', params: { some: kwargs}, }); 

通知

odoo框架有一種標准的方式來向用戶傳遞各種信息：通知，它顯示在用戶界面的右上角。
通知有兩種類型：

• notification: 有助於顯示一些反饋。例如，每當用戶取消訂閱某個頻道時。
• warning:用於顯示一些重要/緊急信息。通常是系統中的大多數（可恢復的）錯誤。

此外，通知還可以用於向用戶詢問問題，而不會干擾其工作流。想象一下，通過VoIP接收到的一個電話呼叫：可以顯示一個帶有兩個按鈕的粘性通知：接受和拒絕。

通知系統

Odoo中的通知系統設計有以下組件：

• a Notification widget:這是一個簡單的小部件，用於創建和顯示所需的信息。
• a NotificationService:一種服務，其職責是在請求完成時（使用custom_event）創建和銷毀通知。請注意，Web客戶端是一個服務提供者。
• ServiceMixin中的兩個助手功能：do_notify和do_warn

顯示通知

顯示通知的最常見方法是使用來自ServiceMixin的兩種方法：

• do_notify(title, message, sticky, className):
  顯示一個通知類型的通知：
     * title:string. 將會在頂部顯示為標題
     * message:string. 通知的內容
     * sticky : boolean,optional. 如果為真，這個通知將會一直保留直到用戶解除。否則，通知將會在一段很短的時間之后自動關閉。
     * calssname:string,optional.這是一個css類的名字，將會自動添加到通知中。這對樣式有用，即使不鼓勵使用它。

• do_warn(title, message, sticky, className):
  顯示一個警告類型的通知。
     * title:string.將會在頂部顯示為標題
     * message：string.通知的內容
     * sticky : boolean,optional. 如果為真，這個通知將會一直保留直到用戶解除。否則，通知將會在一段很短的時間之后自動關閉。
     * calssname:string,optional.這是一個css類的名字，將會自動添加到通知中。這對樣式有用，即使不鼓勵使用它。
  這里有兩個如何使用這兩個方法的例子：

// note that we call _t on the text to make sure it is properly translated.
this.do_notify(_t("Success"), _t("Your signature request has been sent."));

this.do_warn(_t("Error"), _t("Filter name is required."));

任務欄Systray

Systray是界面菜單欄的右側部分，Web客戶端在其中顯示一些小部件，如消息菜單。
當菜單創建SystrayMenu時，它將查找所有已注冊的小部件，並將它們作為子小部件添加到適當的位置。
目前沒有針對Systray小工具的特定API。它們應該是簡單的小部件，並且可以像使用trigger-up方法的其他小部件一樣與環境通信。

添加一個新得任務欄項目

沒有Systray注冊表。添加小部件的正確方法是將其添加到類變量systraymenu.items中。

var SystrayMenu = require('web.SystrayMenu'); var MySystrayWidget = Widget.extend({ ... }); SystrayMenu.Items.push(MySystrayWidget); 

排序Ordering

在將小部件添加到自己之前，Systray菜單將按Sequence屬性對項目進行排序。如果原型上不存在該屬性，則將使用50。因此，要將Systray項目定位在靠后，可以設置一個非常高的序列號（反之，將其放在靠前的是一個較低的序列號）。
MySystrayWidget.prototype.sequence = 100;

翻譯管理

有些翻譯是在服務器端進行的（基本上是由服務器呈現或處理的所有文本字符串），但是靜態文件中有需要翻譯的字符串。它目前的工作方式如下：

• 每個可翻譯字符串都帶有特殊的函數_t（可在js模塊web.core中找到）
• 服務器使用這些字符串生成正確的PO文件。
• 每當加載Web客戶機時，它將調用route/web/web client/translations，它返回所有可翻譯術語的列表
• 在運行時，每當調用函數時，它都會在該列表中查找以查找轉換，如果找不到轉換，則返回它或原始字符串。

請注意，在文檔翻譯模塊中，從服務器的角度對翻譯進行了更詳細的解釋。
javascript中的翻譯有兩個重要功能：_t和_lt。區別在於_lt是以懶惰的方式進行的。

var core = require('web.core'); var _t = core._t; var _lt = core._lt; var SomeWidget = Widget.extend({ exampleString: _lt('this should be translated'), ... someMethod: function () { var str = _t('some text'); ... }, }); 

在本例中，由於在加載模塊時翻譯尚未准備就緒，因此必須使用_lt。
注意，翻譯功能需要注意。參數中給定的字符串不應是動態的。

會話Session

Web客戶端提供了一個特定的模塊，其中包含一些特定於用戶當前會話的信息。一些顯著的鍵是：

• uid:當前用戶的id（來自於表 res.users 的ID）
• user_name: 用戶的名字，字符串類型
• 用戶上下文（context [用戶id,語言和時區]）
• partner_id: 與當前用戶關聯的合作伙伴的ID
• db:當前使用的數據庫名字

添加信息到會話中

加載/web路由后，服務器將在模板中插入一些會話信息和腳本標記。信息將從模型ir.http的方法session_info中讀取。因此，如果要添加特定信息，可以通過重寫session_info方法並將其添加到字典中來完成。

from odoo import models from odoo.http import request class IrHttp(models.AbstractModel): _inherit = 'ir.http' def session_info(self): result = super(IrHttp, self).session_info() result['some_key'] = get_some_value_from_db() return result 

現在，通過在會話中讀取該值，可以在javascript中獲取該值：

var session = require('web.session'); var myValue = session.some_key; ... 

請注意，此機制旨在減少Web客戶端准備就緒所需的通信量。它更適合於計算成本較低的數據（緩慢的session_info調用將延遲為每個人加載Web客戶端），以及在初始化過程早期需要的數據。

視圖

“視圖”一詞有多種含義。本節是關於視圖的JavaScript代碼的設計，而不是Arch的結構或其他任何內容。
2017年，Odoo用新架構替換了先前的視圖代碼。主要需要將呈現邏輯與模型邏輯分開。
視圖（一般意義上）現在用4個部分描述：視圖、控制器、渲染器和模型。這4個部分的API在AbstractView、AbstractController、AbstractRenderer和AbstractModel類中進行了描述。

 

視圖結構.png

• 視圖是工廠。它的工作是獲取一組字段、arch、上下文和其他一些參數，然后構造一個控制器/渲染器/模型三元組。
  視圖的作用是用正確的信息正確地設置MVC模式的每一部分。通常，它必須處理arch字符串，並提取視圖中彼此所需的數據。
  請注意，視圖是一個類，而不是一個小部件。一旦它的工作完成，它就可以被丟棄。
• 渲染器有一個作業：表示在DOM元素中查看的數據。每個視圖都可以以不同的方式呈現數據。此外，它應該監聽適當的用戶操作，並在必要時通知其父級（Controller）。
  渲染器是MVC模式中的V.
• 模型：它的工作是獲取並保持視圖的狀態。通常，它以某種方式表示數據庫中的一組記錄。該模型是“業務數據”的所有者。它是MVC模式中的M.
• Controller：它的工作是協調渲染器和模型。此外，它是Web客戶端其余部分的主要入口點。例如，當用戶在搜索視圖中更改某些內容時，將使用適當的信息調用控制器的更新方法。
  它是MVC模式中的C.

視圖的JS代碼已設計為可在視圖管理器/操作管理器的上下文之外使用。它們可以用於客戶端操作，也可以顯示在公共網站上（對資源進行一些處理）

字段部件

該AbstractField類是在一個視圖中的所有控件的基類，用於支持他們所有的視圖（目前為：表格，列表，看板）。
v11字段小部件與先前版本之間存在許多差異。讓我們提一下最重要的一些：

• 小部件在所有視圖之間共享（表單/列表/看板）。無需再復制實現。請注意，可以為視圖設置特定版本的窗口小部件，方法是在視圖注冊表中為視圖名稱添加前綴：list.many2one將優先於many2one選擇。
• 小部件不再是字段值的所有者。它們僅表示數據並與視圖的其余部分進行通信。
• 小部件不再需要能夠在編輯和只讀模式之間切換。現在，當需要進行此類更改時，窗口小部件將被銷毀並再次重新呈現。這不是問題，因為他們無論如何都不擁有自己的價值
• 字段小部件可以在視圖之外使用。他們的API略顯笨拙，但它們的設計是獨立的。

裝飾與列表視圖一樣，字段小部件對裝飾具有簡單的支持。裝飾的目標是有一種簡單的方法來根據記錄當前狀態指定文本顏色。例如，

<field name = “state” decoration-danger = “amount＆lt; 10000” /> 

有效的裝飾名字有：

• decoration-bf
• decoration-it
• decoration-danger
• decoration-info
• decoration-muted
• decoration-primary
• decoration-success
• decoration-warning
  每個裝飾decoration-X將映射到css類text-X，這是一個標准的bootstrap css類（text-it和text-bf除外，它們由odoo處理並分別對應於斜體和粗體）。請注意，decoration屬性的值應該是一個有效的python表達式，它將使用記錄作為評估上下文進行評估。