# OINK 1.1.0：原生多语言界面、导航与站点扩展

> OINK 1.1.0 带来 32 份原生界面目录、分类法目录、可靠的侧栏状态、站点自定义 搜索动作，以及打印、键盘焦点和图片复制修复。

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

OINK 1.1.0 是稳定 1.0 契约之后的第一个次版本：补齐原生界面翻译，让分类法根页
成为实用的导航目录，并处理社区对侧栏状态、键盘焦点、内容分组与搜索扩展的反馈。
现有 1.0 内容与配置不需要迁移源码。

## 概览 {#at-a-glance}

- **32 份原生界面目录**：从 Docsy 继承的 31 个 locale 名称，加上通用 `zh`，均包含
  相同的 194 条 OINK 消息，并采用各语言的复数规则。
- **分类法目录**：标签、分类、作者与系列提供紧凑术语卡片、本地化页头，以及站点已
  声明分类法之间的切换器。
- **可靠的导航**：缓存侧栏保留页面设置，隐藏的侧栏退出焦点顺序，分组分区保留子文档。
- **站点扩展 API**：`OinkSidebar` 提供已经提交的展开状态；
  `OinkCommandPalette.registerSearchTail` 支持使用当前查询的站点动作。
- **干净的文章复制**：图片缩放不再向复制出的纯文本或 HTML 插入隐藏的预览提示。
- **正确的 Print 与预览输出**：专用 Print 去除外壳导航，重叠的 Book 聚合不再竞态，
  非法组件输入保留文档约定的回退行为。

## 原生界面与分类法目录 {#interface-and-taxonomies}

32 份 locale catalog 现在均使用原生 OINK 界面文本，不再包含机械生成的英文回退块。
页面计数交给 Hugo 按 CLDR 复数类别选择，覆盖需要多于单数、复数两种形式的语言。
目录检查涵盖缺失或多余的键、重复条目、占位符、复数形式与隐藏的双向文本控制字符。
这项工作翻译的是主题界面；站点正文仍由各站点自行提供译文。

`/tags/`、`/categories/`、`/authors/` 与 `/series/` 等分类法根页显示按使用量排序的
紧凑术语卡片网格。分类法页与术语页共用本地化页头，右栏可以切换到站点已声明的其它
分类法。作者卡片可以显示头像，具体术语页仍采用行列表归档。面包屑使用相同的本地化
分类法名称。

## 侧栏、分组与焦点 {#navigation-and-focus}

缓存侧栏现在遵循影响输出的页面与 cascade 有效设置；没有 JavaScript 时仍可导航，
恢复当前路径时也不会短暂降低对比度。带页面专属侧栏标题的 Book 页面不再复用共享
目录树缓存。

社区反馈对应四项修复：

- [#41](https://github.com/pgsty/oink/issues/41)：关闭侧栏或抽屉后，隐藏内容不再接受
  键盘焦点，也不再暴露给辅助技术。恢复按钮、桌面悬停展开、移动端焦点归还与 Escape
  关闭继续正常工作。整列收起右侧大纲时，同样隔离内容并将焦点交给恢复按钮；移入移动
  抽屉的分组仍可使用，不会继承桌面右栏的隐藏状态。抽屉的 Tab 循环只包含可见且可操作
  的控件，闭合分支不会再让焦点漏到背后的正文。
- [#42](https://github.com/pgsty/oink/issues/42)：`sidebar_divider: true` 将分区变成不带
  链接的分组标签，同时保留子文档。配合 `build.render: never` 可不发布分组自身的
  页面。面包屑不会生成分组死链接，搜索与翻页跳过分组，Print 与 Book 目录保留子文档。
  无链接组头也参与目录树键盘导航：左方向键 / `a` 先返回组头，再折叠分组；右方向键 /
  `d` 先展开，再进入子项。`q` / `e` 仍只在页面链接间移动。显式导航树也能在带语言和
  部署路径前缀时正确解析。
- [#43](https://github.com/pgsty/oink/pull/43)：`sidebar_root_menu: false` 对顶层分区与
  自根分区均生效。当前可链接的根仍作为位置标记显示；未发布分区与分隔分区不再生成
  切换器链接。
- [#44](https://github.com/pgsty/oink/issues/44)：鼠标点击阅读容器后，再按无关按键不会
  突然出现大面积焦点边框；键盘导航与跳转正文链接继续保留可见焦点提示。

创作写法见[内容分组](/zh/docs/write/organize/#group-only)，运行时行为见
[侧栏契约](/zh/docs/design/shell/#sidebar-runtime)。

## 站点自定义扩展 {#site-extensions}

`window.OinkSidebar` 提供就绪 Promise、`getState`、`setExpanded` 与展开状态事件。
就绪信号会等缓存树恢复当前路径、响应式外壳完成分组安置后再发出，避免站点保存的状态
被后续初始化覆盖。OINK 先提交视觉状态、ARIA 与 inert 状态，再通知消费方。站点可以
通过该 API 保存读者选择的展开分支；存储方式、版本与语言策略由站点决定。恢复保存的
状态不会隐藏当前页面的祖先路径。

针对 [#40](https://github.com/pgsty/oink/issues/40)，受信任的站点 JavaScript 可以通过
`OinkCommandPalette.registerSearchTail({id, rows, activate})` 注册搜索尾部动作。
非空文本查询结束后，这些行显示在原生结果与动作之后，空结果与索引错误状态也可使用。
OINK 负责行渲染、激活、取消，并提供显式 `handoff()`，将焦点交给站点自己的界面。
异步动作尚未完成时，其它 Palette 行不能启动相互竞争的动作，包括打开选项列表的原生
命令；当前动作结束后解除激活限制。写法见[集成示例](/zh/docs/customize/panel/#search-tail)。

两个 API 都是可选能力。现有站点采用本版本时不必增加脚本或修改配置。本地搜索仍默认
关闭，搜索扩展需要启用对应的 Palette；OINK 不内置远程助手、供应商凭据或查询遥测。

## 复制、Print 与组件修复 {#copying-print-and-components}

启用图片缩放时，旧版本会在每张符合条件的图片后插入视觉隐藏的预览提示。浏览器复制
可能把这些文字带进纯文本与富文本 HTML，目标编辑器丢弃主题样式后便会显示出来。
现在，缩放按钮通过 ARIA 名称提供图片描述与本地化动作，不再插入正文文字节点。
作者图片、alt、图注、键盘操作与对话框焦点归还均保留。修复覆盖普通图片与画廊的缩放
按钮，图片缩放仍默认关闭。详见[图片缩放](/zh/docs/components/image/#zoom)。

专用 Docs 与 Blog Print 输出不再包含站点顶栏或交互外壳初始化。每个页面由一个协调器
按固定顺序渲染普通输出与 Book 聚合输出，避免共享 Page Store 上的竞态，并保留各自
约定的标题与标签页 ID。

非法 `book-toc drafts` 值告警后继续使用文档约定的默认值。非字符串的 Landing
`preview.source` 在普通预览中告警并仅省略该分区。Redoc 本地规范路径统一相对于
`static/` 解析，在根路径与子路径部署下，无论开头是否带 `/` 都得到相同结果；有效的
远程 HTTP(S) URL 行为保持不变。

## 兼容性 {#compatibility}

Hugo Extended **0.160.1** 仍是兼容性下限，持续集成固定工具链为 **0.165.0**。
模块与 1.0.0 一样声明 Go **1.27.0**。Node 与 npm 用于文档回归套件，普通 Hugo 站点
构建不需要它们。

在 Hugo 0.160.x 上，非默认通用 `zh` 与区域中文目录并存时，需要配置
`locale: zh-CN`。在该组合中，裸 `locale: zh` 从 Hugo 0.161 起可用。阿拉伯语、波斯语
与希伯来语站点仍需为语言设置 `direction: rtl`。

从 1.0.0 升级无需迁移组件或配置。分类法根页的布局会有可见变化。覆盖过侧栏、分类法、
Print 或图片缩放实现的站点应与新版主题比较：复制到站点的实现不会自动获得上游修复。
兼容旧版本的站点脚本应先检测新 API 是否存在。

不再下发无效的 ScrollSpy 补丁。`params.ui.scroll_spy` 与页面级 `scroll_spy` 在整个
1.x 期间仍作为静默 no-op 接受；OINK 的普通大纲运行时已经跟踪当前标题。兼容
partial、受支持的搜索后端与迁移工具均继续保留。

## 验证与发布状态 {#verification}

实现提交 [`08f6563`](https://github.com/pgsty/oink/commit/08f656303ba4b1299db92973bc02a4c5d3ba1ca3) 已通过
[固定工具链主题 CI](https://github.com/pgsty/oink/actions/runs/35477171223) 的 Hugo 检查、
浏览器运行时测试与 Book 出版检查。此前的社区修复验收，以及后续中英文图片复制回归，
记录在[上游调研报告](/zh/docs/design/research/2026-09-19-upstream-review/)。补充的初始化、
动作并发与键盘焦点修复，以及源码验收记录在
[发布审查报告](/zh/docs/design/research/2026-09-20-release-review/)。
本地验收通过 44 项 JavaScript 测试、57 项站点测试和 149 项 Chromium 测试。
Hugo Extended 0.160.1 也通过定向兼容性检查与真实文档站的严格生产构建。

输出检查器默认构建新 fixture，只有显式指定输出目录时才复用已有结果。检查器启动的
每个 Hugo 进程都有 120 秒上限；重复的 warning-fatal 构建已去除，逐例诊断与回退断言
仍然保留。

已发布的 [`v1.1.0`](https://github.com/pgsty/oink/releases/tag/v1.1.0) 标签指向
[`3a18234`](https://github.com/pgsty/oink/commit/3a18234aa3af15ae12e2d53839ffd321ef4bcb62)，
该提交仅在已验收实现上收口更新日志，并通过全部三项
[发布提交 CI](https://github.com/pgsty/oink/actions/runs/35482327047)。
通过全新缓存从[官方 Go 模块代理](https://proxy.golang.org/github.com/pgsty/oink/@v/v1.1.0.info)
下载的版本准确解析到该提交；模块归档与 `go.mod` 的校验和均已通过
[sum.golang.org](https://sum.golang.org/lookup/github.com/pgsty/oink@v1.1.0) 验证。

主题发布不会自动更新消费站。各站点仍需固定新模块，在没有文件系统替换的情况下
构建，并验证部署后的输出。

## 升级 {#upgrade}

固定公开版本并执行严格生产构建：

```bash
hugo mod get github.com/pgsty/oink@v1.1.0
hugo mod tidy
hugo --cleanDestinationDir --gc --minify --environment production \
  --printPathWarnings --panicOnWarning
```

提交 `go.mod` 与 `go.sum`，检查分类法目录、缓存与移动侧栏、分组导航、Print 与 Book
输出、文章复制，以及站点的语言、深浅色与子路径路由。操作清单见
[1.0 → 1.1 升级核对项](/zh/docs/admin/upgrade/#from-1-0)。

仓库级完整变更记录继续保存在
[CHANGELOG.md](https://github.com/pgsty/oink/blob/v1.1.0/CHANGELOG.md)。

---

反链：

- [文档](/zh/docs/)