structure-modules.md 8.47 KB
Newer Older
funson86 committed
1
模块
funson86 committed
2 3
=======

funson86 committed
4 5 6 7 8
模块是独立的软件单元,由[模型](structure-models.md), [视图](structure-views.md),
[控制器](structure-controllers.md)和其他支持组件组成,
终端用户可以访问在[应用主体](structure-applications.md)中已安装的模块的控制器,
模块被当成小应用主体来看待,和[应用主体](structure-applications.md)不同的是,
模块不能单独部署,必须属于某个应用主体。
funson86 committed
9 10


funson86 committed
11
## 创建模块 <a name="creating-modules"></a>
funson86 committed
12

funson86 committed
13 14 15
模块被组织成一个称为[[yii\base\Module::basePath|base path]]的目录,
在该目录中有子目录如`controllers`, `models`, `views` 分别为对应控制器,模型,视图和其他代码,和应用非常类似。
如下例子显示一个模型的目录结构:
funson86 committed
16 17 18

```
forum/
funson86 committed
19 20 21 22 23 24 25 26
    Module.php                   模块类文件
    controllers/                 包含控制器类文件
        DefaultController.php    default 控制器类文件
    models/                      包含模型类文件
    views/                       包含控制器视图文件和布局文件
        layouts/                 包含布局文件
        default/                 包含DefaultController控制器视图文件
            index.php            index视图文件
funson86 committed
27 28 29
```


funson86 committed
30
### 模块类 <a name="module-classes"></a>
funson86 committed
31

funson86 committed
32 33 34
每个模块都有一个继承[[yii\base\Module]]的模块类,该类文件直接放在模块的[[yii\base\Module::basePath|base path]]目录下,
并且能被 [自动加载](concept-autoloading.md)。当一个模块被访问,和 [application instances](structure-applications.md)
类似会创建该模块类唯一实例,模块实例用来帮模块内代码共享数据和组件。
funson86 committed
35

funson86 committed
36
以下示例一个模块类大致定义:
funson86 committed
37 38 39 40 41 42 43 44 45 46 47

```php
namespace app\modules\forum;

class Module extends \yii\base\Module
{
    public function init()
    {
        parent::init();

        $this->params['foo'] = 'bar';
funson86 committed
48
        // ...  其他初始化代码 ...
funson86 committed
49 50 51 52
    }
}
```

funson86 committed
53 54
如果 `init()` 方法包含很多初始化模块属性代码,
可将他们保存在[配置](concept-configurations.md) 并在`init()`中使用以下代码加载:
funson86 committed
55 56 57 58 59

```php
public function init()
{
    parent::init();
funson86 committed
60
    // 从config.php加载配置来初始化模块
funson86 committed
61 62 63 64
    \Yii::configure($this, require(__DIR__ . '/config.php'));
}
```

funson86 committed
65
`config.php`配置文件可能包含以下内容,类似[应用主体配置](structure-applications.md#application-configurations).
funson86 committed
66 67 68 69 70 71 72 73 74 75 76 77 78 79

```php
<?php
return [
    'components' => [
        // list of component configurations
    ],
    'params' => [
        // list of parameters
    ],
];
```


funson86 committed
80
### 模块中的控制器 <a name="controllers-in-modules"></a>
funson86 committed
81

funson86 committed
82 83 84
创建模块的控制器时,惯例是将控制器类放在模块类命名空间的`controllers`子命名空间中,
也意味着要将控制器类文件放在模块[[yii\base\Module::basePath|base path]]目录中的`controllers`子目录中。
例如,上小节中要在`forum`模块中创建`post`控制器,应像如下申明控制器类:
funson86 committed
85 86 87 88 89 90 91 92 93 94 95 96

```php
namespace app\modules\forum\controllers;

use yii\web\Controller;

class PostController extends Controller
{
    // ...
}
```

funson86 committed
97 98 99
可配置[[yii\base\Module::controllerNamespace]]属性来自定义控制器类的命名空间,
如果一些控制器不再该命名空间下,可配置[[yii\base\Module::controllerMap]]属性让它们能被访问,
这类似于 [应用主体配置](structure-applications.md#controller-map) 所做的。
funson86 committed
100 101


funson86 committed
102
### 模块中的视图 <a name="views-in-modules"></a>
funson86 committed
103

funson86 committed
104 105 106 107
视图应放在模块的[[yii\base\Module::basePath|base path]]对应目录下的 `views` 目录,
对于模块中控制器对应的视图文件应放在 `views/ControllerID` 目录下,
其中`ControllerID`对应 [控制器 ID](structure-controllers.md#routes). For example, if
例如,假定控制器类为`PostController`,目录对应模块[[yii\base\Module::basePath|base path]]目录下的 `views/post` 目录。
funson86 committed
108

funson86 committed
109 110 111
模块可指定 [布局](structure-views.md#layouts),它用在模块的控制器视图渲染。
布局文件默认放在 `views/layouts` 目录下,可配置[[yii\base\Module::layout]]属性指定布局名,
如果没有配置 `layout` 属性名,默认会使用应用的布局。
funson86 committed
112 113


funson86 committed
114
## 使用模块 <a name="using-modules"></a>
funson86 committed
115

funson86 committed
116 117
要在应用中使用模块,只需要将模块加入到应用主体配置的[[yii\base\Application::modules|modules]]属性的列表中,
如下代码的[应用主体配置](structure-applications.md#application-configurations) 使用 `forum` 模块:
funson86 committed
118 119 120 121 122 123

```php
[
    'modules' => [
        'forum' => [
            'class' => 'app\modules\forum\Module',
funson86 committed
124
            // ... 模块其他配置 ...
funson86 committed
125 126 127 128 129
        ],
    ],
]
```

funson86 committed
130 131
[[yii\base\Application::modules|modules]] 属性使用模块配置数组,每个数组键为*模块 ID*
它标识该应用中唯一的模块,数组的值为用来创建模块的 [配置](concept-configurations.md)
funson86 committed
132 133


funson86 committed
134
### 路由 <a name="routes"></a>
funson86 committed
135 136
### Routes <a name="routes"></a>

funson86 committed
137 138 139 140 141
和访问应用的控制器类似,[路由](structure-controllers.md#routes) 也用在模块中控制器的寻址,
模块中控制器的路由必须以模块ID开始,接下来为控制器ID和操作ID。
例如,假定应用使用一个名为 `forum` 模块,路由`forum/post/index` 代表模块中 `post` 控制器的 `index` 操作,
如果路由只包含模块ID,默认为 `default`[[yii\base\Module::defaultRoute]] 属性来决定使用哪个控制器/操作,
也就是说路由 `forum` 可能代表 `forum` 模块的 `default` 控制器。
funson86 committed
142 143


funson86 committed
144
### 访问模块 <a name="accessing-modules"></a>
funson86 committed
145

funson86 committed
146 147
在模块中,可能经常需要获取[模块类](#module-classes)的实例来访问模块ID,模块参数,模块组件等,
可以使用如下语句来获取:
funson86 committed
148 149 150 151 152

```php
$module = MyModuleClass::getInstance();
```

funson86 committed
153 154
其中 `MyModuleClass` 对应你想要的模块类,`getInstance()` 方法返回当前请求的模块类实例,
如果模块没有被请求,该方法会返回空,注意不需要手动创建一个模块类,因为手动创建的和Yii处理请求时自动创建的不同。
funson86 committed
155

funson86 committed
156 157
> 补充: 当开发模块时,你不能假定模块使用固定的ID,因为在应用或其他没模块中,模块可能会对应到任意的ID,
  为了获取模块ID,应使用上述代码获取模块实例,然后通过`$module->id`获取模块ID。
funson86 committed
158

funson86 committed
159
也可以使用如下方式访问模块实例:
funson86 committed
160 161

```php
funson86 committed
162
// 获取ID为 "forum" 的模块
funson86 committed
163 164
$module = \Yii::$app->getModule('forum');

funson86 committed
165
// 获取处理当前请求控制器所属的模块
funson86 committed
166 167 168
$module = \Yii::$app->controller->module;
```

funson86 committed
169
第一种方式仅在你知道模块ID的情况下有效,第二种方式在你知道处理请求的控制器下使用。
funson86 committed
170

funson86 committed
171
一旦获取到模块实例,可访问注册到模块的参数和组件,例如:
funson86 committed
172 173 174 175 176 177

```php
$maxPostCount = $module->params['maxPostCount'];
```


funson86 committed
178
### 引导启动模块 <a name="bootstrapping-modules"></a>
funson86 committed
179

funson86 committed
180 181
有些模块在每个请求下都有运行, [[yii\debug\Module|debug]] 模块就是这种,
为此将这种模块加入到应用主体的 [[yii\base\Application::bootstrap|bootstrap]] 属性中。
funson86 committed
182

funson86 committed
183
例如,如下示例的应用主体配置会确保`debug`模块每次都被加载:
funson86 committed
184 185 186 187 188 189 190 191 192 193 194 195 196 197

```php
[
    'bootstrap' => [
        'debug',
    ],

    'modules' => [
        'debug' => 'yii\debug\Module',
    ],
]
```


funson86 committed
198
## 模块嵌套 <a name="nested-modules"></a>
funson86 committed
199

funson86 committed
200 201
模块可无限级嵌套,也就是说,模块可以包含另一个包含模块的模块,我们称前者为*父模块*,后者为*子模块*
子模块必须在父模块的[[yii\base\Module::modules|modules]]属性中申明,例如:
funson86 committed
202 203 204 205 206 207 208 209 210 211 212 213

```php
namespace app\modules\forum;

class Module extends \yii\base\Module
{
    public function init()
    {
        parent::init();

        $this->modules = [
            'admin' => [
funson86 committed
214
                // 此处应考虑使用一个更短的命名空间
funson86 committed
215 216 217 218 219 220 221
                'class' => 'app\modules\forum\modules\admin\Module',
            ],
        ];
    }
}
```

funson86 committed
222 223
在嵌套模块中的控制器,它的路由应包含它所有祖先模块的ID,例如`forum/admin/dashboard/index` 代表
在模块`forum`中子模块`admin``dashboard`控制器的`index`操作。
funson86 committed
224 225


funson86 committed
226
## 最佳实践 <a name="best-practices"></a>
funson86 committed
227

funson86 committed
228 229
模块在大型项目中常备使用,这些项目的特性可分组,每个组包含一些强相关的特性,
每个特性组可以做成一个模块由特定的开发人员和开发组来开发和维护。
funson86 committed
230

funson86 committed
231 232
在特性组上,使用模块也是重用代码的好方式,一些常用特性,如用户管理,评论管理,可以开发成模块,
这样在相关项目中非常容易被重用。