> ## Documentation Index > Fetch the complete documentation index at: https://openidea.sh/llms.txt > Use this file to discover all available pages before exploring further. # 视图与装饰 > 工具窗口、自定义编辑器、网页视图、服务节点、由代码打开的编辑器标签页和终端，以及编辑器与项目树装饰。 插件可以在这些地方放置界面： | 位置 | 声明 | 内容 | | - | - | - | | 工具窗口 | `[[contributes.views]]` | 由代码渲染（树、列表、表单、表格、消息、HTML）或网页 | | **服务** 工具窗口 | `[[contributes.views]]`，`location = "services"` | 由代码渲染的树，外加详情面板 | | 特定文件的编辑器 | `[[contributes.customEditors]]` | 由代码渲染或网页；与文件共用同一个文本文档 | | 编辑器标签页和终端 | 无需声明（由代码打开） | 内容标签页、日志标签页、终端会话、输出通道 | | 编辑器和项目树中的标注 | 无需声明（由代码设置） | 装饰 | 行号槽标记和行号槽按钮属于编辑器提供者，见 [语言功能](https://openidea.sh/zh/plugins/guides/language-features.md)。 文件图标见 [图标主题](https://openidea.sh/zh/plugins/guides/icon-themes.md)。 ## 声明工具窗口 ```toml theme={null} [[contributes.views]] id = "todos" title = "TODO Example" icon = "search" # IDE 图标名（最多 64 字节）或包内 SVG location = "right" # left、right（默认）、bottom、services ``` | 字段 | API | 说明 | | - | - | - | | `id` | 1.0 | 插件内唯一。 | | `title` | 1.0 | 1–256 字节，通过插件的文本目录翻译。 | | `icon` | 1.0 | 图标名或包内 `.svg`（最大 64 KiB，会被净化）。 | | `location` | 1.0 | `left`、`right`、`bottom`；`services` 需要 API 1.3。 | | `web` | 1.0 | 包内网页（`web/index.html`），代替由代码渲染的内容。见下文“网页视图”。 | | `group` | 1.3 | 同一插件中 group 相同的视图共用一个工具窗口，每个视图一个标签页，按声明顺序排列。 | | `when` | 1.3 | `when` 子句；为假时视图从侧栏和分组标签中移除，既不渲染也不激活。 | | `secondary` | 1.3 | 为 `true` 时放在所在停靠区的次级分区：**左下**、**右下** 或 **底部右侧**。用户保存的位置优先。 | | `detail` | 1.3 | 为 `true` 时在树或列表旁显示所选条目的详情标签页（不能与 `web` 同用）。 | | `header` | 1.3 | 不分组的工具窗口网页视图若自己绘制顶栏，可设为 `none`（见“网页视图”）。默认 `default`。 | 没有 `web` 的视图需要代码（`wasm`）。显示视图会激活插件（`on-view:`）。 ### 分组与条件显示 ```toml theme={null} engines.openidea = "^1.3" [[contributes.views]] id = "endpoints" title = "Spring" group = "spring" when = "workspaceContains:pom.xml || workspaceContains:build.gradle" [[contributes.views]] id = "beans" title = "Beans" group = "spring" when = "plugin.my-plugin.ready" ``` 分组中的第一条声明决定窗口的标题、图标、位置和 `secondary`，即使这个视图当前被隐藏；所有标签页都隐藏时窗口消失。 标签页在首次选中时加载，之后只要仍然适用就保持挂载，所以切换标签时网页视图的状态不会丢。上下文变化、文件新建或删除、 项目切换时会重新计算 `when`。这些字段只控制可见性，不授予任何访问权限。 ## 渲染视图 注册 `register_plugin!(MyPlugin, views)` 并实现 `openidea_plugin::views::Views`（WIT 导出 `view-provider`）。 视图就是数据：工具栏、主体和状态行。IDE 用自己的组件绘制（主题、键盘操作、快速搜索），再把用户的操作发回来。 摘自 [TODO Finder](https://github.com/l0ng-ai/openidea/tree/main/plugins/official/todo-finder) 示例： ```rust theme={null} use openidea_plugin::views::{Body, ListItem, View, ViewEvent, Viewport, Views}; use openidea_plugin::{Error, Invocation, Location, TextQuery, host, register_plugin}; fn query() -> TextQuery { TextQuery { pattern: "TODO".into(), case_sensitive: true, ..Default::default() } } impl Views for TodoFinder { fn render(&mut self, _view: &str, _viewport: Option, ctx: &Invocation) -> Result { let found = ctx.project().ok_or("Open a project first")?.search_text(&query(), 500)?; let items = found .matches .into_iter() .map(|m| { let detail = format!("{}:{}", m.location.path, m.location.range.start.line + 1); ListItem::new(&serde_json::to_string(&m.location).unwrap(), &m.line).detail(&detail) }) .collect(); Ok(View { toolbar: vec![], body: Body::List(items), status: found.limit_hit.then(|| "Showing the first 500 matches".into()), }) } fn handle(&mut self, _view: &str, event: ViewEvent, _ctx: &Invocation) -> Result<(), Error> { if let ViewEvent::Activate(key) = event { let location: Location = serde_json::from_str(&key).map_err(|e| Error::Invalid(e.to_string()))?; host::open_location(&location.path, location.range.start.line, location.range.start.character)?; } Ok(()) } } register_plugin!(TodoFinder, views); ``` 内容变化时调用 `host::refresh_view(view)`，IDE 会再次调用 `render`。`host::reveal_view(view)` 在发起调用的窗口中把插件的某个视图切到前台。对工具窗口来说，`ctx.editor()` 是窗口中当前活动的文本编辑器， 所以工具栏按钮可以操作用户正在编辑的内容。 ### 主体类型 | 主体 | 说明 | | - | - | | `Body::Message(text)` | 居中消息：空状态和错误。可用 `View::message(text)` 构造。 | | `Body::Tree(items)` | `TreeItem` 的扁平列表，`parent` 指向更早出现的 key。`.expandable(expanded)` 在子节点未知时先显示展开箭头，`Expand` 事件再请求子节点。 | | `Body::List(items)` | `ListItem::new(key, label)`，可加 `.icon()` 和 `.detail()`（标签后的灰色文字）。 | | `Body::Form(fields)` | `Field::new(key, label, value)`：`Text`、`Multiline`、`Checkbox`、`Choice(options, chosen)`。API 1.3 新增 `FieldValue::label(text)` 和 `FieldValue::readonly_text(text, multiline)`。 | | `Body::Table(table)` | `columns`、`total_rows`、`first_row`、`rows`、`editable`。IDE 只请求可见的行（`viewport`）；`Viewport::range(viewport, total, default_rows)` 用于裁剪范围。 | | `Body::sortable_table(&table, sort)` | 表头可点击的表格。点击会发来列和方向（`ViewEvent::sort()`），插件排序后重新渲染。 | | `Body::Html(html)` | 在沙箱 frame 中显示的 HTML（见下文）。 | 工具栏按钮：`View::new(body).button(Button::new("refresh", "Refresh").icon("refresh"))`，状态行：`.status("12 items")`。 ### 事件 `ViewEvent` 包括 `Button(id)`、`Activate(key)`（双击或回车）、`Select(key)`、`Expand(key)`、`Collapse(key)`、 `Field(key, value)`（复选框为 `true`/`false`）、`Cell { row, column, value }`、`InsertRow(before)`、 `DeleteRows(rows)`，以及来自 HTML 主体的 `Message(text)`。表格行的单击和空格用 `event.table_select()` 解码， 双击和回车用 `event.table_activate()`（API 1.3，从 0 开始的绝对行号）。 后续 API 新增的主体、字段和事件以 `Other { kind, data }` 传递：IDE 不认识某种主体时会提示需要更新， 不认识的字段类型则直接省略。条目右键菜单使用 `viewItem.context`（见 [命令与动作](https://openidea.sh/zh/plugins/guides/commands.md) 中的“菜单”一节）。 ## 自定义编辑器 自定义编辑器打开与 patterns 匹配的文件，编辑的是该文件的文本文档： ```toml theme={null} [[contributes.customEditors]] id = "table" title = "Table" patterns = ["*.csv", "*.tsv"] # 1–16 个文件名通配符，不能含目录 priority = "default" # 或 "option"：只能通过“打开方式”使用 layout = "tab" # 或 "split" / "preview"：显示在文本编辑器旁边 # web = "web/index.html" # 用网页代替代码渲染的内容 ``` * `priority = "default"` 时匹配的文件直接用插件编辑器打开；`option` 时可通过 **打开方式** 选择。 **作为文本打开** 会打开文本编辑器。 * `layout = "split"` 或 `"preview"` 时，文件在文本编辑器中打开，插件编辑器显示在旁边，标签栏中出现 **仅编辑器** / **编辑器和预览** / **仅预览** 切换，和 Markdown 一样；取值决定文件打开时的初始布局。 `"tab"`（默认）是独立的标签页。 * 在 `render` 和 `handle` 中，`ctx.editor()` 就是该编辑器的文档。用 `document()` 读取， 用 `apply_edits(version, edits)` 修改。同一文件的文本编辑器会同步变化，撤销/重做共用一份历史， 保存、修改标记和关闭提示都归文档所有。 [CSV Editor](https://github.com/l0ng-ai/openidea/tree/main/plugins/official/csv-editor) 把表格编辑转换成文本编辑： ```rust theme={null} fn handle(&mut self, _view: &str, event: ViewEvent, ctx: &Invocation) -> Result<(), Error> { let editor = ctx.editor().ok_or_else(|| Error::Invalid("the table editor needs a document".into()))?; let doc = editor.document()?; let edits = edits_for(&doc.text, &event)?; if !edits.is_empty() { // 如果用户同时在文本视图中输入，会返回 Stale；表格随后重新渲染。 editor.apply_edits(doc.version, &edits)?; } Ok(()) } ``` 它需要 `editor.read` 和 `editor.write`。 ## HTML 主体 `Body::Html` 在沙箱 frame 中运行：不透明源（opaque origin），CSP 只允许其内联脚本、内联样式和 `data:` 图片， 没有网络，也没有 IDE API。它只能通过 `openidea.postMessage(text)` 和 `openidea.onMessage(fn)` 与插件通信， 消息以 `ViewEvent::Message` 送达，插件用 `host::post_view_message(view, text)` 回复。 [Regex Tester](https://github.com/l0ng-ai/openidea/tree/main/plugins/official/regex-tester) 就是这样工作的。 重新渲染会重新加载 frame，所以状态应由页面自己保存。 frame 会跟随 IDE 主题变化而无需重新加载。其根元素带有 `data-theme="light|dark"` 以及以下 CSS 变量（均为具体颜色值）： | 变量 | 含义 | | - | - | | `--openidea-bg`、`--openidea-bg-elevated`、`--openidea-bg-hover`、`--openidea-bg-selected`、`--openidea-bg-input` | 表面色（frame 本身透明） | | `--openidea-fg`、`--openidea-fg-strong`、`--openidea-fg-muted` | 文字 | | `--openidea-border`、`--openidea-focus-ring`、`--openidea-link` | 线条、焦点、链接 | | `--openidea-accent`、`--openidea-fg-on-accent` | 强调色及其上的文字 | | `--openidea-danger`、`--openidea-warning`、`--openidea-success`、`--openidea-info` | 状态色 | | `--openidea-font-ui`、`--openidea-font-mono`、`--openidea-font-size` | 字体（IDE 自带的网页字体在 frame 中不可用） | 脚本还可以使用 `openidea.theme`（`{ dark, vars }`）和 `openidea.onThemeChange(fn)`。变量只会增加，不会删除。 ## 网页视图 视图或自定义编辑器也可以是包内附带的网页，用来实现声明式主体表达不了的界面（画布、图表编辑器等）。不需要代码： ```toml theme={null} [[contributes.customEditors]] id = "preview" title = "Preview" patterns = ["*.dot", "*.gv"] layout = "split" web = "web/index.html" # 页面；它所在的目录就是它能加载的范围 ``` * 页面所在目录（绝不是包根目录）属于声明的一部分：其下每个文件都会被检查（最多 4096 个文件、256 MiB，不允许链接）， 随包安装和签名。 * 页面从 IDE 自己的 URL scheme 加载到 `