Sublime插件API手冊

2012-11-28 22:32:44來源:ued.alimama.com作者:人點擊

本文為Sublime插件API手冊的中文翻譯版本,英文版地址:http://www.sublimetext.com/docs/2/api_reference.html

翻譯和理解水平有限,有不當的地方歡迎指正。部分方法描述里添加了些個人的注解,希望有助于理解方法的使用。

后期如果有更多實踐經驗的話再回過頭來修正可能解釋有誤的地方,或加些注解。

 閱讀全文

Sublime插件開發API手冊

Sublime API

基類

插件示例

在sublime的插件目錄下Packages/Default里有幾個預置的插件,可以作為參考看看:

  • Packages/Default/delete_word.py 刪除光標左邊或者右邊的一個單詞

  • Packages/Default/duplicate_line.py 復制當前行

  • Packages/Default/goto_line.py 提示用戶輸入,然后更新選擇點

  • Packages/Default/font.py 展示了如何使用settings

  • Packages/Default/mark.py 用了add_regions() 往行頭槽里插入圖標

  • Packages/Default/trim_trailing_whitespace.py 保存前修改緩沖區

sublime模塊

方法 返回值 描述
set_timeout(callback, delay) None 延時調用 (毫秒). 回調的順序會按添加的順序依次執行. 多線程調用setTimeout也是安全的.
status_message(string) None 設置狀態欄消息.
error_message(string) None 顯示一個error對話框.
message_dialog(string) None 顯示一個message對話框.
ok_cancel_dialog(string, <ok_button>) bool 顯示一個"確認/取消"的對話框。如果有"確認"按鈕,點擊確認返回True.
load_settings(base_name) Settings 載入一個配置,name參數要包括文件名和后綴而不是路徑。會根據base name搜索插件包,結果返回setting對象。后續調用load_settings載入同一個base_name將返回同一個對象,而不會重新從磁盤讀取文件。
save_settings(base_name) None 保存配置,寫入磁盤。
windows() [Window] 返回打開窗口的列表。
active_window() Window 返回最近使用的一個窗口。
packages_path() String 返回packages目錄的路徑.
installed_packages_path() String 返回所有用戶 *.sublime-package文件的目錄。
get_clipboard() String 返回剪貼板的內容。
set_clipboard(string) None 設置剪貼板的內容。
score_selector(scope, selector) Int 把選擇器設置成對應的區域,返回區域值。 0標示沒有選區,大于0表示有一個選區。 不同的選擇器可以通過scope來比較: scope值越高說明這段選區越適合這個選擇器.
run_command(string, <args>) None 運行ApplicationCommand,string是command名字,args是傳給command的參數。
log_commands(flag) None 控制命令的日志。如果啟用,所有command從快捷鍵,菜單中執行都回記錄到控制臺。
log_input(flag) None 控制日志輸出。如果啟用,所有按鍵都回被記錄到控制臺。
version() String 返回版本號。
platform() String 返回運行的平臺。"osx", "linux" 或者 "windows"。
arch() String 返回CPU架構。64/32位,"x32" or "x64"。

sublime.View類

view代表了text buffer(緩沖區)中的視圖。注意,多個view可以引用同一段buffer, 但是它們有自己唯一的選區和幾何形狀。

方法 返回值 描述
id() int 返回當前view的唯一標識ID。
buffer_id() int 返回當前view下buffer標識的唯一ID。
file_name() String 返回buffer關聯的完整文件名,如果沒有緩沖區存儲在磁盤的話返回None。(buffer指緩沖區,下同)
name() String 返回buffer指定的名稱。
set_name(name) None 設置buffer的名稱。
is_loading() bool 如果buffer還在從磁盤載入返回ture,表示還未準備好給用戶使用。
is_dirty() bool 返回是否有未保存到buffer的修改。
is_read_only() bool 返回true,如果buffer不允許修改。
set_read_only(value) None 設置緩沖區不可修改。
is_scratch() bool 如果緩沖區是臨時緩沖區返回True。臨時緩沖區不會報告為dirty。
set_scratch(value) None 設置buffer為臨時緩沖區。
settings() Settings 返回view的settings對象。settings對象對當前view是私有的。
window() Window 返回持有當前view的window。
run_command(string, <args>) None 運行指定的TextCommand,args傳入參數。
size() int 返回文件中字符總數量。
substr(region) String 返回region選區內容字符串。
substr(point) String 返回point點的右側字符。
begin_edit(<command>, <args>) Edit 創建一個edit對象,可以劃定一組撤銷操作,需要對應到 end_edit()標記。
end_edit(edit) Edit 標記完成一個edit對象。(譯者注:begin_edit到end_edit之間的操作可以當成一個命令分組,可以用于撤銷操作。)
insert(edit, point, string) int 在緩沖區指定的點插入一個字符串。返回插入的字符數量;如果插入當前緩沖區的tabs返回有點區別。
erase(edit, region) None 從緩沖區移除region選區內容。
replace(edit, region, string) None 把region選區內容替換成指定的字符串。
sel() RegionSet 返回selection(選擇)的引用。
line(point) Region 返回point點所在的行。
line(region) Region 返回region區域行頭到行尾的一份拷貝,從行頭到行尾可能跨了多行(譯者注:換行顯示的時候,但是中間沒有換行符)。
full_line(point) Region 同 line(),但是尾部有換行符的時候也包括了換行符。
full_line(region) Region 同 line(), 但是尾部有換行符的時候也包括了換行符
lines(region) [Region] 返回region區域的所有行列表 (經過排序) 。
split_by_newlines(region) [Region] 用換行符把整個region分割成多個region區域,返回region列表。
word(point) Region 返回包含point點的單詞。
word(region) Region 返回包含region區域的單詞區域(從第一個單詞的開頭,到最后一個單詞的末尾)。有可能會跨多個單詞。
find(pattern, fromPosition, <flags>) Region 返回匹配的第一個區域,從指定的點位置開始,沒有匹配結果返回None。flags參數可以是 sublime.LITERAL, sublime.IGNORECASE, 或者2個"或運算"。
find_all(pattern, <flags>, <format>, <extractions>) [Region] 返回所有(無重疊)的匹配區域結果。flags參數同上, 如果有format參數,所有匹配結果都會按指定格式被格式化并添加到extractions列表里。
rowcol(point) (int, int) 計算指定點從0開始的行位置和列位置。
text_point(row, col) int 計算指定行,列位置字符的偏移量。"col"("列")是從一行的行頭開始的字符數量。
set_syntax_file(syntax_file) None 指定語法文件。view. syntax_file文件應該是按行來定義語法名稱,基于Packages/Python/Python.tmLanguage。接受當前語法可以使用view.settings().get('syntax')。
extract_scope(point) Region 返回指定點位置字符語法名稱的范圍
scope_name(point) String 返回指定點位置字符的語法名稱。
score_selector(point, selector) Int 返回包含指定點位置的選擇器(selector)的數量(score)。score為0表示沒有匹配, 大于0表示一個匹配,不同的選擇器可以通過scope來比較: scope值越高說明這段選區越適合這個選擇器。
find_by_selector(selector) [Regions] 返回符合指定選擇器的所有區域,結果為一個列表。
show(point, <show_surrounds>) None 滾動view到指定的點。
show(region, <show_surrounds>) None 滾動view到指定的區域。
show(region_set, <show_surrounds>) None 滾動view到可以顯示指定的區域集。
show_at_center(point) None 滾動到view的中心位置。
show_at_center(region) None 滾動view到region區域的中心位置。
visible_region() Region 返回當前view可看見的區域。
viewport_position() Vector 返回可視區域在布局坐標中的偏移量。
set_viewport_position(vector, <animate<) None 把可視區域滾動到指定位置。
viewport_extent() vector 返回可視區域寬高。
layout_extent() vector 返回文檔layout的寬高。(譯者注:layout區域相當于編輯器里寫的代碼的范圍,到代碼字符的最后一行和最后一列區域,下同)
text_to_layout(point) vector 把文本位置轉換成layout位置。
layout_to_text(vector) point layout位置轉換成文本位置。
line_height() real 返回layout的行高。
em_width() real 范圍layout的字符寬度。
add_regions(key, [regions], scope, <icon>, <flags>) None 往view里添加這一組區域(region)。如果region已經存在,會被覆蓋。 scope參數決定region繪制的顏色,必須是scope名稱,比如 "comment" 或者 "string"。如果沒有scope參數,region不會被寫入。

icon參數,如果有的話,每個region前面會繪制icon標記。圖標的顏色跟scope參數有關。 icon名稱可以是:dotcircle,、bookmark,、cross。

可選參數flags可以是下列的組合:

  • sublime.DRAW_EMPTY. 用豎線繪制空白區域。默認根本不繪制。

  • sublime.HIDE_ON_MINIMAP. 在minimap不顯示這些區域。

  • sublime.DRAW_EMPTY_AS_OVERWRITE. 用橫線繪制空白區域。

  • sublime.DRAW_OUTLINED. 繪制區域輪廓而不是填充。

  • sublime.PERSISTENT. 保存區域到會話。

  • sublime.HIDDEN. 不繪制區域。

get_regions(key) [regions] 返回指定key的region。
erase_regions(key) None 移除指定key的region
set_status(key, value) None 往view里添加狀態。value值會被現實在狀態欄, 以key排序,每個狀態值逗號分隔。value為空字符串將清空改key對應的狀態值。
get_status(key) String 返回key對應的狀態值。
erase_status(key) None 清空key對一個的狀態值。
command_history(index, <modifying_only>) (String,Dict,int) 返回undo/redo棧中保存的,命令名稱,參數和重復次數。

Index 為0 對應最近的一次command, -1對應倒數第二次的命令,一次類推。index為正數代表redo 棧中德命令。如果undo / redo歷史記錄不足夠多返回(None, None, 0) 。

如果modifying_only為True (默認為False) 將只會返回修改了緩沖區的輸入。

fold([regions]) bool 折疊指定區域,如果已經折疊返回False。
fold(region) bool 同上。
unfold(region) [regions] 展開對應區域的所有文本,返回展開的區域。
unfold([regions]) [regions] 同上。
encoding() String 返回當前文件編碼。
set_encoding(encoding) None 設置文件編碼,文件下一次保存時生效。
line_endings() String 返回當前文件使用的換行符模式。(譯者注:windows系統下回返回"Windows")
set_line_endings(line_endings) None 設置文件的換行符模式,下一次保存時生效。

sublime.RegionSet類

維護一組區域,確保區域間沒有重疊。區域的按保存的順序持有。

方法 返回值 描述
clear() None 移除所有區域。
add(region) None 添加指定區域。如果已經存在與該region有交集的區域,會被合并。
add_all(region_set) None 添加region_set里的所有區域。
subtract(region) None 從所有region中移除指定區域。
contains(region) bool 如果所有區域中包含指定的region返回true。

sublime.Region類

代表了buffer中的一塊區域。空白區域可以相等(==)。

構造器 描述
Region(a, b) 創建一塊區域。
屬性 類型 描述
a int region區域的第一個結束位置。(譯者注:結束位置是相對于整個文檔的第一個開始字符而言。)
b int region區域的第二個結束位置。b可能會比a小,這樣的話就相當于一個反轉的區域。
方法 返回值 描述
begin() int 返回a,b中較小的值。
end() int 返回a,b中較大的值。
size() int 返回區域的字符總數。始終 >= 0。
empty() bool 如果begin()==end(),返回True。
cover(region) Region 返回一個跨越當前region和指定region的一個新的區域。
intersection(region) Region 返回當前region和指定region的交集。
intersects(region) bool 如果this==region或者當前region和指定region都包含了一個或多個同樣的位置。(譯者注:其實就是判斷指定的region和當前的region是否有交集)
contains(region) bool 如果指定的region是當前region的一個子集返回True。
contains(point) bool 如果begin() <= point <= end()返回True。(譯者注:point點在當前區域范圍內)。

sublime.Edit類

Edit對象沒有方法,它是用于對buffer的修改進行分組。

可以通過view.begin_edit()來創建。每一個begion_edit()調用都要對應一個view.end_edit()調用。通常會寫在try ... finally塊內。

方法 返回值 描述
(無方法)    

sublime.Window類

方法 返回值 描述
id() int 返回window的ID.
new_file() View 創建一個文件。返回一個空的view,view的is_loaded方法返回True。
open_file(file_name, <flags>) View 打開指定文件,并返回對應的view。如果文件已經被打開,會切換到當前當前視圖。注意,文件載入是異步的,view的is_loading() 方法返回False前不能對文件進行操作。

可選參數flags可以是下列的組合:

  • sublime.ENCODED_POSITION. 指定通過查找文件名后綴:row 或者 :row:col來定位打開文件后定位的位置

  • sublime.TRANSIENT. 只作預覽打開文件:在修改前不會有文件tab分配。

active_view() View 返回當前正在編輯的view。
active_view_in_group(group) View 返回指定組里正在編輯的view。
views() [View] 返回window中所有打開的view。
views_in_group(group) [View] 返回指定組里的所有view。
num_groups() int 返回window中打開的view分組的總數。
active_group() int 返回當前選中組的索引。
focus_group(group) None 激活指定分組。
focus_view(view) None 切換到指定view。
get_view_index(view) (group, index) 返回view的分組,和在分組里的索引。如果沒有返回-1。
set_view_index(view, group, index) None 把view移動到指定分組和指定的索引位置。
folders() [String] 返回當前打開的文件夾列表。(譯者注:sublime左側顯示的folders列表的每個跟目錄)。
run_command(string, <args>) None 運行WindowCommand,傳入指定參數。
show_quick_panel(items, on_done, <flags>) None 顯示一個選擇列表中某個選項的快速面板。 on_done會被調用一次,接受選中項的索引為參數。如果快速面板被取消,on_done調用的時候接收的參數為-1。

Items 可以是字符串數組,或者一個字符串數組的數組(二維字符串數組)。如果是后者,快速面板里的每個條目會顯示成多行。

Flags 只能有一個值: sublime.MONOSPACE_FONT

show_input_panel(caption, initial_text, on_done, on_change, on_cancel) View 顯示一個輸入面板,收集用戶的一行輸入。caption是輸入框的標題,on_done 和 on_change如果不為空的話需要是一個接受一個字符串的函。on_cancel 是一個無參數的函數。
get_output_panel(name) View 返回view對應的指定名稱的輸出面板,如果有必要會創建。output面板可以通過運行show_panel( window command)來顯示,panel 的名稱會加上 "output." 前綴。

sublime.Settings類

方法 返回值 描述
get(name) value 返回指定名稱的設置。
get(name, default) value 返回指定名稱的設置,如果沒有定義該設置返回默認的。
set(name, value) None 設置某個名稱的配置,只能接受原類型,列表, lists,字典。
erase(name) None 移除某個配置。如果是繼承自父配置不會被刪除。
has(name) bool 判斷當前配置類中是否存在某個配置或者父配置中是否存在。
add_on_change(key, on_change) None 注冊當前配置對象的change的回調。只有有一個配置發生變化都回被回調。.
clear_on_change(key) None 移除指定的change回調。

sublime_plugin模塊

方法 返回值 描述
(無方法)    

sublime_plugin.EventListener類

注意,有許多事件是view下的buffer緩沖區觸發的,而且這些方法只調用一次, view作為第一個參數。

方法 返回值 描述
on_new(view) None 當創建一個新的buffer時觸發。
on_clone(view) None 當從一個已存在的view復制一份時觸發。
on_load(view) None 當文件載入完成時觸發。
on_close(view) None 當view被關閉時觸發(注意,在同一buffer中可能還有其它view)。
on_pre_save(view) None 在一個view保存在觸發。
on_post_save(view) None 在一個view保存后觸發。
on_modified(view) None view被修改后觸發。
on_selection_modified(view) None view里的選區變化時觸發。
on_activated(view) None 一個view被激活時觸發。
on_deactivated(view) None 一個view被隱藏時觸發(被切換到后臺)。
on_query_context(view, key, operator, operand, match_all) bool or None 當使用給定的上下文key去觸發一個key綁定時觸發。如果插件知道如何處理上下文可以返回True 或者 False。如果上線問是未知的,應該返回None。

operator可取下列某個值:

  • sublime.OP_EQUAL. context等于operand

  • sublime.OP_NOT_EQUAL. context 不等于operand

  • sublime.OP_REGEX_MATCH. context匹配operand給定的正則

  • sublime.OP_NOT_REGEX_MATCH. context 不匹配operand給定的正則

  • sublime.OP_REGEX_CONTAINS. context包含可以匹配operand給定正則的子字符串

  • sublime.OP_NOT_REGEX_CONTAINS. context不包含可以匹配operand給定正則的子字符串

如果context涉及到選擇(selections)應該使用match_all:是否每個選擇都需要匹配(match_all = True), 還至少要一個選擇匹配 (match_all = Fals)。

sublime_plugin.ApplicationCommand類

方法 返回值 描述
run(<args>) None 當command運行時執行。
is_enabled(<args>) bool 如果command在當前時間可運行返回True。 默認實現都返回Flase。
is_visible(<args>) bool 如果command在當前可顯示在菜單。默認實現都返回False。
description(<args>) String 返回command的描述。在菜單中使用,如果沒有標題的情況下。返回None獲取默認描述。

sublime_plugin.WindowCommand類

WindowCommands 每個window只初始化一次。Window對象可以通過self.window來引用。

方法 返回值 描述
run(<args>) None command運行時調用。
is_enabled(<args>) bool 如果command在當前時間可運行返回True。 默認實現都返回Flase。
is_visible(<args>) bool 如果command在當前可顯示在菜單。默認實現都返回False。
description(<args>) String 返回command的描述。在菜單中使用,如果沒有標題的情況下。返回None獲取默認描述。

Class sublime_plugin.TextCommand

TextCommands每個view只初始化一次。可以通過self.view放訪問當前view。

方法 返回值 描述
run(edit, <args>) None command運行時調用。
is_enabled(<args>) bool 如果command在當前時間可運行返回True。 默認實現都返回Flase。
is_visible(<args>) bool 如果command在當前可顯示在菜單。默認實現都返回False。

 

微信掃一掃

第七城市微信公眾平臺
捕鱼达人小游戏