widget::widget() 必须传合法 public 属性，拼错名就静默丢弃；需显式传给 render()；包裹内容须用 begin()/end()；配置禁用闭包/对象；每次调用均为新实例。
Widget::widget() 必须传合法 public 属性，拼错名就静默丢弃
Yii 小部件不是靠 new 实例化，而是统一走 Widget::widget() 静态工厂方法。它会自动调用 init() 和 run()，但前提是传入的配置键必须严格匹配目标 Widget 类声明的 public 属性名。
常见错误是把 'body' 写成 'content'（如对 yii\bootstrap4\Alert），或把 'view' 写成 'template' —— 这些都不会报错，值直接被忽略，渲染结果为空或用默认值。
-
Alert::widget(['body' => 'OK'])有效；['content' => 'OK']无效 -
MaskedInput::widget(['mask' => '999-99-9999'])有效；['format' => ...]无效 - 属性名区分大小写：
'clientOptions'≠'clientoptions'
控制器里调用 Widget::widget() 后，必须显式传给 render()，不能直接 return
很多人在控制器 action 里写了 Widget::widget([...]) 却发现页面没显示内容，根本原因是把它当成了响应对象或视图变量自动绑定 —— 它只是返回一段 HTML 字符串，不会自动输出，也不会进视图作用域。
错误写法：
Widget::widget(['class' => 'yii\bootstrap4\Alert', 'body' => 'Hi']);<br>
return $this->render('index');
这段代码中 Alert 的 HTML 被计算出来又丢弃了。
正确写法是把它作为数据变量传进去：
return $this->render('index', [<br>
'alertHtml' => Widget::widget([<br>
'class' => 'yii\bootstrap4\Alert',<br>
'body' => 'Hi'<br>
])<br>
]);
然后在
views/site/index.php 里用 = $alertHtml ?> 输出。需要包裹内容时，必须用 Widget::begin() / Widget::end() 配对
像 ActiveForm、ListView 这类需要嵌套 HTML 内容的小部件，不能用 widget() 单次调用 —— 它们依赖 begin() 输出起始标签（如 <form></form>），中间插入任意 PHP/HTML，再靠 end() 输出结束标签（如 ）。
典型结构：
<?php $form = ActiveForm::begin(['id' => 'login-form']); ?><br>= $form->field($model, 'username') ?><br>= Html::submitButton('Login') ?><br><?php ActiveForm::end(); ?>
-
begin()返回小部件实例，可用于链式调用（如$form->field()） -
end()必须显式调用，否则标签不闭合，页面结构错乱 - 不能混用：
ActiveForm::widget()不支持包裹内容，强行用会出错或无效果
自定义 Widget 里别在 $config 里传闭包或对象，序列化会失败
Widget 构造本质是两阶段：先用 $config 初始化 public 属性，再在 run() 中读取这些属性生成 HTML。但 $config 数组最终可能被序列化（比如缓存、日志、调试工具），而 Closure、PDO、Yii 组件等无法序列化。
错误示例：
MyWidget::widget([<br>
'onSuccess' => function ($event) { /* ... */ },<br>
'db' => Yii::$app->db<br>
])
运行时抛出
Serialization of 'Closure' is not allowed。安全做法：
- 回调逻辑移到
run()内部硬编码，或通过字符串事件名 + 绑定 handler 方式解耦 - 组件依赖用
Yii::$app->xxx在run()中按需获取，不要塞进配置 - 若真要传行为参数，只限基本类型：string、int、bool、array（且 array 里不能含对象或函数）
最容易被忽略的是生命周期边界：Widget 不是“注册后全局可用”的东西，每次 widget() 或 begin() 都是全新实例，init 和 run 严格按顺序触发，跨请求不共享状态 —— 别指望在 init 里 set 一个属性，下个请求还能用。
