Sublime插件API手冊

望穿墻 2018-09-09

展開全文

轉(zhuǎn)： http://mux.alimama.com/posts/549

Sublime插件開發(fā)API手冊[中文版]

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

翻譯和理解水平有限，有不當(dāng)?shù)牡胤綒g迎指正,。部分方法描述里添加了些個人的注解,，希望有助于理解方法的使用。

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

閱讀全文

Sublime插件開發(fā)API手冊

基類

EventListener
ApplicationCommand
WindowCommand
TextCommand

插件示例

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

Packages/Default/delete_word.py 刪除光標(biāo)左邊或者右邊的一個單詞
Packages/Default/duplicate_line.py 復(fù)制當(dāng)前行
Packages/Default/goto_line.py 提示用戶輸入,，然后更新選擇點
Packages/Default/font.py 展示了如何使用settings
Packages/Default/mark.py 用了add_regions() 往行頭槽里插入圖標(biāo)
Packages/Default/trim_trailing_whitespace.py 保存前修改緩沖區(qū)

sublime模塊

方法	返回值	描述
set_timeout(callback, delay)	None	延時調(diào)用 (毫秒). 回調(diào)的順序會按添加的順序依次執(zhí)行. 多線程調(diào)用setTimeout也是安全的.
status_message(string)	None	設(shè)置狀態(tài)欄消息.
error_message(string)	None	顯示一個error對話框.
message_dialog(string)	None	顯示一個message對話框.
ok_cancel_dialog(string, <ok_button>)	bool	顯示一個"確認(rèn)/取消"的對話框,。如果有"確認(rèn)"按鈕，點擊確認(rèn)返回True.
load_settings(base_name)	Settings	載入一個配置,，name參數(shù)要包括文件名和后綴而不是路徑,。會根據(jù)base name搜索插件包，結(jié)果返回setting對象,。后續(xù)調(diào)用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	返回剪貼板的內(nèi)容。
set_clipboard(string)	None	設(shè)置剪貼板的內(nèi)容,。
score_selector(scope, selector)	Int	把選擇器設(shè)置成對應(yīng)的區(qū)域,，返回區(qū)域值。 0標(biāo)示沒有選區(qū),，大于0表示有一個選區(qū),。不同的選擇器可以通過scope來比較： scope值越高說明這段選區(qū)越適合這個選擇器.
run_command(string, <args>)	None	運行ApplicationCommand，string是command名字,，args是傳給command的參數(shù),。
log_commands(flag)	None	控制命令的日志。如果啟用,，所有command從快捷鍵,，菜單中執(zhí)行都回記錄到控制臺。
log_input(flag)	None	控制日志輸出,。如果啟用,，所有按鍵都回被記錄到控制臺。
version()	String	返回版本號,。
platform()	String	返回運行的平臺,。"osx", "linux" 或者 "windows"。
arch()	String	返回CPU架構(gòu),。64/32位,，"x32" or "x64"。

sublime.View類

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

方法	返回值	描述
id()	int	返回當(dāng)前view的唯一標(biāo)識ID,。
buffer_id()	int	返回當(dāng)前view下buffer標(biāo)識的唯一ID,。
file_name()	String	返回buffer關(guān)聯(lián)的完整文件名，如果沒有緩沖區(qū)存儲在磁盤的話返回None,。(buffer指緩沖區(qū),，下同)
name()	String	返回buffer指定的名稱。
set_name(name)	None	設(shè)置buffer的名稱,。
is_loading()	bool	如果buffer還在從磁盤載入返回ture,，表示還未準(zhǔn)備好給用戶使用。
is_dirty()	bool	返回是否有未保存到buffer的修改,。
is_read_only()	bool	返回true,，如果buffer不允許修改。
set_read_only(value)	None	設(shè)置緩沖區(qū)不可修改,。
is_scratch()	bool	如果緩沖區(qū)是臨時緩沖區(qū)返回True,。臨時緩沖區(qū)不會報告為dirty,。
set_scratch(value)	None	設(shè)置buffer為臨時緩沖區(qū)。
settings()	Settings	返回view的settings對象,。settings對象對當(dāng)前view是私有的,。
window()	Window	返回持有當(dāng)前view的window,。
run_command(string, <args>)	None	運行指定的TextCommand，args傳入?yún)?shù)。
size()	int	返回文件中字符總數(shù)量。
substr(region)	String	返回region選區(qū)內(nèi)容字符串。
substr(point)	String	返回point點的右側(cè)字符,。
begin_edit(<command>, <args>)	Edit	創(chuàng)建一個edit對象,，可以劃定一組撤銷操作,，需要對應(yīng)到 end_edit()標(biāo)記,。
end_edit(edit)	Edit	標(biāo)記完成一個edit對象,。（譯者注：begin_edit到end_edit之間的操作可以當(dāng)成一個命令分組,，可以用于撤銷操作,。）
insert(edit, point, string)	int	在緩沖區(qū)指定的點插入一個字符串。返回插入的字符數(shù)量,；如果插入當(dāng)前緩沖區(qū)的tabs返回有點區(qū)別,。
erase(edit, region)	None	從緩沖區(qū)移除region選區(qū)內(nèi)容。
replace(edit, region, string)	None	把region選區(qū)內(nèi)容替換成指定的字符串,。
sel()	RegionSet	返回selection(選擇)的引用,。
line(point)	Region	返回point點所在的行。
line(region)	Region	返回region區(qū)域行頭到行尾的一份拷貝,，從行頭到行尾可能跨了多行（譯者注：換行顯示的時候,，但是中間沒有換行符）,。
full_line(point)	Region	同 line(),，但是尾部有換行符的時候也包括了換行符,。
full_line(region)	Region	同 line(),，但是尾部有換行符的時候也包括了換行符
lines(region)	[Region]	返回region區(qū)域的所有行列表 (經(jīng)過排序) ,。
split_by_newlines(region)	[Region]	用換行符把整個region分割成多個region區(qū)域,，返回region列表。
word(point)	Region	返回包含point點的單詞,。
word(region)	Region	返回包含region區(qū)域的單詞區(qū)域（從第一個單詞的開頭,，到最后一個單詞的末尾）。有可能會跨多個單詞,。
find(pattern, fromPosition, <flags>)	Region	返回匹配的第一個區(qū)域,，從指定的點位置開始，沒有匹配結(jié)果返回None,。flags參數(shù)可以是 sublime.LITERAL, sublime.IGNORECASE, 或者2個"或運算",。
find_all(pattern, <flags>, <format>, <extractions>)	[Region]	返回所有(無重疊)的匹配區(qū)域結(jié)果。flags參數(shù)同上,，如果有format參數(shù),，所有匹配結(jié)果都會按指定格式被格式化并添加到extractions列表里,。
rowcol(point)	(int, int)	計算指定點從0開始的行位置和列位置。
text_point(row, col)	int	計算指定行,，列位置字符的偏移量,。"col"("列")是從一行的行頭開始的字符數(shù)量。
set_syntax_file(syntax_file)	None	指定語法文件,。view. `syntax_file文件應(yīng)該是按行來定義語法名稱,，基于Packages/Python/Python.tmLanguage。接受當(dāng)前語法可以使用view.settings().get('syntax'),。`
extract_scope(point)	Region	返回指定點位置字符語法名稱的范圍,。
scope_name(point)	String	返回指定點位置字符的語法名稱。
score_selector(point, selector)	Int	返回包含指定點位置的選擇器(selector)的數(shù)量(score),。score為0表示沒有匹配, 大于0表示一個匹配,，不同的選擇器可以通過scope來比較： scope值越高說明這段選區(qū)越適合這個選擇器。
find_by_selector(selector)	[Regions]	返回符合指定選擇器的所有區(qū)域,，結(jié)果為一個列表。
show(point, <show_surrounds>)	None	滾動view到指定的點,。
show(region, <show_surrounds>)	None	滾動view到指定的區(qū)域,。
show(region_set, <show_surrounds>)	None	滾動view到可以顯示指定的區(qū)域集。
show_at_center(point)	None	滾動到view的中心位置,。
show_at_center(region)	None	滾動view到region區(qū)域的中心位置,。
visible_region()	Region	返回當(dāng)前view可看見的區(qū)域。
viewport_position()	Vector	返回可視區(qū)域在布局坐標(biāo)中的偏移量,。
set_viewport_position(vector, <animate<)	None	把可視區(qū)域滾動到指定位置,。
viewport_extent()	vector	返回可視區(qū)域?qū)捀摺?/td>
layout_extent()	vector	返回文檔layout的寬高。(譯者注：layout區(qū)域相當(dāng)于編輯器里寫的代碼的范圍,，到代碼字符的最后一行和最后一列區(qū)域,，下同)
text_to_layout(point)	vector	把文本位置轉(zhuǎn)換成layout位置。
layout_to_text(vector)	point	layout位置轉(zhuǎn)換成文本位置,。
line_height()	real	返回layout的行高,。
em_width()	real	范圍layout的字符寬度。
add_regions(key, [regions], scope, <icon>, <flags>)	None	往view里添加這一組區(qū)域(region),。如果region已經(jīng)存在,，會被覆蓋。 scope參數(shù)決定region繪制的顏色,，必須是scope名稱,，比如 "comment" 或者 "string"。如果沒有scope參數(shù),，region不會被寫入,。 icon參數(shù),如果有的話,，每個region前面會繪制icon標(biāo)記。圖標(biāo)的顏色跟scope參數(shù)有關(guān),。 icon名稱可以是：`dot,、circle`,、`bookmark,,、cross,。` 可選參數(shù)flags可以是下列的組合： `sublime.DRAW_EMPTY`. 用豎線繪制空白區(qū)域。默認(rèn)根本不繪制,。 `sublime.HIDE_ON_MINIMAP`. 在minimap不顯示這些區(qū)域,。 `sublime.DRAW_EMPTY_AS_OVERWRITE`. 用橫線繪制空白區(qū)域。 `sublime.DRAW_OUTLINED`. 繪制區(qū)域輪廓而不是填充,。 `sublime.PERSISTENT`. 保存區(qū)域到會話,。 `sublime.HIDDEN`. 不繪制區(qū)域。
get_regions(key)	[regions]	返回指定key的region,。
erase_regions(key)	None	移除指定key的region
set_status(key, value)	None	往view里添加狀態(tài),。value值會被現(xiàn)實在狀態(tài)欄，以key排序,，每個狀態(tài)值逗號分隔,。value為空字符串將清空改key對應(yīng)的狀態(tài)值。
get_status(key)	String	返回key對應(yīng)的狀態(tài)值,。
erase_status(key)	None	清空key對一個的狀態(tài)值,。
command_history(index, <modifying_only>)	(String,Dict,int)	返回undo/redo棧中保存的，命令名稱,，參數(shù)和重復(fù)次數(shù),。 Index 為0 對應(yīng)最近的一次command， -1對應(yīng)倒數(shù)第二次的命令,，一次類推,。index為正數(shù)代表redo 棧中德命令。如果undo / redo歷史記錄不足夠多返回(None, None, 0) ,。如果modifying_only為True (默認(rèn)為False) 將只會返回修改了緩沖區(qū)的輸入,。
fold([regions])	bool	折疊指定區(qū)域，如果已經(jīng)折疊返回False,。
fold(region)	bool	同上,。
unfold(region)	[regions]	展開對應(yīng)區(qū)域的所有文本，返回展開的區(qū)域,。
unfold([regions])	[regions]	同上,。
encoding()	String	返回當(dāng)前文件編碼。
set_encoding(encoding)	None	設(shè)置文件編碼,，文件下一次保存時生效,。
line_endings()	String	返回當(dāng)前文件使用的換行符模式,。（譯者注：windows系統(tǒng)下回返回"Windows"）
set_line_endings(line_endings)	None	設(shè)置文件的換行符模式，下一次保存時生效,。

sublime.RegionSet類

維護(hù)一組區(qū)域,，確保區(qū)域間沒有重疊。區(qū)域的按保存的順序持有,。

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

sublime.Region類

代表了buffer中的一塊區(qū)域?？瞻讌^(qū)域可以相等(==),。

構(gòu)造器	描述
Region(a, b)	創(chuàng)建一塊區(qū)域。

屬性	類型	描述
a	int	region區(qū)域的第一個結(jié)束位置,。（譯者注：結(jié)束位置是相對于整個文檔的第一個開始字符而言,。）
b	int	region區(qū)域的第二個結(jié)束位置。b可能會比a小,，這樣的話就相當(dāng)于一個反轉(zhuǎn)的區(qū)域。

方法	返回值	描述
begin()	int	返回a,b中較小的值,。
end()	int	返回a,b中較大的值,。
size()	int	返回區(qū)域的字符總數(shù)。始終 >= 0,。
empty()	bool	如果begin()==end(),，返回True。
cover(region)	Region	返回一個跨越當(dāng)前region和指定region的一個新的區(qū)域,。
intersection(region)	Region	返回當(dāng)前region和指定region的交集,。
intersects(region)	bool	如果this==region或者當(dāng)前region和指定region都包含了一個或多個同樣的位置。（譯者注：其實就是判斷指定的region和當(dāng)前的region是否有交集）
contains(region)	bool	如果指定的region是當(dāng)前region的一個子集返回True,。
contains(point)	bool	如果begin() <= point <= end()返回True,。（譯者注：point點在當(dāng)前區(qū)域范圍內(nèi)）。

sublime.Edit類

Edit對象沒有方法,，它是用于對buffer的修改進(jìn)行分組,。

可以通過view.begin_edit()來創(chuàng)建。每一個begion_edit()調(diào)用都要對應(yīng)一個view.end_edit()調(diào)用,。通常會寫在try ... finally塊內(nèi),。

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

sublime.Window類

方法	返回值	描述
id()	int	返回window的ID.
new_file()	View	創(chuàng)建一個文件,。返回一個空的view，view的is_loaded方法返回True,。
open_file(file_name, <flags>)	View	打開指定文件,，并返回對應(yīng)的view。如果文件已經(jīng)被打開,，會切換到當(dāng)前當(dāng)前視圖,。注意，文件載入是異步的,，view的is_loading() 方法返回False前不能對文件進(jìn)行操作,。可選參數(shù)flags可以是下列的組合： `sublime.ENCODED_POSITION`. 指定通過查找文件名后綴`:row` 或者 `:row:col來定位打開文件后定位的位置`。 `sublime.TRANSIENT`. 只作預(yù)覽打開文件：在修改前不會有文件tab分配,。
active_view()	View	返回當(dāng)前正在編輯的view,。
active_view_in_group(group)	View	返回指定組里正在編輯的view。
views()	[View]	返回window中所有打開的view,。
views_in_group(group)	[View]	返回指定組里的所有view,。
num_groups()	int	返回window中打開的view分組的總數(shù)。
active_group()	int	返回當(dāng)前選中組的索引,。
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]	返回當(dāng)前打開的文件夾列表,。（譯者注：sublime左側(cè)顯示的folders列表的每個跟目錄）。
run_command(string, <args>)	None	運行WindowCommand,，傳入指定參數(shù),。
show_quick_panel(items, on_done, <flags>)	None	顯示一個選擇列表中某個選項的快速面板。 on_done會被調(diào)用一次,，接受選中項的索引為參數(shù),。如果快速面板被取消，on_done調(diào)用的時候接收的參數(shù)為-1,。 Items 可以是字符串?dāng)?shù)組,，或者一個字符串?dāng)?shù)組的數(shù)組(二維字符串?dāng)?shù)組)。如果是后者,，快速面板里的每個條目會顯示成多行,。 Flags 只能有一個值： `sublime.MONOSPACE_FONT`
show_input_panel(caption, initial_text, on_done, on_change, on_cancel)	View	顯示一個輸入面板，收集用戶的一行輸入,。caption是輸入框的標(biāo)題,，on_done 和 on_change如果不為空的話需要是一個接受一個字符串的函,。on_cancel 是一個無參數(shù)的函數(shù)。
get_output_panel(name)	View	返回view對應(yīng)的指定名稱的輸出面板,，如果有必要會創(chuàng)建,。output面板可以通過運行`show_panel(` window command)來顯示，`panel` 的名稱會加上 "output." 前綴,。

sublime.Settings類

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

sublime_plugin模塊

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

sublime_plugin.EventListener類

注意,，有許多事件是view下的buffer緩沖區(qū)觸發(fā)的,，而且這些方法只調(diào)用一次， view作為第一個參數(shù),。

方法	返回值	描述
on_new(view)	None	當(dāng)創(chuàng)建一個新的buffer時觸發(fā),。
on_clone(view)	None	當(dāng)從一個已存在的view復(fù)制一份時觸發(fā)。
on_load(view)	None	當(dāng)文件載入完成時觸發(fā),。
on_close(view)	None	當(dāng)view被關(guān)閉時觸發(fā)(注意，在同一buffer中可能還有其它view),。
on_pre_save(view)	None	在一個view保存前觸發(fā),。
on_post_save(view)	None	在一個view保存后觸發(fā)。
on_modified(view)	None	view被修改后觸發(fā),。
on_selection_modified(view)	None	view里的選區(qū)變化時觸發(fā),。
on_activated(view)	None	一個view被激活時觸發(fā)。
on_deactivated(view)	None	一個view被隱藏時觸發(fā)（被切換到后臺）,。
on_query_context(view, key, operator, operand, match_all)	bool or None	當(dāng)使用給定的上下文key去觸發(fā)一個key綁定時觸發(fā),。如果插件知道如何處理上下文可以返回True 或者 False。如果上線問是未知的,，應(yīng)該返回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)應(yīng)該使用match_all：是否每個選擇都需要匹配`(match_all = True), 還至少要一個選擇匹配 (match_all = Fals),。

sublime_plugin.ApplicationCommand類

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

sublime_plugin.WindowCommand類

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

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

Class sublime_plugin.TextCommand

TextCommands每個view只初始化一次,。可以通過self.view放訪問當(dāng)前view,。

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

本站是提供個人知識管理的網(wǎng)絡(luò)存儲空間,，所有內(nèi)容均由用戶發(fā)布，不代表本站觀點,。請注意甄別內(nèi)容中的聯(lián)系方式,、誘導(dǎo)購買等信息，謹(jǐn)防詐騙。如發(fā)現(xiàn)有害或侵權(quán)內(nèi)容,，請點擊一鍵舉報,。

轉(zhuǎn)藏 分享

QQ空間 QQ好友新浪微博微信

獻(xiàn)花（0） +1

來自：望穿墻 > 《sublime》

舉報/認(rèn)領(lǐng)