Odoo ORM API（五）- Fields

Fields

Basic fields 基礎性字段

class openerp.fields.Field(string=None, **kwargs)
這些字段描述符也包含了對這個字段的定義，同時也對這條 record 的每個字段進行了一定的權限控制。下面的幾個屬性可以在定義字段時寫入：

-	Name	描述
Parameters:	string	在用戶界面顯示的label，如果沒有設置，則用首字母大寫的 field name
	help	在用戶界面，當鼠標移動在這個field上時，彈出一個提示框，內容爲help中填寫的內容
	readonly(bool)	這個字段是不是只讀的，默認爲 False
	required(bool)	這個字段是不是必填的，默認爲 False
	index(bool)	這個字段在數據表中是否設置索引，默認爲 False
	default	要麼設置爲靜態的值，要麼設置爲一個函數，這個函數接受一個recordset作爲參數，並返回一個值。 如： default=lambda self: self.env.user.name
	states	一個字典，key爲state字段中的各項值，value中可用的爲”readonly”, “required”, “invisible”。 注意： 使用這個字段，必需是這個model中設置了state 字段，這樣才能被客戶的正確的處理。這個的設置，通常是爲了在某個階段，才能讓用戶看到相應的信息 states={‘draft’:[(‘readonly’, False)], ‘sent’:[(‘readonly’: False)]}
	groups	以英文逗號分割的字符串，使這個字段只屬於對應的groups。 如： groups=”crm.group_sale_1,crm.group_sale_2”
	copy(bool)	當在客戶端複製某個record時，是否將這個字段的值複製過去。一般的field都是True, One2many 以及 computed field 和 related field 和 property field 都是 False
	oldname(string)	這個field之前的名字，用以ORM能找到對應的字段進行更新數據

Computed fields

用以設置某個字段的值是直接根據計算而來，而不是僅僅的從數據庫中讀取。下面給出了這類字段所需要設置的屬性，如果要定義一個computed field，只需要設置 compute 屬性即可。

–	Name	描述
Parameters:	compute	一個方法的名字，這個方法是用來計算這個field的值的
	inverse	一個方法的名字，用以在設置這個字段後，針對對應的字段設置他們的值。可選的
	search	一個方法的名字，定義針對這個字段的search行爲。 可選的
	store(bool)	這個字段是否存在數據庫中。設置compute之後，默認爲False
	compute_sudo(bool)	這個字段是否需要以admin的權限的來計算，用以越過access rights， 默認False

The methods given for compute, inverse and search are model methods. Their signature is shown in the following example:

upper = fields.Char(compute='_compute_upper',
                    inverse='_inverse_upper',
                    search='_search_upper')

@api.depends('name')
def _compute_upper(self):
    for rec in self:
        rec.upper = rec.name.upper() if rec.name else False

def _inverse_upper(self):
    for rec in self:
        rec.name = rec.upper.lower() if rec.upper else False

def _search_upper(self, operator, value):
    if operator == 'like':
        operator = 'ilike'
    return [('name', operator, value)]

這個 compute method 將被作用到這個model中的每一個record中。openerp.api.depends() 這個裝飾器必需作用與compute method上，用以指明這些依賴，以明確當那些依賴字段的值發生變化時，好重新計算這個field的值。重計算是自動的，並且確保了cache和database的一致性。注意：一個method可以作用於多個字段。只需要對這些計算字段的compute屬性設置相同的compute method name 即可，這樣這些方法只會針對這些字段被調用一次。
默認情況下，computed field不會存在數據庫中，他們計算是 on-the-fly。可以通過添加一個屬性 store=True 使得這個字段存在數據庫中。帶來的優勢就是可以針對這個字段進行 search，並且是在數據庫層就被search 完畢。劣勢是當這個字段必需重新計算是，將會update database
inverse method，如他的名字一樣，進行 compute method的逆運算。當你對 computed field設置某個值後，必需對這個computed field的 依賴字段進行某些改變，使得 compute method 對 依賴字段 計算之後，得到的值與你填入computed field的值相同。注意：如果沒有設置inverse method，那麼這個computed field是 readonly = True 的
search method 就是當有對這個field search時，hack掉基礎的search 行爲，並且返回一個新的domain，再進行search。必須是 field operator value

Related fields

related field的值就是一個 由關係型字段的field names 用 dot 鏈接的string，當然最後一個field name可能不是關心型的。如果 cp_name = fields.Char(related=”parent_id.company_id.name”)。這個related field的一些屬性將會自動的從 源 field 中直接複製: string, help, readonly, required(這個必須是所有的field name都是required，這個related field纔會被設置成required=True), groups, digits, size, translate, sanitize, selection, comodel_name, domain, context。
默認的，這個字段也不會存在數據庫中。但是可以通過添加store=True，使其存在數據庫中。就像computed field 一樣， related field 在他依賴的字段值發生變化時，他也會自動的重新計算。

Company-dependent fields

就是以前的 ‘property’ fields，這類字段的值是依賴於 company，也就是說，歸屬於不同公司的user對某一個record的field，得到的值是不同的。
company_dependent 這個field是否是company dependent （boolean）

Incremental definition

A field is defined as class attribute on a model class. 如果這個Modle是繼承的，也可以通過重新定義一個名字相同的field用以擴展源model的field的定義。在這中情況下，這個field的屬性將從源model的field的屬性複製，並且用你自己寫的新的屬性用來update。
例如：第二個class就是給僅僅給state 字段添加了一個 help

class First(models.Model):
    _name = 'foo'
    state = fields.Selection([...], required=True)

class Second(models.Model):
    _inherit = 'foo'
    state = fields.Selection(help="Blah blah blah")

class openerp.fields.Char(string=None, **kwargs)
Bases : openerp.fields._String
基礎的string field，可以設定長度限制，通常在客戶端用一行表示

–	Name	Description
Parameters:	size(int)	這個字段最大的size
	translate	使得這個field的值可以被翻譯，使用translate=True 來翻譯這個字段值，也可以給他設置成一個callable, transalte(callback, value)，翻譯values使用 callback(terms)依賴獲取這個value的翻譯

class openerp.fields.Boolean(string=None, **kwargs)
Bases: openerp.fields.Field

class openerp.fields.Integer(string=None, **kwargs)
Bases: openerp.fields.Field

class openerp.fields.Float(string=None, digits=None, **kwargs)
Bases: openerp.fields.Field
可以通過設置digits屬性來實現Float的精度
digits 一個tuple（total, decimal)，或者一個function 接收一個 database cursor作爲參數，並且返回一個 （total, decimal)

class openerp.fields.Text(string=None, **kwargs)
Bases : openerp.fields._String
和Char非常相似，但是沒有size屬性，通常是作爲多行顯示的 Text box.
translate 這個和 Char 是一樣的

class openerp.fields.Selection(selection=None, string=None, **kwargs)
Bases: openerp.fields.Field

–	Name	Description
Parameters:	selection	制定這個字段的可能的值，它要麼設置成 多個（value, string)組成的一個列表， 要麼是一個 model method, 或者 model name。
	selection_add	如果這個字段是 extended的話，可以通過設置這個屬性，給源字段添加一些選項。必需是list of pairs(values, string)

selection 屬性是必需設置的，除非是這個字段是related field 或者是 field extensions。

class openerp.fields.Html(string=None, **kwargs)
Bases : openerp.fields._String

class openerp.fields.Date(string=None, **kwargs)
Bases : openerp.fields.Field

• static context_today(record, timestap=None)
  返回客戶端的timezone對應的時間，通常用來計算默認值 。timestap(datetime) 可選的，用以替代當前的時間，必需是datetime，date不行，這個方法返回 一個 string

• static from_string(value)
  將一個 ORM value 返回成 date value

• static to_string(value)
  將一個date value 轉換成一個 符合ORM要求的format 之後的string

• statci today(*args)
  返回符合ORM 要求的format的當前的日期，通常用來計算默認值

class openerp.fields.Datetime(string=None, **kwargs)
Bases : openerp.fields.Field

• static context_timestamp(record, timestamp)
  將給出的timestamp轉換成客戶端的對應timezone的時間，這個方法不是用來設置 _defaults initializer，因爲datetime field是在客戶端顯示時自動修改的。如果要設置默認值，請使用fields.datetime.now()。

–	Name
Parameters:	timestamp(datetime)，普通的UTC datetime, 用以將其轉換成客戶端timezone的datetime
Return type	datetime
Returns	一個被客戶端timezone轉換之後的datetime

• static from_string(value)
  將一個ORM value轉換成 datetime

• static now(*args)
  返回符合ORM 要求的format的當前的時間，通常用來計算默認值

• static to_string(value)
  將一個datetime轉換成符合ORM要求的 format之後的 string value。

Relational fields 關係型字段

class openerp.fields.Many2one(comodel_name=None, string=None, **kwargs)
Bases: openerp.fields._Relational
這個字段的值是一個 size 0 或者 1的 recordset

–	Name	Description
Parameters:	comodel_name (string)	目標model的name
	domain(domain or string)	可選，用以在客戶端供用戶選擇時，先進行一定的篩選
	context(dict)	可選，用以在客戶端處理這個字段時，設置他的context
	ondelete	設置當引用的record被刪除是，如果對本record進行的行爲，可填：set null, restrict, cascade
	auto_join	whether JOINs are generated upon search through that field (boolean, by default False)
	delegate	set it to True to make fields of the target model accessible from the current model (corresponds to _inherits)

comodel_name 是必需設置的，除了這個field 是 related field or field extendsions

class openerp.fields.One2many(comodel_name=None, inverse_name=None, string=None, **kwargs)
Bases: openerp.fields._RelationalMulti
One2many field; 這個字段的值是一個recordset，all the records in comodel_name such that the field inverse_name is equal to the current record.

–	Name	Description
Parameters:	comodel_name (string)	目標model的name
	inverse_name	對應target model(B model)的 Many2one的field的名字，這個field的 comodel_name必需是A model
	domain	同Many2one
	context	同上
	auto_join	同上
	limit	optional limit to use upon read (integer)

comodel_name 和 inverse_name 是必需設置的，除了這個field 是 related field or field extendsions

class openerp.fields.Many2many(comodel_name=None, relation=None, column1=None, column2=None, string=None, **kwargs)
Bases: openerp.fields._RelationalMulti
Many2many field; 這個field的值是一個recordset

–	Name	Description
Parameters:	comodel_name (string)	目標model的name
	relation(string)	可選，儲存兩者關係的表的名字
	column1(string)	optional name of the column referring to “these” records in the table relation
	column2(string)	optional name of the column referring to “those” records in the table relation
	domain(domain or string)	和其他兩種relation field一樣
	context(dict)	同上
	limit(int)	同上

comodel_name 是必需設置的，除了這個field 是 related field or field extendsions
relations column1 column2 是可選的，如果沒提供，那麼Odoo將會自動的根據對應的兩個model自動生成。

class openerp.fields.Referece(selection=None, string=None, **kwargs)
Bases: openerp.fields.Selection