代碼片段建立

建立

通常，「代碼片段模板」.snippet 檔案需要直接返回一個表，如：

return {
    name = '测试片段';  -- 代碼片段名稱
    description = '用于测试各选择器的功能';  -- 代碼片段描述
    arguments = {  -- 代碼片段選擇器列表
        {  -- 選擇器 1
            type = 'app',  -- 選擇器類型
            title = '选择应用',  -- 選擇器標題
            subtitle = '请选择一个应用',  -- 選擇器副標題
            default = 'com.xxtouch.XXTExplorer',  -- 選擇器默認值
        },
        {  -- 選擇器 2
            type = 'loc',
            title = '选择地理位置',
            subtitle = '请随便选择一个地理位置',
            default = xui.get("com.darwindev.XXTExplorer", "location1"),
            -- 代碼片段 .snippet 中可以使用 .xui 支持的所有 API
        },
        {  -- 選擇器 3

        },
        -- ...
    };
    generator = function (...)  -- 可變參數生成器
        -- 處理參數並返回生成的結果
        local result
        return result
    end;
}

根層級

鍵	類型	描述
name	字串	代碼片段名稱
description	字串	代碼片段描述
arguments	陣列	代碼片段選擇器清單
generator	函式	代碼片段生成器
output	字串	代碼片段獨立輸出檔名

name 和 description 分別為代碼片段模板的顯示名稱與顯示描述，會顯示在檔案管理器、代碼片段的入口處。

arguments 為包含了一個或多個 選擇器參數字典 的陣列。App 將根據該陣列中約定的選擇器順序，建立出一個選擇器隊列，依次讓使用者進行選擇操作。使用者完成選擇器隊列後，App 會將各選擇器的回傳值作為可變傳入參數，依次傳入生成器 generator 並呼叫它，最後將 generator 的回傳值返回給呼叫方。

代碼片段模板 .snippet 是可以獨立使用的。如果需要允許它獨立使用，可為其設定 output 字段，generator 生成的結果文字將儲存到同一目錄下 output 所標識的檔案中。

選擇器參數字典

鍵	類型	描述
type	字串	選擇器類型
title	字串	選擇器標題，顯示在選擇器頁面下方
subtitle	字串	選擇器副標題，顯示在選擇器頁面下方
default	基本類型	選擇器預設值

有關各類型選擇器 選擇器參數字典 的詳細介紹，參見後文內容。

在 XUI 中使用

如果代碼片段模板 .snippet 在 XUI 的 TitleValue 元件中使用，即可從 XUI 中喚起選擇器隊列，並將結果儲存到 XUI 元件的設定項中。同時該 .snippet 可呼叫 XUI 支援的所有 API，如 xui.get/xui.set/xpp.bundle_path 等。

在代碼編輯器中使用

將代碼片段模板 .snippet 放置到主目錄的 snippets 目錄中，即可被 App 的代碼編輯器所呼叫。輕按鍵盤工具類右上角的星形按鈕，即可快速生成代碼片段，並插入到編輯的代碼中。

作為獨立檔案使用

為代碼片段模板 .snippet 設定 output 字段，並將代碼片段放置在主目錄的 lua/scripts 目錄中，即可從 App 中直接點選，開始選擇器隊列，generator 生成的結果文字將儲存到同一目錄下 output 所標識的檔案中。