documents — 编辑器文档

查询宿主编辑器中的文档、符号与选区，并订阅文档生命周期事件。

self.documents（类型 EditorDocuments）用于查询宿主编辑器中打开的文档，并订阅文档的打开、修改、保存、关闭等事件。

self.documents 在 UiPlugin 与 ServicePlugin 上均可用。

self.editor 的所有方法只作用于当前活动文档；而 self.documents 可以通过 document_id 操作任意已打开的文档。

查询

方法	说明
`get_active(callback=None)`	获取当前活动文档
`get(document_id, callback=None)`	按 ID 获取文档
`symbols(document_id, callback=None)`	获取文档的符号列表
`get_selection(document_id=None, callback=None)`	获取文档当前选区
`reveal(document_id, line, column=None, callback=None)`	将文档滚动到指定位置

get_active(callback=None)

获取当前活动文档。回调为 callback(document=Document|None)，当没有打开任何文档时为 None。

def on_result(**cb):
    doc = cb.get("document")
    print(doc.document_id if doc else "无活动文档")

self.documents.get_active(on_result)

get(document_id, callback=None)

按 document_id 获取指定文档。回调为 callback(document=Document|None)。

self.documents.get("doc-abc", lambda **cb: print(cb.get("document")))

参数：

document_id (str) — 文档 ID

symbols(document_id, callback=None)

请求文档的符号列表。回调为 callback(result=SymbolResult)；当语言服务关闭时回调为 callback(error=...)，错误码为 unavailable。

def on_symbols(**cb):
    error = cb.get("error")
    if error is not None:
        print("符号不可用:", error)
        return
    result = cb.get("result")
    print(result.stale, [s.name for s in result.symbols])

self.documents.symbols("doc-abc", on_symbols)

SymbolResult.stale 为 True 表示文档在请求发出与响应返回之间发生了修改，结果可能与当前缓冲区不一致，建议丢弃这类结果。

参数：

document_id (str) — 文档 ID

get_selection(document_id=None, callback=None)

获取文档当前选区。回调为 callback(selection=Selection|None)。document_id 缺省时使用当前活动文档。

self.documents.get_selection(
    lambda **cb: print(cb.get("selection"))
)

参数：

document_id (str, 可选) — 文档 ID；缺省使用活动文档

reveal(document_id, line, column=None, callback=None)

将指定文档滚动到目标行列，并定位光标。

self.documents.reveal("doc-abc", 12, column=4)

参数：

document_id (str) — 文档 ID
line (int) — 目标行号
column (int, 可选) — 目标列号

数据类

Document

表示宿主编辑器中打开的一个文档。

字段	类型	说明
`document_id`	`str`	文档 ID
`file_path`	`str`	文档对应文件路径
`language_id`	`Optional[str]`	语言 ID（如 `python`）
`revision`	`Optional[int]`	文档修订号，每次修改递增
`is_active`	`bool`	是否为当前活动文档
`line_count`	`Optional[int]`	行数
`text`	`Optional[str]`	文档文本

Position

表示文档中的一行一列。

字段	类型	说明
`line`	`int`	行号
`column`	`int`	列号，默认 `0`

Selection

表示文档中的一段选区。

字段	类型	说明
`document_id`	`str`	所属文档 ID
`start`	`int`	选区起始偏移量
`end`	`int`	选区结束偏移量
`cursor`	`Optional[Position]`	光标位置，可能为 `None`

DocumentSymbol

语言服务报告的一个符号。from_json 接受层级结构的 LSP DocumentSymbol（含 children）和扁平结构的 SymbolInformation（含 location）。

字段	类型	说明
`name`	`str`	符号名称
`kind`	`int`	LSP 符号类型（如函数、类）
`detail`	`Optional[str]`	附加信息
`children`	`list[DocumentSymbol]`	子符号（层级形状时）
`raw`	`dict`	宿主转发的原始 LSP 数据

SymbolResult

符号查询的结果，并带有计算该结果时的修订号。

字段	类型	说明
`document_id`	`str`	文档 ID
`revision`	`Optional[int]`	计算符号时的文档修订号
`stale`	`bool`	为 `True` 时表示文档在请求与响应之间已变化
`symbols`	`list[DocumentSymbol]`	符号列表

方法	事件主题	触发时机
`on_active_changed(handler)`	`editor.activeDocument.changed`	活动文档切换
`on_opened(handler)`	`editor.document.opened`	文档被打开
`on_changed(handler)`	`editor.document.changed`	文档内容修改
`on_saved(handler)`	`editor.document.saved`	文档被保存
`on_closed(handler)`	`editor.document.closed`	文档被关闭
`on_selection_changed(handler)`	`editor.document.selection.changed`	文档选区变化

sub = self.documents.on_changed(
    lambda **cb: print("文档已修改:", cb)
)

# 使用完成后取消订阅
sub.dispose()

documents — 编辑器文档

On this page