参考：SeoMetadata 属性¶

模板上下文变量 seo 是一个 FinalizedSeoMetadata 实例。其中所有 UNSET 哨兵值都已解析完毕，每个字段都是可以直接渲染的 Python 值。

FinalizedSeoMetadata 字段¶

字段	类型	说明
`title`	`str \\| None`	页面标题（不含后缀）。
`title_suffix`	`str`	追加到标题末尾的后缀（未设置时为空字符串）。
`full_title`	`str`	`title + title_suffix`。`title` 为 `None` 时为空字符串。属性（property）。
`h1`	`str \\| None`	页面主标题文本，与 `<title>` 相互独立。
`meta_description`	`str \\| None`	`<meta name="description">` 的内容。
`meta_keywords`	`str \\| None`	`<meta name="keywords">` 的内容。
`robots`	`str \\| None`	`<meta name="robots">` 的内容。
`canonical_url`	`str \\| None`	绝对规范 URL。
`hreflang`	`list[HreflangAlt]`	hreflang 替代链接列表。未设置时为空列表。
`og`	`dict[str, str]`	Open Graph 值，以 property 后缀为键（例如 `"title"`、`"image"`）。根据页面元数据自动填充。
`twitter`	`dict[str, str]`	Twitter 卡片值，以标签名后缀为键。根据 `og` 的值自动填充。
`jsonld`	`list[dict]`	各层累积的 JSON-LD 对象。未设置时为空列表。
`extra_head`	`list[str]`	插入 `<head>` 的额外 HTML 片段。未设置时为空列表。

HreflangAlt¶

seo.hreflang 中的每一项都是一个 HreflangAlt 命名元组：

字段	类型	说明
`lang`	`str`	语言代码，或 `"x-default"`。
`href`	`str`	该语言版本的绝对 URL。

SeoMetadata（部分元数据 / 构建器）¶

SeoMetadata 是一个不可变的 dataclass，provider 用它来表达“部分”元数据：只填写自己关心的字段。它与模板中看到的 FinalizedSeoMetadata 是两个不同的类。

构造部分元数据¶

from seo_suite.metadata import SeoMetadata

# Only the named fields are set; all others are UNSET.
md = SeoMetadata.partial(
    title="My Page",
    meta_description="A description.",
    robots="noindex",
)

字段¶

与 FinalizedSeoMetadata 同名：

title、title_suffix、h1、meta_description、meta_keywords、 robots、canonical_url、hreflang、og、twitter、og_image、jsonld、 extra_head

Note

og_image 只存在于 SeoMetadata（构建器）上，FinalizedSeoMetadata 没有这个字段。最终化（finalisation）时，og_image 会被合并进 og["image"] 和 twitter["image"]，不会作为独立字段出现在渲染结果中。

在 Python 中访问 seo 对象¶

在视图或中间件中：

from seo_suite.context import resolve_seo, attach_seo

# Resolve (not memoized):
seo = resolve_seo(request, view=view, obj=obj)

# Resolve and memoize on the request:
seo = attach_seo(request, view=view, obj=obj)

# Read back a memoized result without re-resolving:
from seo_suite.context import get_attached
seo = get_attached(request)  # None if not yet resolved

安全地检查字段¶

所有标量字段在未设置时都是 None。可以用 Django 的 default 模板过滤器，或者按 Python 的常规真值判断来处理：

{{ seo.h1|default:seo.title }}

if seo.canonical_url:
    do_something(seo.canonical_url)

og 和 twitter 始终是字典（不会是 None）；hreflang、jsonld 和 extra_head 始终是列表（不会是 None）。

as_dict()¶

把最终化后的元数据转换为普通字典（适合用于 JSON 响应或日志）：

seo = resolve_seo(request)
data = seo.as_dict()