README

Yii 视图渲染器

该包是 Yii View 渲染库的扩展。它添加了WEB特定的功能，并与 PSR-7 接口兼容。

要求

• PHP 8.0 或更高版本。

安装

可以使用 Composer 安装此包。

composer require yiisoft/yii-view-renderer

一般用法

渲染视图有两种方式

• 返回一个具有延迟渲染的 Yiisoft\DataResponse\DataResponse 类的实例。
• 立即渲染并返回渲染结果字符串。

将渲染结果作为 PSR-7 响应

Yiisoft\DataResponse\DataResponse 类是 Psr\Http\Message\ResponseInterface 的实现。有关此类的更多信息，请参阅 yiisoft/data-response 包。以下是如何获取具有延迟渲染的响应实例的方法

/**
 * @var \Yiisoft\Aliases\Aliases $aliases
 * @var \Yiisoft\DataResponse\DataResponseFactoryInterface $dataResponseFactory
 * @var \Yiisoft\View\WebView $webView
 */

$viewRenderer = new \Yiisoft\Yii\View\Renderer\ViewRenderer(
    $dataResponseFactory,
    $aliases,
    $webView,
    '/path/to/views', // Full path to the directory of view templates or its alias.
    'layouts/main.php', // Default is null, which means not to use a layout.
);

// Rendering a view with a layout.
$response = $viewRenderer->render('site/page', [
    'parameter-name' => 'parameter-value',
]);

当调用 Yiisoft\DataResponse\DataResponse 的 getBody() 或 getData() 方法时，将直接执行渲染。如果已设置布局，但您需要渲染不带布局的视图，则可以使用不可变设置器 withLayout()

$viewRenderer = $viewRenderer->withLayout(null);

// Rendering a view without a layout.
$response = $viewRenderer->render('site/page', [
    'parameter-name' => 'parameter-value',
]);

或使用 renderPartial() 方法，它将调用 withLayout(null)

// Rendering a view without a layout.
$response = $viewRenderer->renderPartial('site/page', [
    'parameter-name' => 'parameter-value',
]);

将渲染结果作为字符串

要立即渲染并返回渲染结果字符串，请使用 renderAsString() 和 renderPartialAsString() 方法

// Rendering a view with a layout.
$result = $viewRenderer->renderAsString('site/page', [
    'parameter-name' => 'parameter-value',
]);

// Rendering a view without a layout.
$result = $viewRenderer->renderPartialAsString('site/page', [
    'parameter-name' => 'parameter-value',
]);

更改视图模板路径

您可以在运行时按以下方式更改视图模板路径

$viewRenderer = $viewRenderer->withViewPath('/new/path/to/views');

您可以指定视图目录的完整路径或其别名。有关路径别名的更多信息，请参阅 yiisoft/aliases 包的说明。

在控制器中使用

如果在控制器中使用视图渲染器，您可以使用 withControllerName() 显式指定控制器名称，或将控制器实例传递给 withController() 以自动确定名称。在这种情况下，名称的确定方式如下

App\Controller\FooBar\BazController -> foo-bar/baz
App\Controllers\FooBar\BazController -> foo-bar/baz
App\AllControllers\MyController\FooBar\BazController -> foo-bar/baz
App\AllControllers\MyController\BazController -> baz
Path\To\File\BlogController -> blog

使用这种方法，每次渲染视图模板时不需要指定目录名称

use Psr\Http\Message\ResponseInterface;
use Yiisoft\Yii\View\Renderer\ViewRenderer;

class SiteController
{
    private ViewRenderer $viewRenderer;

    public function __construct(ViewRenderer $viewRenderer)
    {
        // Specify the name of the controller:
        $this->viewRenderer = $viewRenderer->withControllerName('site');
        // or specify an instance of the controller:
        //$this->viewRenderer = $viewRenderer->withController($this);
    }

    public function index(): ResponseInterface
    {
        return $this->viewRenderer->render('index');
    }
    
    public function contact(): ResponseInterface
    {
        // Some actions.
        return $this->viewRenderer->render('contact', [
            'parameter-name' => 'parameter-value',
        ]);
    }
}

如果控制器中有许多方法（操作），这将非常方便。

向视图注入额外数据

除了在渲染视图模板时直接传递的参数之外，您还可以设置额外的参数，这些参数将在所有视图中可用。为了执行此操作，您需要一个实现了至少一个注入接口的类

use Yiisoft\Yii\View\Renderer\CommonParametersInjectionInterface;
use Yiisoft\Yii\View\Renderer\LayoutParametersInjectionInterface;

final class MyParametersInjection implements
    CommonParametersInjectionInterface,
    LayoutParametersInjectionInterface
{
    // Pass both to view template and to layout
    public function getCommonParameters(): array
    {
        return [
            'common-parameter-name' => 'common-parameter-value',
        ];
    }
    
    // Pass only to layout
    public function getLayoutParameters(): array
    {
        return [
            'layout-parameter-name' => 'layout-parameter-value',
        ];
    }
}

链接标签和元标签应按相同的方式组织。

use Yiisoft\Html\Html;
use Yiisoft\View\WebView;
use Yiisoft\Yii\View\Renderer\LinkTagsInjectionInterface;
use Yiisoft\Yii\View\Renderer\MetaTagsInjectionInterface;

final class MyTagsInjection implements
    LinkTagsInjectionInterface,
    MetaTagsInjectionInterface
{
    public function getLinkTags(): array
    {
        return [
            Html::link()->toCssFile('/main.css'),
            'favicon' => Html::link('/myicon.png', [
                'rel' => 'icon',
                'type' => 'image/png',
            ]),
            'themeCss' => [
                '__position' => WebView::POSITION_END,
                Html::link()->toCssFile('/theme.css'),
            ],
            'userCss' => [
                '__position' => WebView::POSITION_BEGIN,
                'rel' => 'stylesheet',
                'href' => '/user.css',
            ],
        ];
    }
    
    public function getMetaTags(): array
    {
        return [
            Html::meta()
                ->name('http-equiv')
                ->content('public'),
            'noindex' => Html::meta()
                ->name('robots')
                ->content('noindex'),
            [
                'name' => 'description',
                'content' => 'This website is about funny raccoons.',
            ],
            'keywords' => [
                'name' => 'keywords',
                'content' => 'yii,framework',
            ],
        ];
    }
}

在创建视图渲染器时，将此类实例作为构造函数的第六个可选参数传递，或使用 withInjections() 和 withAddedInjections 方法。

$parameters = new MyParametersInjection();
$tags = new MyTagsInjection();

$viewRenderer = $viewRenderer->withInjections($parameters, $tags);
// Or append it:
$viewRenderer = $viewRenderer->withAddedInjections($parameters, $tags);

传递给 render() 方法的参数具有更高的优先级，并且如果它们的名称匹配，将覆盖注入的内容参数。

注入延迟加载

您可以使用延迟加载进行注入。注入将由实现 Yiisoft\Yii\View\Renderer\InjectionContainerInterface 接口的容器创建。开箱即用，它包含在基于 PSR-11 兼容容器的 InjectionContainer 中。

1. 将注入容器添加到 ViewRenderer 构造函数中

use Yiisoft\Yii\View\Renderer\ViewRenderer;
use Yiisoft\Yii\View\Renderer\InjectionContainer\InjectionContainer;

/**
 * @var Psr\Container\ContainerInterface $container
 */

$viewRenderer = new ViewRenderer(
    injectionContainer: new InjectionContainer($container)
)

1. 使用注入类名而不是实例。

$viewRenderer->withInjections(MyParametersInjection::class, MyTagsInjection::class);

本地化视图文件

您可以使用 withLocale() 方法设置一个特定的区域设置，用于本地化视图文件。

$viewRenderer = $viewRenderer->withLocale('de_DE');

有关本地化的更多信息，请参阅 本地化 部分，该部分位于 yiisoft/view 软件包中。

Yii 配置 参数

'yiisoft/yii-view-renderer' => [    
    // The full path to the directory of views or its alias.
    // If null, relative view paths in `ViewRenderer::render()` is not available.
    'viewPath' => null, 
    
    // The full path to the layout file to be applied to views.
    // If null, the layout will not be applied.
    'layout' => null, 
    
     // The injection instances or class names.
    'injections' => [],
],

文档

• 内部结构

如果您需要帮助或有疑问，Yii 论坛 是一个很好的地方。您还可以查看其他 Yii 社区资源。

许可

Yii 视图渲染器是免费软件。它根据 BSD 许可证发布。有关更多信息，请参阅 LICENSE。

由 Yii 软件 维护。

支持项目

关注更新