Openwrt LuCI之CBI控件

一、CBI控件類型匯總

• CBI模型是描述UCI配置文件結構的Lua文件，並且CBI解析器將lua文件轉為HTML呈現給用戶 。
• 所有 CBI 模型文件必須返回類型為 luci.cbi.Map 的對象。
• CBI 模型文件的范圍由 luci.cbi 模塊的內容和 luci.i18n 的轉換函數自動擴展。

名稱	描述	繼承自	模板
NamedSection	A fixed configuration section defined by its name	NamedSection = class(AbstractSection)	cbi/nsection
TypedSection	A (set of) configuration section(s) defined by the type	TypedSection = class(AbstractSection)	cbi/tsection
Node	Node pseudo abstract class	Node = class()	cbi/node
Template	A simple template element	Template = class(Node)
Map	A map describing a configuration file	Map = class(Node)	cbi/map
Compound	Container	Compound = class(Node)	cbi/compound
Delegator	Node controller	Delegator = class(Node)	cbi/delegator
SimpleForm	A Simple non-UCI form	SimpleForm = class(Node)	cbi/simpleform
Form		Form = class(SimpleForm)
AbstractSection		AbstractSection = class(Node)
SimpleSection		SimpleSection = class(AbstractSection)	cbi/nullsection
Table		Table = class(AbstractSection)	cbi/tblsection
AbstractValue	An abstract Value Type	AbstractValue = class(Node)
Value	A one-line value	Value = class(AbstractValue)	cbi/value
DummyValue	This does nothing except being there	DummyValue = class(AbstractValue)	cbi/dvalue
Flag	A flag being enabled or disabled	Flag = class(AbstractValue)	cbi/fvalue
ListValue	A one-line value predefined in a list	ListValue = class(AbstractValue)	cbi/lvalue
MultiValue	Multiple delimited values	MultiValue = class(AbstractValue)	cbi/mvalue
StaticList		StaticList = class(MultiValue)
DynamicList		DynamicList = class(AbstractValue)	cbi/dynlist
TextValue	A multi-line value	TextValue = class(AbstractValue)	cbi/tvalue
Button		Button = class(AbstractValue)	cbi/button
FileUpload		FileUpload = class(AbstractValue)	cbi/upload
FileBrowser		FileBrowser = class(AbstractValue)	cbi/browser
Page	A simple node	Page = class(Node)

二、CBI常用控件用法詳解

1、class Map (config, title, description)

參數說明：

• config: /etc/config/目錄下的UCI文件名
• title: 頁面顯示名稱
• description: 頁面顯示詳細描述

方法說明：

• function :section(sectionclass, …)

補充說明：

section(TypedSection, type, title, description)
section(NamedSection, name, type, title, description)

section 對象有一些屬性如下：

• template： html 模板， 默認為"cbi/tsection"
• addremove： 是否可以增加和刪除， 默認為 false
• anonymous： 是否為匿名 section， 默認為 false

網頁圖例：

2、class NamedSection(name, type, title, description)

• An object describing an UCI section selected by the name. //根據name來解析一個UCI section
• To instantiate use: Map:section(NamedSection, "name", "type", "title", "description")

參數說明：

• name: UCI section名字, config type section
• type: UCI section類型, config type section
• title: 頁面顯示名稱
• description: 頁面顯示詳細描述

對象屬性：

• property.addremove = false

Allows the user to remove and recreate the configuration section. //允許用戶刪除並重新創建配置section。

• property.anonymous = true

true 頁面不顯示section名字
false 頁面顯示section名字

• property.dynamic = false

ture 將section 標記為動態
Dynamic sections can contain an undefinded number of completely userdefined options. //將此部分標記為動態。動態section可以包含未找到的完全用戶定義的選項數。

• property.optional = true

解析可選的options

3、class TypedSection (type, title, description)

• An object describing a group of UCI sections selected by their type. // 通過類型type選擇來描述一組 UCI section的對象。
• To instantiate use: Map:section(TypedSection, "type", "title", "description")

參數說明：

• type: UCI section類型, config type section
• title: 頁面顯示名稱
• description: 頁面顯示詳細描述

對象屬性:

• property.addremove = false

此section是否允許刪除或創建
為true時，頁面會顯示刪除和創建按鈕

• property.anonymous = true

頁面不顯示此secion名字

• property.template = "cbi/template"

設置此section頁面模板

方法說明:

• function :depends(key, value)

僅當另一個選項鍵在同一section中設置為值時，才顯示此選項字段。如果多次調用此函數，則依賴項將鏈接為 [或]

• function .filter(self, section) -abstract-

您可以重寫此函數以篩選某些不會解析的部分。對於應分析的每個section，將調用篩選器函數，對於應篩選的section，將返回 nil。對於所有其他section，它應返回第二個參數中給出的section名稱。

• function :option(optionclass, …)

4、class Value (option, title, description)

• An object describing an option in a section of a UCI File. Creates a standard text field in the formular.//描述 UCI 文件部分中的選項的對象。在公式中創建標准文本框。(單行文本框)
• To instantiate use: NamedSection:option(Value, "option", "title", "description") or TypedSection:option(Value, "option", "title", "description")

參數說明：

• option: UCI option name
• title: 頁面顯示名稱
• description: 頁面顯示詳細描述

對象屬性：

• property .default = nil 文本框中缺省的值
• property .maxlength = nil

The maximum input length (of chars) of the value //值的最大輸入長度（字符）

• property .optional = false

Marks this option as optional, implies .rmempty = true //將此選項標記為可選， .rmempty = true

• property .rmempty = true

Removes this option from the configuration file when the user enters an empty value //當用戶輸入空值時，從配置文件中刪除此選項

• property .size = nil

The maximum number of chars displayed by form field //窗體字段顯示的最大字符數

• property .password = false

密碼輸入框

方法說明：

• function :depends(key, value)
• function :value(key, value)

Convert this text field into a combobox if possible and add a selection option. //如果可能，將此文本字段轉換為組合框，並添加選擇選項。

圖片示例：

5、class ListValue (option, title, description)

• An object describing an option in a section of a UCI File.Creates a list box or list of radio (for selecting one of many choices) in the formular. //描述 UCI File 部分中選項的對象。在公式中創建一個列表框或單選列表（用於選擇多種選項之一）（即下拉列表）。
• To instantiate use: NamedSection:option(ListValue, "option", "title", "description") or TypedSection:option(ListValue, "option", "title", "description")

參數說明:

• option: UCI option name
• title: 頁面顯示名稱
• description: 頁面顯示詳細描述

屬性說明：

• property .widget = "select"

select shows a selection list, radio shows a list of radio buttons inside form。 //select 顯示選擇列表，radio 顯示表單內單選按鈕的列表

• property .default = nil

The default value 文本框中缺省的值

• property .optional = false
• property .rmempty = true
• property .size = nil

方法說明：

• function :value(key, value)

Adds an entry to the selection list

網頁圖例：

6、class Flag (option, title, description)

• An object describing an option with two possible values in a section of a UCI File. Creates a checkbox field in the formular. //描述在 UCI 文件部分中具有兩個可能值的選項的對象。在公式中創建復選框。
• To instantiate use: NamedSection:option(Flag, "option", "title", "description") or TypedSection:option(Flag, "option", "title", "description")

參數說明：

• option: UCI option name
• title: 頁面顯示名稱
• description: 頁面顯示詳細描述

對象屬性：

• property .default = nil The default value
• property .disabled = 0

the value that should be set if the checkbox is unchecked //取消選中復選框時 應設置的值

• property .enabled = 1

the value that should be set if the checkbox is checked //選中復選框時 應設置的值

方法說明：

• function :depends (key, value)

網頁圖例：

7、class MultiValue (option, title, description)

• An object describing an option in a section of a UCI File.Creates a list of checkboxed or a multiselectable list as form fields. //描述 UCI 文件部分中的選項的對象。創建復選框列表或多選列表（非下拉列表）。
• To instantiate use: NamedSection:option(MultiValue, “option”, “title”, “description”) or TypedSection:option(MultiValue, “option”, “title”, “description”)

參數說明：

對象屬性：

• property .widget = “checkbox”

select shows a selection list, checkbox shows a list of checkboxes inside form //選中顯示選擇列表，復選框顯示表單內的復選框列表

• property .delimiter = " "

The string which will be used to delimit the values inside stored option //用於分隔存儲選項內的值的字符串

• property .default = nil
• property .optional = false
• property .rmempty = true
• property .size = nil

The size of the form field (only used if property .widget = “select”) //窗體字段的大小（僅當屬性 .widget = "select"時才使用）

方法說明：

• function :depends (key, value)
• function :value(key, value)

Adds an entry to the list

網頁圖例：

8、class StaticList (option, title, description)

• Similar to the MultiValue, but stores selected Values into a UCI list instead of a character-separated option. //與MultiValue類似，但將所選值存儲到 UCI list中，而不是字符分隔option中。
• (這里可能會有疑問，請看下面操作，當在網頁對StaticList和MultiValue 選中四個選項時，保存並應用，查看UCI 中配置文件就可以明白。MultiValue 對應的值存儲在option,而StaticList對應的值分別存儲在list中)

網頁圖例：

9、class DynamicList (option, title, description)

• A extensible list of user-defined values. Stores Values into a UCI list //用戶定義值的可擴展列表。將值存儲到 UCI list中

網頁圖例：

10、class DummyValue (option, title, description)

• Creates a readonly text in the form. It writes no data to UCI!//在窗體中創建只讀文本。它不寫入任何數據到UCI！
• To instantiate use: NamedSection:option(DummyValue, "option", "title", "description") or TypedSection:option(DummyValue, "option", "title", "description")

參數說明：

• option: UCI option name
• title: 頁面顯示名稱
• description: 頁面顯示詳細描述

方法說明：

• function :depends (key, value)

網頁說明：

11、class TextValue (option, title, description)

• An object describing a multi-line textbox in a section in a non-UCI form.// 描述非 UCI 窗體中節中多行文本框的對象。
• 注：與Value的區別就是TextValue可以多行顯示，而Value只能單行顯示。

網頁圖例：

12、class Button (option, title, description)

• An object describing a Button in a section in a non-UCI form.//描述非 UCI 窗體中節中的按鈕的對象。

屬性說明：

同Value。.inputstyle = nil 按鈕樣式 apply, reset

方法說明：

同Value

網頁圖例：

13、class tab(tabname, title)

• 調用 section 的 tab 函數創建一個名稱為 tabname，標題為 title 的 Tab 標簽。
• 對應的 option 則使用 taboption
  s:taboption(tabname, type, name, title)
  在指定的 tabname 下創建一個 option。
• s為section 對象，與之前的控件不同，一個section里面如果有tab控件，會將其他（如Value）控件覆蓋掉，所以，要想創建tab選項，必須另外再創建section。

b = m:section(TypedSection, "typedsection2_title", "typedsection2 description")
b:tab("tab1", "Tab1");
b:tab("tab2", "Tab2");
b1=b:taboption("tab1", Value, "tab1_option1", "tab1 Option1");
b2=b:taboption("tab2", Value, "tab2_option2", "tab2 Option2");

網頁圖例：

三、實例操作

1、示例

（1）網頁整體圖例

（2） lua 文件中CBI控件代碼

m = Map("test_file","map title" ,translate("map descrption")) -- cbi_file is the config file in /etc/config

a = m:section(TypedSection, "typedsection1_title", "typedsection1 description")  -- info is the section called info in cbi_file

a1 = a:option(Value, "Value_option_name","Value option title", translate("Value option description"));

a2 = a:option(TextValue, "TextValue_option_name","TextValue option title", "TextValue option description");

a3 = a:option(MultiValue , "MultiValue_option_name","MultiValue  option title", "MultiValue  option description");
a3:value("0", translate("value0"));
a3:value("1", translate("value1"));
a3:value("2", translate("value2"));
a3:value("3", translate("value3"));

a4 = a:option(DummyValue , "DummyValue_option_name","DummyValue option title", "DummyValue option description");

a5 = a:option(ListValue, "Listvalue_option_name","ListValue option title", "ListValue option description");
a5:value("0", translate("value0"));
a5:value("1", translate("value1"));
a5:value("2", translate("value2"));
a5:value("3", translate("value3"));

a6 = a:option(DynamicList, "DynamicList_option_name","Dynamiclist option title", "DynamicList option description");

a7 = a:option(StaticList, "StaticList_option_name","StaticList option title", "StaticList option description");
a7:value("0", translate("value0"));
a7:value("1", translate("value1"));
a7:value("2", translate("value2"));
a7:value("3", translate("value3"));

a8 = a:option(Flag, "Flag_option_name","Flag option title", "Flag option description");

a9 = a:option(Button, "Button_option_name","Button option title", "Button option description");
 
b = m:section(TypedSection, "typedsection2_title", "typedsection2 description")
b:tab("tab1", "Tab1");
b:tab("tab2", "Tab2");
b1=b:taboption("tab1", Value, "tab1_option1", "tab1 Option1");
b2=b:taboption("tab2", Value, "tab2_option2", "tab2 Option2");

return m	

（3）UCI 文件中配置信息

config typedsection1_title 'typedsection1'
        option Value_option_name 'Value'
        option TextValue_option_name 'TextValue'
        option DummyValue_option_name 'DummyValue'
        option Listvalue_option_name '1'
        list DynamicList_option_name 'DynamicList'
        list DynamicList_option_name '123123'
        option Flag_option_name '1'
        option MultiValue_option_name '0 1 2 3'
        list StaticList_option_name '0'
        list StaticList_option_name '1'
        list StaticList_option_name '2'
        list StaticList_option_name '3'

config typedsection2_title 'typedsection2'
        option tab1_option1 '1'
        option tab2_option2 '2'

2、網上實例參考

例程詳情參考 https://github.com/openwrt/luci/wiki/ModulesHowTo

m = Map("network", "Network") -- We want to edit the uci config file /etc/config/network 
s = m:section(TypedSection, "interface", "Interfaces") -- Especially the "interface"-sections
s.addremove = true -- Allow the user to create and remove the interfaces
function s:filter(value)  
     return value ~= "loopback" and value -- Don't touch loopback
end s:depends("proto", "static") -- Only show thosewith"static"
s:depends("proto", "dhcp") -- or "dhcp" as protocol and leave PPPoE and PPTP alone 

p = s:option(ListValue, "proto", "Protocol") -- Creates an element list (select box)
p:value("static", "static") -- Key and value pairs
p:value("dhcp", "DHCP")
p.default = "static" 

s:option(Value, "ifname", "interface", "the physical interface to be used") -- This will give a simple textbox 

s:option(Value, "ipaddr", translate("IP Address")) -- Ja, das ist eine i18n-Funktion ;-) 

s:option(Value, "netmask", "Netmask"):depends("proto", "static") -- You may remember this "depends" function from above 

mtu = s:option(Value, "mtu", "MTU")
mtu.optional = true -- This one is very optional 
dns = s:option(Value, "dns", "DNS-Server")
dns:depends("proto", "static")
dns.optional = true
function dns:validate(value) -- Now, that's nifty, eh?
    return value:match("[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+") -- Returns nil if it doesn't match otherwise returns match
end 

gw = s:option(Value, "gateway", "Gateway")
gw:depends("proto", "static")
gw.rmempty = true -- Remove entry if it is empty 

return m -- Returns the map

四、結尾

1、總結

2、資料參考

文檔參考：https://github.com/openwrt/luci/wiki/CBI
博客參考：https://blog.csdn.net/qq_21949217/article/details/44340261