Sublime插件開發API手冊

Sublime插件開發API手冊[中文版]

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

翻譯和理解水平有限，有不當的地方歡迎指正。部分方法描述裏添加了些我的的註解，但願有助於理解方法的使用。

後期若是有更多實踐經驗的話再回過頭來修正可能解釋有誤的地方，或加些註解。

 

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名稱能夠是：dot、circle,、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。
description(args)	String	返回command的描述。在菜單中使用，若是沒有標題的狀況下。返回None獲取默認描述。