> ## 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。
导航 UI 会将此 URL 加载到 iframe 中，因此页面及其资源必须可通过应用程序的 URL 空间访问。
例如，清单文件可以像这样声明页面元数据：

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

导航系统仅在满足以下所有条件时才会创建条目：

* 插件具有 `Entry` 值。
* 插件状态为 `running` 或 `degraded`。
* 插件名称未被主机导航配置排除。

仅发现插件是不够的。已安装但未运行的插件不会显示在导航中。

## 排序和可见性

当前的导航实现从应用程序配置中的 `[Plugins.navigator.Params]` 读取其行为。
这些设置控制主机如何呈现插件条目；它们不会替换清单文件中的页面元数据。

| 参数          | 格式         | 含义                                     |
| ----------- | ---------- | -------------------------------------- |
| `order`     | 以逗号分隔的插件名称 | 将列出的插件按指定顺序放在首位。其他可见的插件将按照内核的插件列表顺序排列。 |
| `ignore`    | 以逗号分隔的插件名称 | 将列出的插件从导航中排除，即使它们正在运行。                 |
| `i18n`      | 以逗号分隔的语言代码 | 定义导航 UI 中可用的语言。                        |
| `languages` | 以逗号分隔的语言代码 | `i18n` 的别名。当两者都设置时，`i18n` 优先。          |

`order` 和 `ignore` 中的名称是插件的 `Name` 值，而不是显示标签。

逗号分隔值周围的空格将被忽略。空值将被忽略。
如果未配置语言，导航 UI 将使用 `en`。
`order` 参数不会隐藏未列出的插件。它只会将已列出的插件移动到其余可见条目的前面。

## 图标行为

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

使用一个在导航条目可见期间始终有效的图标 URL。图标文件应通过静态挂载或其他稳定的公共资源路径提供。