Yii2自定义Widget必须继承Widget类并重写init()和run()方法：init()校验参数、合并默认值、注册资源；run()返回HTML字符串；须用Widget::widget()调用，禁止new；view路径默认为@app/views/widget-name/；registerJs需唯一$key防重复。
如果您在Yii2项目中需要封装可复用的UI逻辑，例如动态菜单、表单控件或数据展示模块，则必须通过自定义小部件（Widget）实现。以下是创建与使用自定义小部件组件的具体方法：
一、继承Widget类并重写init()与run()方法
Yii2小部件的核心机制依赖于两个强制重写的方法：init()用于参数校验、默认值合并及资源注册；run()负责生成并返回最终渲染的HTML字符串。二者缺一不可，否则将触发Method not found错误或逻辑静默失效。
1、在@app/widgets/目录下新建PHP文件，如AlertWidget.php。
2、声明命名空间app\widgets，并use yii\base\Widget;。
3、定义public属性接收外部参数，例如public $title; public $type = 'info';。
4、在init()中调用parent::init()，使用ArrayHelper::merge()合并默认配置与传入参数。
5、在run()中调用$this->render('index', [...])或直接拼接并returnHTML字符串，禁止使用echo。
二、正确调用小部件而非new实例化
Yii2小部件生命周期由框架容器管理，手动new AlertWidget([...])会导致$this->view为空、$this->id未生成、JS注册失败等上下文缺失问题。
1、在视图文件中use app\widgets\AlertWidget;。
2、使用静态工厂方法调用：= AlertWidget::widget(['title' => '操作成功', 'type' => 'success']) ?>。
3、确保传参为关联数组，键名须与Widget类中声明的public属性名完全一致。
4、严禁在参数数组中传入匿名函数，否则触发Serialization of Closure is not allowed错误。
三、指定view路径避免视图文件定位失败
小部件内部调用$this->render('index')时，默认查找路径为@app/views/widgets/alertwidget/index.php（基于类名小写+连字符转换），而非当前控制器视图目录。路径错误将直接报View file not found。
1、在run()方法中显式指定完整路径：return $this->render(__DIR__ . '/views/index.php', [...]);。
2、若需跨模块复用，建议在Widget类顶部统一定义常量：const VIEW_PATH = __DIR__ . '/views';。
3、在render调用中使用：$this->render(self::VIEW_PATH . '/index.php', [...])。
4、多个同名Widget分散在不同命名空间时，必须严格区分use语句，否则可能加载旧版本导致样式/逻辑静默失效。
四、注册客户端资源防止JS/CSS重复注入
当小部件需引入JavaScript或CSS资源时，必须通过$this->view->registerJs()或registerCssFile()完成，并传入唯一$key参数，否则在页面多次调用该Widget时将重复注册资源，引发冲突或性能下降。
1、在init()或run()中获取当前view对象：$view = $this->getView();。
2、调用$view->registerJs("alert('loaded');", View::POS_READY, 'alert-widget-js');，其中'alert-widget-js'为唯一key。
3、CSS文件注册示例：$view->registerCssFile('@web/css/alert.css', [], 'alert-css');。
4、同一页面中多次调用相同Widget时，若未提供唯一key，第二次及之后的注册将被忽略，但首次注册的资源仍生效。
五、处理动态数据与模型交互
小部件可主动查询数据库或调用服务层获取数据，适用于导航菜单、用户信息栏等需实时内容的场景。此时需注意模型加载路径、命名空间引用及异常捕获。
1、在run()中使用ActiveRecord查询：$items = Nav::find()->where(['status' => 1])->all();。
2、确保已use app\models\Nav;或对应命名空间下的模型类。
3、将查询结果传递至视图：return $this->render('menu', ['items' => $items]);。
4、若模型查询失败且未加try-catch，整个页面渲染将中断并抛出异常。
