121. 系统AJAX（四）：命令
在drupal AJAX api中，AJAX请求获取的数据均是以“命令”方式在页面中进行更新，命令由两部分核心内容组成：执行更新的JS函数、函数操作所需的数据（参数），实现命令概念需要前后端配合。
命令概述：
在前端：
一条命令就是一个对象，称为命令对象，是一个纯js数据对象，该对象必须存在属性：command，她的值是命令名，命令名是一个js函数的函数名，该函数称为命令函数，必须存在于以下前端全局变量中：
Drupal.AjaxCommands.prototype
如果不存在，那么命令是无效的，命令对象的其他属性属于命令携带的数据，根据命令不同而不同。
所有命令函数均按序接受三个参数：AJAX对象、命令对象、状态信息，AJAX结果动作由命令函数完成
在后端：
每一个AJAX命令由一个类表示，这些类均需要实现以下接口：
\Drupal\Core\Ajax\CommandInterface
该接口仅有一个render()方法，用于返回一个命令数组，该数组将被序列化成json字符串，传递到前端后就是前文所述的命令对象
同样的，命令也可以传递附属物（资源库、配置变量），这样的命令需要实现以下接口：
\Drupal\Core\Ajax\CommandWithAttachedAssetsInterface
在实现上可以直接使用以下特征：
\Drupal\Core\Ajax\CommandWithAttachedAssetsTrait
命令由以下AJAX响应对象传递到前端：
\Drupal\Core\Ajax\AjaxResponse
一次AJAX请求可以传递多个命令，通过该AJAX响应对象的以下方法添加：
public function addCommand(CommandInterface $command, $prepend = FALSE)
参数$command为命令对象，添加顺序就是前端执行命令的顺序，如果需要后添加但先执行，那么需要将参数$prepend设置为true
如果后端传递的命令，在前端不支持将是没有用的，接下来我们看一看系统默认提供了哪些命令。
插入命令insert：
命令名：insert，用于向页面插入html内容
在前端：
前端方法：Drupal.AjaxCommands.prototype.insert(ajax, response)
（前文已讲了所有js命令函数按序接收三个参数：AJAX对象、命令对象、状态信息，因此此处及下文不再解释命令函数的参数含义）
响应对象除包含command属性外（值为insert，下文所有命令均包含该属性，仅值不同，将不再赘述），还有以下属性：
selector：可选，执行插入操作的目标元素的jquery选择器，字符串值，含义等同AJAX配置中的wrapper项，但优先级更高
method：可选，插入所用的方法，含义等同AJAX配置中的method项，但优先级更高
effect：可选，插入或替换动画效果，含义等同AJAX配置中的effect项，但优先级更高
speed：可选，插入或替换动画速度，含义等同AJAX配置中的speed项，但优先级更高
data：必选，字符串值，通常是要插入的html片段，里面如包含JS，会被执行，当使用empty方法时该项被忽视，此时可以是空字符串
settings：可选，一个设置对象，当成功插入DOM后，用于对插入的各根元素执行Drupal.attachBehaviors，这允许其他组件为其添加js事件，当有元素移除时（插入是替换操作），用于Drupal.detachBehaviors方法；优先级最高，其次是AJAX配置中的settings项，最后是drupalSettings
在后端：
插入命令类：\Drupal\Core\Ajax\InsertCommand
使用示例：
$ajaxResponse = new \Drupal\Core\Ajax\AjaxResponse();
$html = ['#markup' => '示例'];
$command = new \Drupal\Core\Ajax\InsertCommand(NULL, $html);
$ajaxResponse->addCommand($command);
return $ajaxResponse;
该命令的构造函数接收三个参数：
$selector：执行插入操作的目标元素的jquery选择器，字符串值，见前文
$content：可以是一个渲染数组，或html字符串片段，当是渲染数组时附属物会自动处理
$settings：js设置数组，见前文的js设置对象
该命令无法直接指定插入方法，当客户端Ajax对象指定了方法时，这样很好，如需指定方法用以下类代替：
在外部前面追加插入：
\Drupal\Core\Ajax\BeforeCommand
在外面后面追加插入：
\Drupal\Core\Ajax\AfterCommand
在里面头部追加插入：
\Drupal\Core\Ajax\PrependCommand
在里面尾部追加插入：
\Drupal\Core\Ajax\AppendCommand
整个元素替换插入：
\Drupal\Core\Ajax\ReplaceCommand
替换全部子内容插入：
\Drupal\Core\Ajax\HtmlCommand
以上这些类全部继承插入类，实例化方法也一样，仅仅方法不同而已
移除命令remove：
命令名：remove，用于移除页面元素
在前端：
前端方法：Drupal.AjaxCommands.prototype.remove(ajax, response, status);
响应对象必须包含selector属性，字符串值，jquery选择器，指示要移除的元素，否则命令无效，可选的传递settings属性，用于移除时，对各元素执行Drupal.detachBehaviors方法
在后端：
命令类：\Drupal\Core\Ajax\RemoveCommand
构造函数仅接收一个字符串值的jquery选择器做参数
标记改变命令changed：
命令名：changed，用于标记一个元素被更改，而不是更改一个元素
在前端：
前端方法：Drupal.AjaxCommands.prototype.changed(ajax, response, status)
响应对象必须包含selector属性，字符串值，jquery选择器，指示哪个元素要被标记为已更改，否则命令无效，可选的传递asterisk属性，也是一个jquery选择器，应是selector所指元素的子元素，如果指定了将在该元素内追加一个星号标记
在后端：
命令类：\Drupal\Core\Ajax\ChangedCommand
构造函数接收两个参数：
$selector：必选，一个字符串值的jquery选择器
$asterisk：可选，一个字符串值的jquery选择器
警告弹框命令alert：
命令名：alert，用于通过alert方法弹出警告框
在前端：
前端方法：Drupal.AjaxCommands.prototype.alert(ajax, response, status);
响应对象包含两个属性，text弹框内容，title弹框标题（bug：该参数是无意义的）
在后端：
命令类：\Drupal\Core\Ajax\AlertCommand
构造函数仅接收一个字符串值参数做弹框内容
无障碍消息通知命令announce：
命令名：announce，用于向残障设备发送消息通知，详见前端Drupal.announce方法
在前端：
前端方法：Drupal.AjaxCommands.prototype.announce(ajax, response);
响应对象包含两个属性：
text：被通知的消息
priority：可选值，优先级
在后端：
命令类：\Drupal\Core\Ajax\AnnounceCommand
构造函数按序参数为：$text, $priority = NULL，该命令会加载核心库：core/drupal.announce
重定向页面命令redirect：
命令名：redirect，用于将页面跳转到指定的url地址
在前端：
前端方法：Drupal.AjaxCommands.prototype.redirect(ajax, response, status);
响应对象包含一个属性，url重定向地址，将赋值给window.location以实现重定向
在后端：
命令类：\Drupal\Core\Ajax\RedirectCommand
构造函数仅接收一个字符串值的url参数做重定向
CSS样式修改命令css：
命令名：css，用于执行jquery的css方法修改元素样式
在前端：
前端方法：Drupal.AjaxCommands.prototype.css(ajax, response, status);
响应对象包含两个属性：
selector：要运用样式的元素的选择器
argument：jquery的css方法的参数
在后端：
命令类：\Drupal\Core\Ajax\CssCommand
构造函数按序参数为：$selector, array $css = []
js配置命令settings：
命令名：settings，用于为其他命令设置配置对象或修改全局配置对象drupalSettings
在前端：
前端方法：Drupal.AjaxCommands.prototype.settings(ajax, response, status);
响应对象包含两个属性：
settings：一个配置对象
merge：布尔值，如果为true，那么将把settings配置对象深度递归合并到全局配置对象drupalSettings中，否则将把配置对象赋值给Ajax对象的settings属性，以供该Ajax对象上的其他命令使用，比如插入命令就用到了该配置对象（这使得在AJAX请求后可以设置新的AJAX行为）。
该命令还会将已经失效的AJAX配置从全局配置：drupalSettings.ajax中删除
在后端：
命令类：\Drupal\Core\Ajax\SettingsCommand
构造函数按序参数为：array $settings, $merge = FALSE，
数据设置命令data：
命令名：data，用于通过jquery的data方法为元素设置数据
在前端：
前端方法：Drupal.AjaxCommands.prototype.data(ajax, response, status);
响应对象包含三个属性：
selector：被附加数据的元素的jquery选择器
name：数据键名
value：数据键值
在后端：
命令类：\Drupal\Core\Ajax\DataCommand
构造函数按序参数为：$selector, $name, $value
jquery方法执行命令invoke：
命令名：invoke，用于在jquery对象上执行一个jquery方法
在前端：
前端方法：Drupal.AjaxCommands.prototype.invoke(ajax, response, status);
响应对象包含三个属性：
selector：选择器字符串，将在该选择器产生的jquery对象上执行jquery方法
method：任意有效的jquery方法
args：方法所需的参数，是一个数据对象，将通过“…”运算符展开后传递给方法
在后端：
命令类：\Drupal\Core\Ajax\InvokeCommand
构造函数按序参数为：$selector, $method, array $arguments = []
重构表命令restripe：
命令名：restripe，用于给表中的行重新设置奇偶数类名（odd、even）
在前端：
前端方法：Drupal.AjaxCommands.prototype.restripe(ajax, response, status);
响应对象包含一个属性：
selector：选择器字符串，将作用在该选择器指定的元素的子元素上
在后端：
命令类：\Drupal\Core\Ajax\RestripeCommand
构造函数仅接收一个字符串值的jquery选择器参数
更新表单id命令update_build_id：
命令名：update_build_id，用于更新表单id的值
在前端：
前端方法：Drupal.AjaxCommands.prototype.update_build_id(ajax, response, status);
响应对象包含两个属性：
old：旧表单id值
new：新表单id值
在后端：
命令类：\Drupal\Core\Ajax\UpdateBuildIdCommand
构造函数按序参数为：$old, $new
CSS文件或标签加载命令add_css：
命令名：add_css，用于加载一个css样式表文件或<style>标签到页面，这不同于“css”命令，后者仅修改一个样式属性
在前端：
前端方法：Drupal.AjaxCommands.prototype.add_css(ajax, response, status);
响应对象包含一个属性：
data：字符串值的html片段，可以是一个加载css文件的link标签，也可以是一个<style>标签，将通过prepend方法（里面、前面）追加到head标签中，预追加操作意味着添加的样式优先级是很低的，样式标签中的@import将得到处理
在后端：
命令类：\Drupal\Core\Ajax\AddCssCommand
构造函数仅接收一个字符串值的$styles参数，含义同data
自定义命令：
如果系统默认提供的命令不能满足需求，那么可以自定义，一个命令需要前后端配合执行，缺一不可，因此需要在前后端均进行扩展：
在前端：
向以下全局变量添加命令函数：
Drupal.AjaxCommands.prototype
函数名必须和命令名相同，由此也可看出命令名必须满足js函数名要求，接收以下参数：
AJAX对象、命令对象、状态信息
该函数在前端执行js动作，通过命令对象的属性获取后端传递的数据
在后端：
实现一个命令类，必须实现以下接口：
\Drupal\Core\Ajax\CommandInterface
类名随意，最佳实践是以命令名的驼峰命名法加“Command”做后缀，在方法render()中返回一个数组，其中必须存在键名：command，其对应的键值为命令名，可选的传递其他代表命令所需数据的数组元素（注意：这不是js命令函数的参数），在前端该数组键名将作为命令对象的属性名
如果命令有附属物需要处理，还应实现以下接口：
\Drupal\Core\Ajax\CommandWithAttachedAssetsInterface
此时可以使用以下特征：
\Drupal\Core\Ajax\CommandWithAttachedAssetsTrait
补充：
1、后端提供了基础命令类：\Drupal\Core\Ajax\BaseCommand，可以指定命令名和数据，有时会很有用
2、关于dialog、modal主内容渲染器、相关AJAX命令、前端实现将在专门的主题中讲解