DRF--渲染器Renderers

前戏

所谓的渲染器（Renderer），其实就是将服务器生成的数据的格式转换为HTTP请求的格式。REST框架包含许多内置的Renderer类，可以返回各种媒体类型的响应。还支持定义自定义渲染器，灵活地设计自己的媒体类型。

在DRF配置参数中，可用的渲染器依然是作为一个类的列表进行定义。但与解析器不同的是，渲染器的列表是有顺序关系的。REST框架将对传入请求执行内容协商，根据请求的类型确定最合适的渲染器以满足类型要求。

内容协商过程会检查请求头部的 Accept 属性，以确定客户期望的媒体类型。可选的，URL上的格式后缀可用于显式地请求特定的内容类型，例如http://example.com/api/users_count.json 表明客户希望服务器返回JSON格式的数据。

配置渲染器

使用 DEFAULT_RENDERER_CLASSES 设置全局渲染器集合。例如，以下设置将 JSON 用作主要媒体类型，也可以渲染可视化API，这也是DRF的默认配置。

REST_FRAMEWORK = {
    'DEFAULT_RENDERER_CLASSES': (
        'rest_framework.renderers.JSONRenderer',
        'rest_framework.renderers.BrowsableAPIRenderer',
    )
}

还可以为使用 APIView 基于类的视图，设置视图级别的，单独使用的渲染器。

from django.contrib.auth.models import User
from rest_framework.renderers import JSONRenderer
from rest_framework.response import Response
from rest_framework.views import APIView


class UserCountView(APIView):
    # 配置渲染器
    renderer_classes = (JSONRenderer,)

    def get(self, request):
        user_count = User.objects.filter(active=True).count()
        content = {'user_count': user_count}
        return Response(content)

或者对使用 @api_view 装饰器的视图，进行单独的渲染器指定。

from django.contrib.auth.models import User
from rest_framework.renderers import JSONRenderer
from rest_framework.response import Response
from rest_framework.decorators import api_view
from rest_framework.decorators import renderer_classes


@api_view(['GET'])
@renderer_classes((JSONRenderer,))  # 配置渲染器
def user_count_view(request):

    user_count = User.objects.filter(active=True).count()
    content = {'user_count': user_count}
    return Response(content)

视图中配置的优先级高于全局配置

在为API指定渲染器类时，要考虑清楚为每种媒体类型分配什么样的优先级，这一点很重要。如果客户端未明确指定它可以接受的内容类型，例如发送 Accept: */* 属性值，或者根本没有Accept 属性值，那么REST框架将选择settings列表中的第一个渲染器用于渲染响应内容。

JSONRenderer

使用utf-8编码将响应内容渲染为json格式的数据。默认样式包含unicode字符，并使用紧凑样式，没有不必要的空格，例如：

{"unicode black star":"★","value":999}

如果客户端设置了 'indent' 缩进参数，返回的内容将缩进。例如 Accept:application/json; indent=4

{
 　　"unicode black star": "★",
 　　"value": 999
}

TemplateHTMLRenderer

使用Django的标准模板渲染器将数据渲染为HTML格式。与其他渲染器不同，此时传递给Response 的数据不需要序列化。此外，可能还要使用 template_name 参数，指定你要渲染的HTML模板。

TemplateHTMLRenderer使用 response.data 作为上下文字典创建 RequestContext ，并确定要使用哪个模板。

模板的查询规则（按优先顺序）

1. 显式指定的 template_name 参数。
2. 在TemplateHTMLRenderer上显式设置的 .template_name 属性。
3. view.get_template_names() 方法调用的返回结果

下面是一个使用 TemplateHTMLRenderer 渲染器的示例：

class UserDetail(generics.RetrieveAPIView):

　　queryset = User.objects.all()
　　renderer_classes = (TemplateHTMLRenderer,)
　　def get(self, request, *args, **kwargs):
　　　　self.object = self.get_object()
　　　　return Response({'user': self.object},
template_name='user_detail.html')

可以使用 TemplateHTMLRenderer 返回常规HTML页面，也可以返回API类型的响应。

如果你是与其他渲染器类一起混用的网站，则应将 TemplateHTMLRenderer 作为renderer_classes 设置列表中的第一个类。

StaticHTMLRenderer

一个简单的渲染器，只返回渲染好的HTML内容数据。与其他渲染器不同，传递给响应对象的数据应该是要返回内容的字符串形式。

from rest_framework.renderers import StaticHTMLRenderer
from rest_framework.response import Response
from rest_framework.decorators import api_view
from rest_framework.decorators import renderer_classes


@api_view(('GET',))
@renderer_classes((StaticHTMLRenderer,))
def simple_html_view(request):
    # 注意data变量是个字符串，虽然看起来像HTML代码
    data = '<html><body><h1>Hello, world</h1></body></html>'
    return Response(data)