Field API

Wed, 05 Aug 2015 10:32:19 +0800

利用Field API可以把字段附加到Drupal实体中，并提供了对字段数据的存储、载入、编辑以及渲染支持。Field API能把包括Node、User在内的任何实体变得“字段化”，也就是说可以把字段附加在实体之上。其他模块可以提供基于用户界面，可以通过浏览器来管理各种数据类型的字段，Form元素以及显示兼容性等。

Field API定义了两个重要的数据结构：Field（字段）和Instance（字段实例），以及一个重要的概念：Bundle。字段定义了可以附加到实体智商的数据类型。字段实例是一个附加到一个Bundle上的字段。一个Bundle是一系列的用Field Attach API组织起来的字段集合，并且这一集合会被附加到一个字段化的实体之上。

例如，站点管理员希望文章类型的Node具有次标题和照片。利用Field API或者Field UI模块，管理员创建了一个类型为’text’的名称为’次标题’的字段，以及一个’image’类型的名为’照片’的字段。接下来在界面上建立两个字段实例，两个实例分别将次标题和照片字段附加到Node类型的文章Bundle上。当Node系统利用Field Attach API来载入一个文章的所有字段时，因为前面已经将副标题和照片两个字段同Node实体的Article Bunle进行了绑定，会将Node的实体类型（node），内容类型（article）作为Bundle作为参数，field_attach_load()会载入这两个字段。

##字段的定义以键值对数组的形式来表达。

array $field:

id(整形，只读)：字段的主键，由field_create_field()自动生成。
field_name(字符串，最大长度32)：字段的名称，每个字段名都是唯一的。当字段被附加到实体之后，会用$entity->$field_name的形式进行存储。
type(字符串)：：字段的类型，例如“文本”或者“图片”。字段类型是由定义字段的模块在hook_field_info中实现的。
entity_types(数组)：允许挂接该字段的Entity类型列表，如果没有指定，那么该字段可以附加到任何类型的实体上。
cardinality(整数)：字段中可以存储的值的数量。取值范围为任何正整数或FIELD_CARDINALITY_UNLIMITED。
translatable(整数)：该字段是否可翻译。
locked(整数)：该字段是否可以编辑，如果是TRUE，则用户无法设置该字段，也无法创建新实例。缺省为False。
module(字符串，只读)：实现该Field的模块名称。
active(整数，只读)：如果实现该字段的模块处于启用状态，则该值为真。
deleted(整数，只读)：是否被删除。被删除的字段会被Field Attach API忽略，这个属性的存在是因为字段一般只是被标记为删除，仅有在垃圾收集过程中才真正删除。
columns(数组，只读)：一个字段的值可能包含多个列，每个字段包含的列可能都不同。Field API中的列类似Schema API中的列，但这并不代表这两者一定是一一对应的，这要看字段的存储方法的具体实现。
indexes(数组)：数据列的索引数组，格式同Schema API的索引定义相同。只有出现在columns中的列才可以用在索引数组中。另外字段类型创建时可以定义缺省索引，并且在创建该字段类型的字段时，对索引进行修改或添加。
foreign keys(可选)：一个关系数组，同Schema的外键定义一致。这个成员的作用是非常优先的，因为你不能指定另外一个Field作为外键，只能指定数据表作为外键的关联目标。
settings(数组)：字段类型所属的一个键值对列表。每个字段类型的实现模块会定义实现自己的字段设置。
storage(数组)：一个键值对数组用于指定该字段的存储后端：
- *type(字符串)*：在hook_field_storage_info中定义的后端存储。
- *module(字符串，只读)*：实现后端存储的模块名称。
- *active(整数，只读)*：存储后端是否可用。
- *settings(数组)*：每个后端存储都有自己的配置键值对数组。

##字段实例的定义也是用键值对数组来实现的

array $instance:

id(整数：只读)：字段实例的主键，由field_create_instance()自动生成。
field_id(整数，只读)：指向这一实例的字段的外键，由field_create_instance()自动创建。
entity_type(字符串)：实例所绑定的Bundle的名称。
label(字符串)：当字段同一个Bundle进行绑定时的一个可读的标签，例如，一个字段实例可能成为一个Form API元素的标题。
description(字符串)：同Label类似，在实例被绑定到Form时候，可能以Help文本的形式出现。
required(整数)：字段实例被绑定到Bundle上的时候，是否是必填字段。目前为止，这一属性仅在同Form API协同工作时生效，对于field_attach_load, field_attach_insert以及field_attach_update是无效的。
default_value_function(字符串)：如果该名称指定的函数存在的话，会为该实例提供一个缺省值。
default_value(数组)：如果default_value_function不存在，可以在这里指定缺省值。
delted(整数，只读)：字段实例的删除标志。被标记删除的实例会被Field Attach API忽略。同字段的情况一样，字段实例的删除也只是做一个删除标记，随垃圾收集完成真正的删除。
settings(数组)：继承字段类型的设置值。
widget(数组)：用键值对数组的形式，为这一绑定到Bundle的实例指定Form API的输入插件。
- *type(字符串)*：插件类型，例如text_textfield。插件类型由相应模块的hook_field_widget_info()定义。
- *settings(数组)*：插件自身的设置，每个字段插件类型模块都会定义自己的设置。
- *weight(浮点数)*：该插件在编辑窗体中的权重。
- *module(字符串，只读)*：实现这一插件的模块名称。
dispaly(数组)：用键值对数组的形式，指定字段值在实体的各种非取胜视图模式下的展示方式。在每一种视图模式下，Field UI让管理员可以在新建字段的时候，定义是否只定义一个缺省的显示方式来减少管理工作。在新装站点的情况下，Node只有在’teaser’模式下又一个自定义显示，其他的所有视图都定义使用缺省方式显示。当用变成方式把一个字段实例添加到node的时候，至少为缺省和’teaser’两种模式指定显示方式：
- *default(字符串)*：用键值对数组来描述该字段在没有指定独立显示选项的情况下的显示方式。
  - *label(字符串)*：标签的显示方式，缺省的字段主题能支持的包括行内、上方、下方或是隐藏。
  - *type(字符串)*：显示格式器的类型，或者用’hidden’来隐藏。
  - *settings(数组)*：格式器的配置键值数组。
  - *weight(浮点数)*：在该视图下的字段显示权重。
  - *module(字符串，只读)*：实现该格式器的模块。
- *其他模式*：同default类似，用同样的格式类定义在“其他模式”的视图中的显示。这些选项只有在运行时使用非缺省模式的情况下才会生效。

字段实例的渲染数组在field_attach_view()文档中有描述。

Bundle取决于两个字符串，实体类型和bundle名称。

Field Types API：定义了字段类型，插件类型，以及显示格式器。字段模块利用这个API来把文本或Node引用这样的字段同显示格式器以及form元素关联起来。
Field CRUD API：对字段、字段实例和bundles进行增删改查，模块一般在hook_install()中使用这些API来创建自定义数据结构。
Field Attach API：把实体类型和字段API连接起来。这一组API为连接到实体上的字段数据提供载入、存储、生成From、显示和一些其他操作。Node之类的“字段化”的实体利用这些API使得自身能够被Field挂载。
Field Info API：向外提供所有字段、实例、插件的相关信息。
Field Storage API：为字段数据提供一个可插接的存储后端系统。缺省的实现是field_sql_storage.module，其中利用SQL数据库实现字段数据的存储。
Field API bulk data deletion：清理由field_delete_field()和field_delete_instance批量删除操作后的数据。
Field language API：为Field API提供多语言支持。

api | 伪架构师

Field API