从0开始创建一个Odoo插件模块

Alan

7 年前

这是Odoo系列文章的第四篇，完整目录请见最好用的免费ERP系统Odoo 11开发指南

插件(addon)和插件模块（addon module）用于指代可在Odoo中安装的Python包，在用户端显示为应用app或模块module。

本文中我们将通过创建一个名为my_module的插件来认识插件创建的全过程：

我们依然使用10分钟带你搭建史上最强的ERP系统-Odoo最新版中所创建的环境，即在~/odoo-dev下进行操作

mkdir local-addons/my_module #插件的命令规则同样为字母开头，可包含字母、数字和下划线
# 创建Python模块用于引用识别的__init__.py
touch local-addons/my_module/__init__.py
# 创建Odoo所需的__manifest__.py文件
vi local-addons/my_module/__manifest__.py
# 同时加入内容
{'name': 'My module'}

mkdir local-addons/my_module #插件的命令规则同样为字母开头，可包含字母、数字和下划线

# 创建Python模块用于引用识别的__init__.py

touch local-addons/my_module/__init__.py

# 创建Odoo所需的__manifest__.py文件

vi local-addons/my_module/__manifest__.py

# 同时加入内容

{'name': 'My module'}

打开开发者模式，并更新插件列表，此时在Apps中便可搜索到我们刚刚新建的my_module：

注：在my_module目录下添加static/description/icon.png则可显示图标，如上图中的循环箭头

__manifest__.py中的常见配置项

{
    'name': "Title", # 插件的标题
    'summary': "Short subtitle phrase", # 副标题
    'description': """Long description""", # 以RST格式书写的长描述，通常置于三引号中
    'author': "Your name", # 作者，多个作者时以逗号间隔
    'license': "AGPL-3", # 证书，常用用AGPL-3，其它选项：LGPL-3或其它OSI证书 
    'website': "http://www.example.com", # 获取插件更多详情的网址
    'category': 'Uncategorized', # 分类（可自定议），详见http://tinyurl.com/yd6on5tj
    'version': '11.0.1.0.0', # 版本号，如未包含Odoo目标版本号（此处为11.0），将会强制添加，这主要是因为Odoo版本间的大变化带来的不兼容
    'depends': ['base'], # 所依赖的模块列表，如无，则至少会依赖base
    'data': ['views.xml'],# 安装或升级模块时使用的数据，相对路径为插件为根目录，通常为xml或csv文件
    'demo': ['demo.xml'], # 数据库中启用了Demo data时将会从相对插件根目的该路径中添加demo数据
}

{

'name': "Title", # 插件的标题

'summary': "Short subtitle phrase", # 副标题

'description': """Long description""", # 以RST格式书写的长描述，通常置于三引号中

'author': "Your name", # 作者，多个作者时以逗号间隔

'license': "AGPL-3", # 证书，常用用AGPL-3，其它选项：LGPL-3或其它OSI证书

'website': "http://www.example.com", # 获取插件更多详情的网址

'category': 'Uncategorized', # 分类（可自定议），详见http://tinyurl.com/yd6on5tj

'version': '11.0.1.0.0', # 版本号，如未包含Odoo目标版本号（此处为11.0），将会强制添加，这主要是因为Odoo版本间的大变化带来的不兼容

'depends': ['base'], # 所依赖的模块列表，如无，则至少会依赖base

'data': ['views.xml'],# 安装或升级模块时使用的数据，相对路径为插件为根目录，通常为xml或csv文件

'demo': ['demo.xml'], # 数据库中启用了Demo data时将会从相对插件根目的该路径中添加demo数据

}

除了可使用长描述外，还能使用README文件来进行描述，扩展名可以为.txt, .rst或.md，另外还可以在插件根目录下添加description/index.html，一旦添加了HTML文件，其它描述文件将会被覆盖。

__manifest__.py中除了以上列出的之外，还有一些常用的键名：

application: 若值为True，则模块将以应用的方式显示

auto_install: 若值为True，则表示这是一个“胶水”(glue)模块，在它的依赖都安装后会自动安装

installable: 默认值为True，表示模块允许被安装

插件的基本结构

cd local-addons/my_module/
mkdir models
touch models/__init__.py
mkdir controllers
touch controllers/__init__.py
mkdir views security data demo i18n
mkdir -p static/description
# 在插件根目录下的__init__.py文件中载入文件
from . import models
from . import controllers

cd local-addons/my_module/

mkdir models

touch models/__init__.py

mkdir controllers

touch controllers/__init__.py

mkdir views security data demo i18n

mkdir -p static/description

# 在插件根目录下的__init__.py文件中载入文件

from . import models

from . import controllers

插件中的主要目录：

models/包含后端代码文件，创建模型及其业务逻辑。推荐一个Model使用一个文件，并且与model同名，library.book这一model使用library_book.py，第五章将详细介绍应用模型

views/包含用户端用到的XML文件，如actions, forms, lists等等。同样推荐一个模型一个文件，网站模板通常添加_template后缀，第十章会介绍后台视图，十六章讲解CMS网站开发

data/包含模块初始数据及其它数据，在第七章中将会介绍模块数据

demo/包含带有演示数据的数据文件，可用于测试、培训或模块评估

i18n/是Odoo查找.pot和.po翻译文件的地方，这些文件无需在__manifest__.py中进行声明，第十二章会介绍多语言相关内容

security/包含定义访问权限列表的数据文件，通常是一个ir.model.access.csv文件，也可能是一个定义访问组或行级安全记录规则的XML文件，在第11章中将会详细介绍访问权限控制

controllers/包含网站控制器及提供同等功能的模块的代码文件，第十四章将会介绍Web服务器开发的内容

static/是放置网页文件的地方，和前述不同，这个目录不是一种惯例，而是仅有其下的文件才能在Odoo网页中使用。同样无需在__manifest__.py中指定，但需要在网页模板中进行引用，第十六章将会介绍CMS网站开发的内容

注意：在向插件中新增文件时，数据文件需在__manifest__.py中声明，代码文件需在__init__.py中声明，否则将不会被载入

下面以一个简单的图书案例来学习具体内容的填充（操作路径~/odoo-dev/local-addons/my_module）

# 1.添加library_book.py
vi models/library_book.py

from odoo import models, fields
class LibraryBook(models.Model):
	_name = 'library.book'
	name = fields.Char('Title', required=True)
	date_release = fields.Date('Release Date')
	author_ids = fields.Many2many(
		'res.partner',
		string='Authors'
	)

# 2. 添加model的初始化文件
vi models/__init__.py
from . import library_book
# 3.编辑插件初始化文件
vi __init__.py
from . import models

# 1.添加library_book.py

vi models/library_book.py

from odoo import models, fields

class LibraryBook(models.Model):

_name = 'library.book'

name = fields.Char('Title', required=True)

date_release = fields.Date('Release Date')

author_ids = fields.Many2many(

'res.partner',

string='Authors'

)

# 2. 添加model的初始化文件

vi models/__init__.py

from . import library_book

# 3.编辑插件初始化文件

vi __init__.py

from . import models

本例中未包含业务逻辑，在第六章中将进行深入的探讨，安装后可以在Settings（开发者模式）下找到相应的记录

添加菜单和视图

# 1.创建XML文件，习惯上和model名称相同
vi views/library_book.xml
<?xml version="1.0" encoding="utf-8"?>
<odoo>
  <!-- 此处添加下面的action和menu配置 -->
</odoo>
# 2.在插件根目录的__manifest__.py中添加
'data': ['views/library_book.xml'],
# 3.添加views/library_book.xml中添加打开视图的action
#  数据记录通常使用<record>标签，这里的act_window是用于创建ir.actions.act_window的快捷方式，该模型用于存储视窗动作(Window Actions),name属性为对用户显示的名称（在Settings>Actions>Actions中查看，res_model中定义的是目标模型）
<act_window
  	id="library_book_action"
  	name="Library Books"
  	res_model="library.book" />
# 4.在<odoo>标签中添加菜单文件
# 菜单项存储在ir.ui.menu模型中，类似地<menuitem>是它的快捷方式，其中name属性为用户端显示的文字，action属性是执行的action的标识，使用第3步中创建时定义的id，sequence属性用于定义同级菜单的显示顺序，parent属性顾名思义用于定义父级菜单，本例中没有父级菜单，以顶级菜单形式展示
<menuitem
        id="library_book_menu"
        name="Library"
        action="library_book_action"
        parent=""
        sequence="5" />

# 1.创建XML文件，习惯上和model名称相同

vi views/library_book.xml

<?xml version="1.0" encoding="utf-8"?>

<odoo>

</odoo>

# 2.在插件根目录的__manifest__.py中添加

'data': ['views/library_book.xml'],

# 3.添加views/library_book.xml中添加打开视图的action

# 数据记录通常使用<record>标签，这里的act_window是用于创建ir.actions.act_window的快捷方式，该模型用于存储视窗动作(Window Actions),name属性为对用户显示的名称（在Settings>Actions>Actions中查看，res_model中定义的是目标模型）

<act_window

id="library_book_action"

name="Library Books"

res_model="library.book" />

# 4.在<odoo>标签中添加菜单文件

# 菜单项存储在ir.ui.menu模型中，类似地<menuitem>是它的快捷方式，其中name属性为用户端显示的文字，action属性是执行的action的标识，使用第3步中创建时定义的id，sequence属性用于定义同级菜单的显示顺序，parent属性顾名思义用于定义父级菜单，本例中没有父级菜单，以顶级菜单形式展示

<menuitem

id="library_book_menu"

name="Library"

action="library_book_action"

parent=""

sequence="5" />

此时更新该插件时菜单栏中就会出现Library

# 视图都是建立在ir.ui.view模型上的记录，其中name属性用于定义视图中显示的标题，通常会在这里看到XML ID值在这里重复出现，但我们也可以定义可读性更强的标题，如未定义name属性，Odoo会根据模型名和视图类型生成一个名称；model属性定义目标模型，使用目标模型中的_name值；arch属性定义视图的结构，不同的视图在这里产生差别
# 5.在library_book.xml中添加自定义表单视图
<record id="library_book_view_form" model="ir.ui.view">
	<field name="name">Library Book Form</field>
	<field name="model">library.book</field>
	<field name="arch" type="xml">
        <form>
          	<group>
	            <field name="name"/>
	            <field name="author_ids" widget="many2many_tags"/>
	          </group>
	          <group>
     			<field name="date_release"/>
   			</group>
 		</form>
	</field>
</record>
# 6.在library_book.xml中添加自定义树形/列表视图
<record id="library_book_view_tree" model="ir.ui.view">
	<field name="name">Library Book List</field>
	<field name="model">library.book</field>
	<field name="arch" type="xml">
		 <tree>
			   <field name="name"/>
			   <field name="date_release"/>
		 </tree>
	</field>
</record>
# 7.在library_book.xml中添加自定义搜索选项
<record id="library_book_view_search" model="ir.ui.view">
	<field name="name">Library Book Search</field>
	<field name="model">library.book</field>
	<field name="arch" type="xml">
		 <search>
			   <field name="name" />
			   <field name="author_ids" />
			   <filter string="No Authors" domain="[('author_ids','=',False)]" />
		 </search>
	</field>
</record>

# 视图都是建立在ir.ui.view模型上的记录，其中name属性用于定义视图中显示的标题，通常会在这里看到XML ID值在这里重复出现，但我们也可以定义可读性更强的标题，如未定义name属性，Odoo会根据模型名和视图类型生成一个名称；model属性定义目标模型，使用目标模型中的_name值；arch属性定义视图的结构，不同的视图在这里产生差别

# 5.在library_book.xml中添加自定义表单视图

<field name="name">Library Book Form</field>

<field name="model">library.book</field>

<form>

<group>

</group>

<group>

</group>

</form>

</field>

</record>

# 6.在library_book.xml中添加自定义树形/列表视图

<field name="name">Library Book List</field>

<field name="model">library.book</field>

<tree>

</tree>

</field>

</record>

# 7.在library_book.xml中添加自定义搜索选项

<field name="name">Library Book Search</field>

<field name="model">library.book</field>

</search>

</field>

</record>

Form视图通过<form>定义，画布是一个两列网格，其中的<group>用于垂直方向，两个group会有两列带有<field>定义的字段，字段采用数据类型默认的显示，也可以使用widget属性来进行具体指定。

Tree视图通过<tree>标签内部加上<field>来进行列的显示。

Search视图用于扩展右上角搜索选项框，在顶级的<search>标签中可包含<field>和<filter>，field增加可用于搜索的字段，filter增加预设的过滤条件。

权限控制

在新建数据模型时，需要指定谁能进行增删改查的操作，在创建新的应用时，则可定义用户组。

我们继续使用my_module来进行学习，权限控制的效果为：所有人均可阅读图书记录，新建一个Librarian组来进行增删改查的操作。

# 1.创建security/groups.xml
vi security/groups.xml
# 创建一个 Librarians 组
<?xml version="1.0" encoding="utf-8"?>
<odoo>
  	<record id="group_librarian" model="res.groups">
    	<field name="name">Librarians</field>
  	</record>
</odoo>
# 2.创建security/ir.model.access.csv
vi security/ir.model.access.csv
# 默认所有用户可读，Librarians 组成员可进行增删改查操作
id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink
acl_book,library.book default,model_library_book,,1,0,0,0
acl_book_librarian,library.book_librarian,model_library_book,group_librarian,1,1,1,1
# 3.创建__manifest__.py
vi __manifest__.py
'data': [
        'views/library_book.xml',
        'security/groups.xml',
        'security/ir.model.access.csv',
],
# 注意：创建权限组的文件要在创建权限的文件前加载

# 1.创建security/groups.xml

vi security/groups.xml

# 创建一个 Librarians 组

<?xml version="1.0" encoding="utf-8"?>

<odoo>

<field name="name">Librarians</field>

</record>

</odoo>

# 2.创建security/ir.model.access.csv

vi security/ir.model.access.csv

# 默认所有用户可读，Librarians 组成员可进行增删改查操作

id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink

acl_book,library.book default,model_library_book,,1,0,0,0

acl_book_librarian,library.book_librarian,model_library_book,group_librarian,1,1,1,1

# 3.创建__manifest__.py

vi __manifest__.py

'data': [

'views/library_book.xml',

'security/groups.xml',

'security/ir.model.access.csv',

# 注意：创建权限组的文件要在创建权限的文件前加载

可通过Settings > Users & Companies > Groups查看所创建组

通过Settings > Users & Companies > Users 打开任意用户即可通过编辑勾选为该用户赋予 Librarians 的权限：

使用脚手架快速创建插件结构

基本目录结构见本文插件的基本结构部分

cd local-addons/
~/odoo-dev/odoo/odoo-bin scaffold my_scaffolded
# 默认新模块的创建位置为当前路径，如若不在插件目录中，也可使用：
~/odoo-dev/odoo/odoo-bin scaffold my_scaffolded ~/odoo-dev/local-addons
# 脚手架默认使用的路径为~/odoo-devodoo/odoo/cli/templates/下的default模板，我们还可以通过-t来指定模板  
~/odoo-dev/odoo/odoo-bin scaffold -t path/to/template my_module

cd local-addons/

~/odoo-dev/odoo/odoo-bin scaffold my_scaffolded

# 默认新模块的创建位置为当前路径，如若不在插件目录中，也可使用：

~/odoo-dev/odoo/odoo-bin scaffold my_scaffolded ~/odoo-dev/local-addons

# 脚手架默认使用的路径为~/odoo-devodoo/odoo/cli/templates/下的default模板，我们还可以通过-t来指定模板

~/odoo-dev/odoo/odoo-bin scaffold -t path/to/template my_module

本节参考代码