# 后台组件
小部件是解决不同任务的独立功能块。窗口小部件始终具有用户界面和后端控制器（窗口小部件类），后端控制器准备窗口小部件数据并处理由窗口小部件用户界面生成的AJAX请求。
### [](https://octobercms.com/docs/backend/widgets#generic-widgets)通用小部件
小部件与前端[组件](https://octobercms.com/docs/cms/components)的后端等效。它们之所以相似，是因为它们是功能性的模块捆绑，提供零件并使用别名进行命名。关键区别在于后端窗口小部件使用YAML标记进行配置并将其自身绑定到后端页面。
**窗口小**部件类位于插件目录的**窗口小部件**目录内。目录名称与以小写形式编写的小部件类的名称匹配。小部件可以提供资产和零件。小部件目录结构示例如下所示：
~~~
widgets/
/form
/partials
_form.htm <=== Widget partial file
/assets
/js
form.js <=== Widget JavaScript file
/css
form.css <=== Widget StyleSheet file
Form.php <=== Widget class
~~~
### [](https://octobercms.com/docs/backend/widgets#generic-class-definition)类定义
通用窗口小部件类必须扩展`Backend\Classes\WidgetBase`该类。与其他任何插件类一样，通用窗口小部件控制器应属于[插件名称空间](https://octobercms.com/docs/plugin/registration#namespaces)。小部件控制器类定义示例：
~~~
<?php namespace Backend\Widgets;
use Backend\Classes\WidgetBase;
class Lists extends WidgetBase
{
/**
* @var string A unique alias to identify this widget.
*/
protected $defaultAlias = 'list';
// ...
}
~~~
小部件类必须包含**render（）**方法，用于通过渲染小部件部分来生成小部件标记。例：
~~~
public function render()
{
return $this->makePartial('list');
}
~~~
要将变量传递给局部变量，可以将其添加到`$vars`属性中。
~~~
public function render()
{
$this->vars['var'] = 'value';
return $this->makePartial('list');
}
~~~
或者，您可以将变量传递给makePartial（）方法的第二个参数：
~~~
public function render()
{
return $this->makePartial('list', ['var' => 'value']);
}
~~~
### [](https://octobercms.com/docs/backend/widgets#generic-ajax-handlers)AJAX处理程序
小部件与[后端控制器](https://octobercms.com/docs/backend/controllers-ajax#ajax)实现相同的AJAX方法。AJAX处理程序是窗口小部件类的公共方法，其名称以**on**前缀开头。小部件AJAX处理程序和后端控制器的AJAX处理程序之间的唯一区别是，`getEventHandler`当您在小部件部分中引用小部件AJAX处理程序时，应使用小部件的方法返回小部件的处理程序名称。
~~~
<a
href="javascript:;"
data-request="<?= $this->getEventHandler('onPaginate') ?>"
title="Next page">Next</a>
~~~
从窗口小部件类或部分类调用时，AJAX处理程序将自己定位。例如，如果窗口小部件使用**mywidget**的别名，**则将使用**作为处理程序的目标`mywidget::onName`。上面将输出以下属性值：
~~~
data-request="mywidget::onPaginate"
~~~
### [](https://octobercms.com/docs/backend/widgets#generic-binding)将小部件绑定到控制器
在开始在后端页面或部分页面中使用小部件之前，应将其绑定到[后端控制器](https://octobercms.com/docs/backend/controllers-ajax)。使用小部件的`bindToController`方法将其绑定到控制器。初始化小部件的最佳位置是控制器的构造函数。例：
~~~
public function __construct()
{
parent::__construct();
$myWidget = new MyWidgetClass($this);
$myWidget->alias = 'myWidget';
$myWidget->bindToController();
}
~~~
绑定小部件后，您可以在控制器的视图中访问它，也可以按其别名对其进行部分访问：
~~~
<?= $this->widget->myWidget->render() ?>
~~~
### [](https://octobercms.com/docs/backend/widgets#form-widgets)表单小部件
使用表单小部件，您可以将新的控件类型添加到后端[表单](https://octobercms.com/docs/backend/forms)。它们提供了为模型提供数据所共有的功能。表单窗口小部件必须在[插件注册文件中注册](https://octobercms.com/docs/plugin/registration#registration-methods)。
表单**窗口**小部件类位于插件目录的**formwidgets**目录中。目录名称与以小写形式编写的小部件类的名称匹配。小部件可以提供资产和零件。表单小部件目录结构示例如下：
~~~
formwidgets/
/form
/partials
_form.htm <=== Widget partial file
/assets
/js
form.js <=== Widget JavaScript file
/css
form.css <=== Widget StyleSheet file
Form.php <=== Widget class
~~~
### [](https://octobercms.com/docs/backend/widgets#form-class-definition)类定义
表单窗口小部件类必须扩展`Backend\Classes\FormWidgetBase`该类。与其他任何插件类一样，通用窗口小部件控制器应属于[插件名称空间](https://octobercms.com/docs/plugin/registration#namespaces)。可以在后端[表单字段定义](https://octobercms.com/docs/backend/forms#form-fields)文件中使用注册的窗口小部件。表单小部件类定义示例：
~~~
namespace Backend\Widgets;
use Backend\Classes\FormWidgetBase;
class CodeEditor extends FormWidgetBase
{
/**
* @var string A unique alias to identify this widget.
*/
protected $defaultAlias = 'codeeditor';
public function render() {}
}
~~~
### [](https://octobercms.com/docs/backend/widgets#form-widget-properties)表单小部件属性
表单小部件可能具有可以使用[表单字段配置](https://octobercms.com/docs/backend/forms#form-fields)设置的属性。只需在类上定义可配置属性，然后调用`fillFromConfig`方法以将其填充到`init`方法定义中。
~~~
class DatePicker extends FormWidgetBase
{
//
// Configurable properties
//
/**
* @var bool Display mode: datetime, date, time.
*/
public $mode = 'datetime';
/**
* @var string the minimum/earliest date that can be selected.
* eg: 2000-01-01
*/
public $minDate = null;
/**
* @var string the maximum/latest date that can be selected.
* eg: 2020-12-31
*/
public $maxDate = null;
//
// Object properties
//
/**
* {@inheritDoc}
*/
protected $defaultAlias = 'datepicker';
/**
* {@inheritDoc}
*/
public function init()
{
$this->fillFromConfig([
'mode',
'minDate',
'maxDate',
]);
}
// ...
}
~~~
然后，在使用窗口小部件时，可以从[表单字段定义中](https://octobercms.com/docs/backend/forms#form-fields)设置属性值。
~~~
born_at:
label: Date of Birth
type: datepicker
mode: date
minDate: 1984-04-12
maxDate: 2014-04-23
~~~
### [](https://octobercms.com/docs/backend/widgets#form-widget-registration)表单小部件注册
插件应该通过覆盖[Plugin注册类中](https://octobercms.com/docs/plugin/registration#registration-file)的`registerFormWidgets`方法来注册表单小部件。该方法返回一个数组，该数组包含键中的小部件类和小部件短代码作为值。例：[](https://octobercms.com/docs/plugin/registration#registration-file)
~~~
public function registerFormWidgets()
{
return [
'Backend\FormWidgets\CodeEditor' => 'codeeditor',
'Backend\FormWidgets\RichEditor' => 'richeditor'
];
}
~~~
短代码是可选的，可在引用“[表单”字段定义中](https://octobercms.com/docs/backend/forms#field-widget)的窗口小部件时使用，它应该是唯一值，以避免与其他表单字段发生冲突。
### [](https://octobercms.com/docs/backend/widgets#form-widget-load-data)加载表格数据
表单小部件的主要目的是与您的模型进行交互，这意味着在大多数情况下是通过数据库加载和保存值。呈现表单小部件时，它将使用`getLoadValue`方法请求其存储的值。的`getId`和`getFieldName`方法将返回一个唯一的标识符，并将其命名为形式中使用的HTML元素。这些值通常在渲染时传递给窗口小部件部分。
~~~
public function render()
{
$this->vars['id'] = $this->getId();
$this->vars['name'] = $this->getFieldName();
$this->vars['value'] = $this->getLoadValue();
return $this->makePartial('myformwidget');
}
~~~
在基本级别上，表单小部件可以使用输入元素将用户输入值发送回。从上面的示例中，可以在**myformwidget**部分内部使用准备好的变量来呈现元素。
~~~
<input id="<?= $id ?>" name="<?= $name ?>" value="<?= e($value) ?>" />
~~~
### [](https://octobercms.com/docs/backend/widgets#form-widget-save-data)保存表格数据
当需要输入用户输入并将其存储在数据库中时，表单小部件将在`getSaveValue`内部调用以请求该值。要修改此行为，只需覆盖表单窗口小部件类中的方法。
~~~
public function getSaveValue($value)
{
return $value;
}
~~~
在某些情况下，您有意不希望提供任何值，例如，表单小部件在不保存任何内容的情况下显示信息。返回`FormField::NO_SAVE_DATA`从`Backend\Classes\FormField`类派生的特殊常量，以忽略该值。
~~~
public function getSaveValue($value)
{
return \Backend\Classes\FormField::NO_SAVE_DATA;
}
~~~
### [](https://octobercms.com/docs/backend/widgets#report-widgets)报告小部件
报表小部件可以在后端仪表板和其他后端报表容器中使用。报表窗口小部件必须在[插件注册文件中注册](https://octobercms.com/docs/plugin/registration#widget-registration)。
> 您可以使用该`create:reportwidget`命令轻松地构建报表小部件。有关更多信息，请参见[脚手架命令](https://octobercms.com/docs/console/scaffolding#scaffold-create-reportwidget)。
### [](https://octobercms.com/docs/backend/widgets#report-class-definition)报告小部件类
报表小部件类应扩展`Backend\Classes\ReportWidgetBase`该类。与其他任何插件类一样，通用窗口小部件控制器应属于[插件名称空间](https://octobercms.com/docs/plugin/registration#namespaces)。该类应重写该`render`方法，以呈现窗口小部件本身。与所有后端窗口小部件类似，报表窗口小部件使用部分文档和特殊的目录布局。目录布局示例：
~~~
plugins/
rainlab/ <=== Author name
googleanalytics/ <=== Plugin name
reportwidgets/ <=== Report widgets directory
trafficsources <=== Widget files directory
partials
_widget.htm
TrafficSources.php <=== Widget class file
~~~
示例报告窗口小部件类定义：
~~~
namespace RainLab\GoogleAnalytics\ReportWidgets;
use Backend\Classes\ReportWidgetBase;
class TrafficSources extends ReportWidgetBase
{
public function render()
{
return $this->makePartial('widget');
}
}
~~~
小部件部分可以包含您要在小部件中显示的任何HTML标记。标记应与**report-widget**类一起包装在DIV元素中。使用H3元素输出小部件标题是可取的。示例小部件部分：
~~~
<div class="report-widget">
<h3>Traffic sources</h3>
<div
class="control-chart"
data-control="chart-pie"
data-size="200"
data-center-text="180">
<ul>
<li>Direct <span>1000</span></li>
<li>Social networks <span>800</span></li>
</ul>
</div>
</div>
~~~
在报表小部件内部，您可以使用任何[图表或指标](https://octobercms.com/docs/backend/controls)，列表或任何其他想要的标记。请记住，报告小部件扩展了通用后端小部件，并且您可以在报告小部件中使用任何小部件功能。下一个示例显示了列表报告窗口小部件标记。
~~~
<div class="report-widget">
<h3>Top pages</h3>
<div class="table-container">
<table class="table data" data-provides="rowlink">
<thead>
<tr>
<th><span>Page URL</span></th>
<th><span>Pageviews</span></th>
<th><span>% Pageviews</span></th>
</tr>
</thead>
<tbody>
<tr>
<td>/</td>
<td>90</td>
<td>
<div class="progress">
<div class="bar" style="90%"></div>
<a href="/">90%</a>
</div>
</td>
</tr>
<tr>
<td>/docs</td>
<td>10</td>
<td>
<div class="progress">
<div class="bar" style="10%"></div>
<a href="/docs">10%</a>
</div>
</td>
</tr>
</tbody>
</table>
</div>
</div>
~~~
### [](https://octobercms.com/docs/backend/widgets#report-properties)报表小部件属性
报表小部件可能具有用户可以通过Inspector管理的属性：
这些属性应`defineProperties`在小部件类的方法中定义。这些属性在[组件文章中](https://octobercms.com/docs/plugin/components#component-properties)进行了描述。例：
~~~
public function defineProperties()
{
return [
'title' => [
'title' => 'Widget title',
'default' => 'Top Pages',
'type' => 'string',
'validationPattern' => '^.+$',
'validationMessage' => 'The Widget Title is required.'
],
'days' => [
'title' => 'Number of days to display data for',
'default' => '7',
'type' => 'string',
'validationPattern' => '^[0-9]+$'
]
];
}
~~~
### [](https://octobercms.com/docs/backend/widgets#report-widget-registration)报告小部件注册
插件可以通过覆盖[插件注册类中](https://octobercms.com/docs/plugin/registration#registration-file)的`registerReportWidgets`方法来注册报告窗口小部件。该方法应返回一个数组，该数组包含键中的窗口小部件类以及值中的窗口小部件配置（标签，上下文和所需的权限）。例：[](https://octobercms.com/docs/plugin/registration#registration-file)
~~~
public function registerReportWidgets()
{
return [
'RainLab\GoogleAnalytics\ReportWidgets\TrafficOverview' => [
'label' => 'Google Analytics traffic overview',
'context' => 'dashboard',
'permissions' => [
'rainlab.googleanalytics.widgets.traffic_overview',
],
],
'RainLab\GoogleAnalytics\ReportWidgets\TrafficSources' => [
'label' => 'Google Analytics traffic sources',
'context' => 'dashboard',
'permissions' => [
'rainlab.googleanaltyics.widgets.traffic_sources',
],
]
];
}
~~~
该**标签**元素定义添加部件弹出的窗口小部件的名称。所述**上下文**元素定义其中可以使用的插件的上下文。October的报表小部件系统允许在任何页面上托管报表容器，并且容器上下文名称是唯一的。“仪表板”页面上的窗口小部件容器使用**仪表板**上下文。
- 基本说明
- 基本操作
- October cms 安装
- 后台控制器路径
- 图标
- 获取安装网上的插件/主题
- 插件构造器使用
- 定时任务
- October后台控制器
- vscode编辑器
- ajax操作
- 使用
- ajax更新组件
- ajax属性API
- JavaScript API
- ajax综合使用
- 主题
- 多语言主题
- 安装市场主题
- 主题程序处理
- 主题
- 页面
- 部件
- 布局
- 内容
- 组件
- 媒体
- 主题表单操作
- 表单使用
- 表单后端程序处理
- 插件
- 自定义插件
- 插件说明
- 插件导航条
- 插件数据库设置
- 插件的设置管理
- 插件的配置文件config
- 组件
- app服务
- app容器
- 扩展行为
- 缓存
- Collection类
- Lazy Collections
- Collection方法
- 助手函数
- 数组助手函数
- 路径助手函数
- 玄乐助手函数
- 其他助手函数
- 错误与记录
- 事件处理
- HTML页面
- 文件与目录操作
- 散列和加密
- 邮件
- 邮件内容
- 邮件发送
- 分页
- 模板解析器
- 动态解析器语法
- 队列消息
- 请求与输入
- 响应
- 视图
- 路由器
- 配置
- 验证操作
- 处理错误消息
- 错误消息与视图
- 可用的验证规则
- 有条件的验证规则
- 验证数组
- 错误消息
- 自定义验证规则
- 模型操作
- 定义模型与其属性
- 检索模型
- 插入与更新
- 删除模型
- 查询范围
- 事件操作
- 关联操作
- 定义关系
- 关系类型
- 多肽关系
- 关系查询
- 渴望加载
- 插入模型
- 数据库操作
- 基本用法
- 数据表结构
- 查询连贯操作
- 结果检索
- select子句
- 插入更新
- where子句
- 排序，分组，限制和偏移
- 文件附件
- Collection操作
- 属性操作
- 系列化json
- 数据库属性
- 数据库行为
- 控制器
- 后台控制器定义
- 后台页面
- 后台组件
- 后台表单
- 表单组件
- 表单视图
- 表单行为
- 后台列表
- 列表行为
- 列表过滤器
- 可用列类型
- 关系行为
- 关系行为类型
- 扩展关系行为
- 列表排序操作
- 导入导出操作
- 用于与权限
- corlate模板修改
- 修改顶部导航
- laravel问题
- 控制器不存在
- 控制器
- 路由组
- laravel笔记
- laravel 安装
- 伪静态配置
- 依赖注入 & 控制器
- 中间件
- 路由文件
- 视图