20. 渲染上下文RenderContext、渲染器renderer

drupal的控制器返回渲染数组的时候,系统会派发视图事件,渲染数组被main_content_view_subscriber(主内容视图订阅器)处理,它根据请求的格式,将系统流程定向到对应的格式渲染器,系统默认提供了四个格式渲染器,他们被定义在容器的main_content_renderers参数里面,其中html格式对应的是服务id。为“main_content_renderer.html”的html格式渲染器,我们得到的html格式页面几乎都是它渲染的,它将渲染分为两个步骤:先渲染body标签,然后渲染html标签,其中我们将html的渲染称为根渲染。

具体的工作是由渲染器完成的,它负责将渲染数组转换为html字符串,本篇的主题就是这个渲染器。

要理解它是怎么工作的需要先理解一些知识:

首先是渲染数组,关于它可阅读本系列的《云客Drupal8源码分析之渲染数组(render array)》

其次是渲染上下文,下面介绍一下渲染上下文:

渲染上下文

每次渲染时,渲染数组的渲染过程是从根元素开始的,递归到所有的子元素,它对应着html页面结构,由父元素渲染到子元素,这个过程中有两个问题需要解决:

1:缓存问题,为了提高性能,每个渲染数组只渲染一次,除非变的无效,否则不会再次渲染,这里子元素的缓存性质将影响到父元素,比如子元素一小时后失效,那么父元素的缓存时间也不能超过一小时。

2:附件问题,每个元素都可以定义自己要用到的jscss等附件,需要收集所有的这些附件,以添加到最终的页面上,这个收集过程就伴随渲染过程实现的。

为了解决以上两个问题,系统定义了一个BubbleableMetadata对象(Drupal\Core\Render\BubbleableMetadata),字面翻译为“可冒泡元数据”,每个BubbleableMetadata对象都对应一个元素(或称为渲染数组,可含有子元素),它包含着该元素的缓存数据和附件数据,但根据它的用途,云客这里将它称为“渲染跟踪元数据”,为什么取了BubbleableMetadata这么个名字呢?为什么是冒泡?这跟渲染数组的遍历算法有关系,如果学过计算机数据结构这门课程会比较熟悉冒泡遍历,没学过?没关系后面会讲清楚。

对渲染数组的渲染(遍历)是从根元素开始的,它可能有很多层子元素,每一层也可能有多个并列子元素,渲染并不是将父层渲染完后再开始渲染子层(这叫做广度优先算法),而是使用深度优先算法(将一个元素和它的所有子元素渲染完才会开始渲染兄弟元素),如果把“渲染”比作一个人,它将在元素间不停进出或平移,他的行动轨迹完全符合堆栈数据结构,实际上系统就设置了一个堆栈对象来表示这个轨迹,每个元素对应着一个BubbleableMetadata,这个人在进行渲染工作的时候,只需要将元素对应的BubbleableMetadata对象在堆栈对象中压入、弹出、合并就能解决上面两个问题,这个堆栈对象就是本主题说的渲染上下文对象:Drupal\Core\Render\RenderContext,当渲染进入一个子元素的时候压入一个空的BubbleableMetadata对象到堆栈中,渲染完后更新这个对象,当退出这个元素的时候将BubbleableMetadata和堆栈中前一个BubbleableMetadata合并,这个合并动作就是冒泡,它将子元素的缓存数据和附件数据带到父元素,现在明白为什么叫做冒泡了吧,渲染过程中缓存数据逐级向上传递,附件也全部收集到一起。

这里需要注意的是:“渲染”这个“人”在渲染完某个元素,更新当前的BubbleableMetadata时,也可能依据BubbleableMetadata将渲染结果进行缓存,这样每个元素只渲染一次,每个满足缓存条件的子元素都被独立缓存了,这样大大提高了系统性能。

介绍完上面的准备知识后我们来看一下渲染器是怎么工作的:

渲染器

渲染器的服务id是:renderer

类:Drupal\Core\Render\Renderer

实现了渲染器接口:Drupal\Core\Render\RendererInterface

有以下构造参数,以服务id指出:

controller_resolver:解析渲染数组中的回调,见控制器解析器

theme.manager:主题系统,进行主题渲染

plugin.manager.element_info:用于获取元素的默认值

render_placeholder_generator:产生占位符,占位符请看渲染数组主题

render_cache:执行渲染缓存

request_stack:请求堆栈,用于获取当前请求的渲染上下文,它以请求对象为数组键,保存在属性数组里。

以及必须的渲染上下文及占位符条件配置数组。

drupal的渲染系统是一个很大的系统,各种对象配合工作,由于篇幅原因本主题不介绍以上对象的内容,但不用担心,他们不影响本主题的理解,他们将在后续主题中介绍,现在只需要知道他们的作用足矣。

渲染器的核心方法是doRender,在这个方法中能明白渲染的主要工作,下面是对这个方法的流程说明,请对照着程序看:

Drupal\Core\Render\Renderer::doRender

由于要自我调用渲染子数组,所以其第二个参数$is_root_call表明当前调用是否处于自我递归调用中,仅内部使用,并不是指在渲染根html元素

这里以变量:$elements做为渲染数组来说明:

如果$elements为空直接返回空串

先进行权限检查

如果没有设置$elements['#access']时,看有无访问控制回调$elements['#access_callback'],如果有执行回调,将结果赋值给$elements['#access']

如果$elements['#access']全等为false,则返回空串,如果为AccessResultInterface对象,将其缓存依赖添加到渲染数组,以便权限正确,访问结果不允许的话也返回空串。

如果$elements['#printed']不为空,说明已经被渲染过了,直接返回空(笔者认为返回$elements['#markup']更好)。
 

准备开始渲染实质性工作

取得上下文堆栈对象,它用于跟踪各级渲染数组的缓存数据和附件数据,压入一个初始的BubbleableMetadata对象,字面翻译是“可冒泡元数据”,按用途和直观原因笔者这里翻译为:“渲染跟踪元数据”,是如何跟踪的呢?伴随渲染递归过程,从最里层子元素冒泡到根父元素。

如果有$elements['#cache']['keys']属性或者是根渲染,则合并预配置的必要缓存上下文。

如果设置有$elements['#cache']['keys']则尝试从渲染缓存里面获取渲染结果,渲染缓存里面的内容都是没有经过占位符替换的,所以如果是递归子元素完毕后的根渲染,则返回前要进行占位符替换。

如果存在$elements['#type']则附加元素的默认值,其中如果设置了$elements['#defaults_loaded']不为空将阻止加载,这在某些方面是有用的,比如表单API里面的form_builder()。

判断是否设置延迟构建回调$elements['#lazy_builder'],并检查它的合法性;它的作用就是延迟构建渲染数组,其值只能是两个元素组成的数组:回调及回调的参数,参数可以是NULL或者标量类型值;当指定延迟构建时,渲染数组不能也不应该有子渲染数组,子内容应该由延迟构建回调产生。

判断是否需要运用自动占位符机制,如果需要,则设置$elements['#create_placeholder']为真,当$elements['#create_placeholder']有设置且为真时$elements['#lazy_builder']必须存在,因为需要用它的结果去替换占位符。

$elements['#create_placeholder']有设置且为真时对$elements创建占位符。

如果存在$elements['#lazy_builder']则调用它来构建新元素以代替原元素,将原元素的缓存数据设置到新元素,设置$elements['#lazy_builder_built']TRUE以表示已经调用了延迟构建。

如果设置了$elements['#pre_render']则调用它们,允许其修改渲染数组。

如果$elements['#markup']$elements['#plain_text']不为空,则处理它们,$elements['#plain_text']优先级更高,保证有一个安全的$elements['#markup'],其值为markup对象。

规范化当前元素的渲染跟踪元数据

检查$elements['#printed']的设置,允许$elements['#pre_render']终止渲染。

如果存在$elements['#states']则处理状态信息。

查找出子元素(子渲染数组),如果$elements['#children']不存在则设置它的初始值为空字符串,它代表子元素的html内容字符串。

如果设置了$elements['#theme'],则说明渲染数组需要由主题系统去渲染,调用主题系统进行渲染,这也将渲染子元素,并将结果赋值给$elements['#children'],可以设置$elements['#render_children']防止调用主题渲染。

当没有被主题系统渲染或设置了$elements['#render_children']防止主题渲染,此时当$elements['#children']为空,则进行子渲染,自我调用,这里是递归渲染的开端。

如果存在$elements['#markup'],将它追加到$elements['#children']前面,如果是主题渲染的话,此工作应该由主题系统完成。

如果存在$elements['#theme_wrappers']且没有设置$elements['#render_children'],则由主题系统执行主题包装渲染,它通常在已经渲染的子元素外面包装一些其他元素。

如果存在$elements['#post_render']则执行这些回调。

如果有设置前缀$elements['#prefix']或后缀$elements['#suffix']则运用它们,最终形成渲染后的$elements['#markup'],它是一个Markup对象。

执行渲染上下文堆栈的更新,具体是将代表本元素的BubbleableMetadata(渲染跟踪元数据)变为最新,因为上面许多过程可以改变这些值,比如#pre_render#post_render#lazy_builder等等。

缓存已经被渲染的渲染数组,在以上整个过程中$elements['#cache']['keys']不允许被改变,需要不同的缓存id可以使用缓存上下文去实现。

如果是递归渲染结束后的根渲染,则进行占位符替换,将真正的占位内容值渲染后替换占位变量。

执行冒泡:$context->bubble(),这是渲染跟踪元数据冒泡的关键,也是渲染上下文堆栈对象发挥作用的核心。

最后标记$elements['#printed']为真表示已经渲染过了,返回$elements['#markup'],它代表渲染后的字符串值,以markup对象的方式存在。

补充说明

其实drupal8的所有控制器都是包装在一个渲染上下文中执行的,目的是解决在控制器中直接渲染内容丢失BubbleableMetadata的问题,有望在drupal9中通过禁止在控制器中直接渲染解决。

渲染器进行根渲染后jscss附件仅通过占位tokens代替,在后续流程中才会真正附加这些附件。

doRender等方法的$is_root_call参数代表当前调用是否为一个递归调用,并不表示在进行html文档的根渲染,它是一个编程技巧,仅内部使用,在递归过程中不会进行占位符替换。

渲染器的$contextCollection属性,它是SplObjectStorage对象,保存请求堆栈中每个请求对应的请求上下文堆栈对象,注意它是静态属性,这意味着不管多少个渲染器实例,渲染上下文保证每个请求只对应一个,在executeInRenderContext方法中会临时设置一个上下文,用完即毁,然后复原之前的上下文。

强调一下在渲染过程中$elements['#cache']['keys']不允许被改变。

本书共161小节。


目前全部收费内容共295.00元。购买全部

评论 (0)