> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arupa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 导航

> 定义服务如何向应用导航贡献一个页面。

应用导航是由服务元数据构建的。如果您的服务暴露了一个面向用户的页面，请在其 `info.yaml` 清单中添加导航元数据。这些字段属于服务元数据惯例的一部分，不是属于某个特定导航服务的 API。

## 页面元数据

以下元数据字段定义了一个导航条目：

| 字段            | 是否必需 | 含义                               |
| ------------- | ---- | -------------------------------- |
| `Entry`       | 是    | 用户选择该服务时加载的应用 URL。               |
| `DisplayName` | 否    | 导航中显示的标签。如果省略，则使用服务的 `Name`。     |
| `Icon`        | 否    | 该条目未激活时显示的图标 URL。                |
| `IconSolid`   | 否    | 该条目激活时显示的图标 URL。如果省略，则使用 `Icon`。 |

`Entry` 必须是由该服务的某个 HTTP 路由所提供的 URL，无论该路由是被动态处理，还是通过 static 传输提供服务。导航 UI 会在一个 iframe 中加载该 URL，因此该页面及其资源必须能够通过应用的 URL 空间访问到。

例如，一份清单可以这样声明页面元数据：

```yaml theme={null}
DisplayName: "服务页面"
Entry: "/example/pages/index.html"
Icon: "/assets/icon/example.svg"
IconSolid: "/assets/icon/example-solid.svg"
```

只有当以下所有条件都成立时，导航系统才会创建一个条目：

* 该服务具有 `Entry` 值。
* 该服务的状态为 `running` 或 `degraded`。
* 该服务名称没有被主机的导航配置排除。

仅仅被发现是不够的：已安装但未运行的服务不会显示在导航中。

## 排序与可见性

当前的导航实现从应用配置中的 `[Services.navigator.Params]` 读取其行为。这些设置控制主机如何呈现服务条目，但不会替代清单中的页面元数据。

| 参数          | 格式         | 含义                                     |
| ----------- | ---------- | -------------------------------------- |
| `order`     | 以逗号分隔的服务名称 | 将列出的服务按指定顺序排在最前面，其他可见服务按内核的服务列表顺序排在后面。 |
| `ignore`    | 以逗号分隔的服务名称 | 将列出的服务从导航中排除，即使它们正在运行。                 |
| `i18n`      | 以逗号分隔的语言代码 | 定义导航 UI 中可用的语言。                        |
| `languages` | 以逗号分隔的语言代码 | `i18n` 的别名。两者都设置时，以 `i18n` 为准。         |

`order` 和 `ignore` 中的名称都是服务的 `Name` 值，而不是显示标签。逗号分隔值前后的空白会被忽略，空值也会被忽略。如果没有配置语言，导航 UI 默认使用 `en`。

`order` 参数不会隐藏未列出的服务，它只会把列出的服务排到其余可见条目的前面。

## 图标行为

图标通过公开 URL 引用。当前的导航实现对未激活的条目使用 `Icon`，对选中的条目使用 `IconSolid`。如果没有声明图标，则使用默认的导航图标。

请使用一个在该导航条目可见期间始终可用的图标 URL。图标文件应当通过一个 static 路由或其他稳定的公开资源路径提供。