[作者:David Lambauer]{class="badge informative" title="David Lambauer"}
system.xml參考
system.xml
檔案可讓您管理Commerce系統組態。 使用此主題做為system.xml
檔案的一般參考。 system.xml
檔案位於指定Commerce 2擴充功能中的etc/adminhtml/system.xml
下。
下列程式碼片段顯示檔案的裸骨架:
<?xml version="1.0" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
<system>
<!-- PLACE YOUR MODULE SPECIFIC CONFIGURATION HERE -->
</system>
</config>
bin/magento dev:urn-catalog:generate [--ide IDE] [--] <path>
。索引標籤//區段//群組//欄位
在system.xml
檔案中,可以定義四個彼此相關的不同實體型別。 下節說明標籤、區段、群組和欄位之間的關係。 以下熒幕擷圖顯示管理員後端中的Commerce 2系統設定。
紅色方塊會標籤在system.xml
檔案中定義的不同型別:
標籤可用來以語義方式分割不同的組態區域。 每個標籤可以包含一或多個區段,這些區段也可以作為子選單參照。 區段包含一或多個群組。
每個群組會列出一或多個欄位。 您也可以使用群組來新增下列欄位的一般說明。 如前所述,每個群組可以有一或多個欄位。 欄位是最小的實體
在系統組態內容中。
索引標籤
<tab>
— 標籤參照到系統組態中的現有或新索引標籤。
索引標籤屬性參考
<tab>
— 標籤可以有下列屬性:
id
typeId
translate
label
讓標籤可翻譯。string
sortOrder
float
class
string
索引標籤節點參考
<tab>
標籤可以有下列子系:
label
string
範例:建立標籤
下列程式碼片段示範如何使用範例資料建立新標籤。
<?xml version="1.0" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
<system>
<tab id="A_UNIQUE_ID" translate="label" class="a-custom-css-class-to-style-this-tab" sortOrder="10">
<label>A meaningful label</label>
</tab>
</system>
</config>
上述程式碼片段會建立識別碼為A_UNIQUE_ID
的新標籤。 由於translate
— 屬性已定義並參考標籤,因此label
— 節點是可轉譯的。 在轉譯程式期間,CSS類別a-custom-css-class-to-style-this-tab
將套用至為此索引標籤建立的HTML專案。
值為10
的sortOrder
屬性定義轉譯時索引標籤在所有索引標籤清單中的位置。
部分
<section>
-Tag參照到系統組態中的現有或新區段。
區段屬性參考
<section>
— 標籤可以有下列屬性:
id
typeId
translate
label
讓標籤可翻譯。string
type
text
。string
sortOrder
float
showInDefault
1
以顯示區段,指定0
隱藏區段。int
showInStore
1
以顯示區段,指定0
隱藏區段。int
showInWebsite
1
以顯示區段,指定0
隱藏區段。int
canRestore
int
advanced
bool
extends
string
區段節點參考
<section>
— 標籤可以有下列子系:
label
string
class
string
tab
typeTabId
header_css
string
resource
typeAclResourceId
group
typeGroup
frontend_model
typeModel
include
system_include.xsd
個相容的檔案。 通常用於建構大型system.xml
檔案。includeType
範例:建立區段並將其指派給標籤
下列程式碼片段示範建立新區段的基本用法。
<?xml version="1.0" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
<system>
<tab id="A_UNIQUE_ID" translate="label" class="a-custom-css-class-to-style-this-tab" sortOrder="10">
<label>A meaningful label</label>
</tab>
<section id="A_UNIQUE_SECTION_ID" showInDefault="1" showInWebsite="0" showInStore="1" sortOrder="10" translate="label">
<label>A meaningful section label</label>
<tab>A_UNIQUE_ID</tab>
<resource>VENDOR_MODULE::path_to_the_acl_resource</resource>
</section>
</system>
</config>
上述章節定義識別碼A_UNIQUE_SECTION_ID
,在預設設定檢視和存放區內容中可見。 label
節點是可翻譯的。 區段與ID為A_UNIQUE_ID
的索引標籤相關聯。 只有在ACL VENDOR_MODULE::path_to_the_acl_resource
中定義許可權的使用者才能存取區段。
群組
<group>
— 標籤用於將欄位分組在一起。
群組屬性參考
<group>
— 標籤可以有下列屬性:
id
typeId
translate
label
讓標籤可翻譯。 多個欄位應以空格分隔。string
type
text
。string
sortOrder
float
showInDefault
1
以顯示群組,指定0
隱藏群組。int
showInStore
1
以顯示群組,指定0
隱藏群組。int
showInWebsite
1
以顯示群組,指定0
隱藏群組。int
canRestore
int
advanced
bool
extends
string
群組節點參考
<group>
— 標籤可以有下列子系:
label
string
fieldset_css
string
frontend_model
typeModel
clone_model
typeModel
clone_fields
int
help_url
typeUrl
more_url
typeUrl
demo_link
typeUrl
comment
<![CDATA[//]]>
可套用HTML。string
hide_in_single_store_mode
1
隱藏群組;0
顯示群組。int
field
field
group
unbounded
depends
1
時,才會用來顯示特定欄位/群組。 此節點需要section/group/field
字串。depends
attribute
attribute
include
system_include.xsd
個相容的檔案。 通常用於建構大型system.xml
檔案。includeType
more_url
、demo_url
和help_url
是由只使用一次的PayPal前端模型所定義。 這些節點無法重複使用。範例:為指定區段建立群組
下列程式碼片段示範建立新群組的基本用法。
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
<system>
<tab id="A_UNIQUE_ID" translate="label" class="a-custom-css-class-to-style-this-tab" sortOrder="10">
<label>A meaningful label</label>
</tab>
<section id="A_UNIQUE_SECTION_ID" showInDefault="1" showInWebsite="0" showInStore="1" sortOrder="10" translate="label">
<label>A meaningful section label</label>
<tab>A_UNIQUE_ID</tab>
<resource>VENDOR_MODULE::path_to_the_acl_resource</resource>
<group id="A_UNIQUE_GROUP_ID" translate="label comment" sortOrder="10" showInDefault="1" showInWebsite="0" showInStore="1">
<label>A meaningful group label</label>
<comment>An additional comment helping users to understand the effect when configuring the fields defined in this group.</comment>
<!-- Add your fields here. -->
</group>
</section>
</system>
</config>
上述群組定義識別碼A_UNIQUE_GROUP_ID
,可在預設設定檢視和存放區內容中看到。 label
和comment
都標示為可翻譯。
欄位
<field>
— 標籤用在<group>
— 標籤內部,以定義特定的設定值。
欄位屬性參考
<field>
— 標籤可以有下列屬性:
id
typeId
translate
label
讓標籤可翻譯。 多個欄位應以空格分隔。string
type
text
。string
sortOrder
float
showInDefault
1
以顯示欄位,指定0
隱藏欄位。int
showInStore
1
以顯示欄位,指定0
隱藏欄位。int
showInWebsite
1
以顯示欄位,指定0
隱藏欄位。int
canRestore
int
advanced
bool
extends
string
欄位型別參考
<field>
— 標籤的type=""
屬性可以有下列值:
text
textarea
select
source_model
。 也用於Yes/No
選擇。 如需範例,請參閱Magento\Search\Model\Adminhtml\System\Config\Source\Engine
。multiselect
select
,但多個選項有效。button
Magento\ScheduledImportExport\Block\Adminhtml\System\Config\Clean
。obscure
**​**
值的文字欄位。 在瀏覽器中使用「Inspect元素」變更型別不會顯示值。password
obscure
,但隱藏值並未加密,在瀏覽器中使用「Inspect Element」強制變更型別時,不會顯示值。file
label
time
allowspecific
source_model
,例如Magento\Shipping\Model\Config\Source\Allspecificcountries
image
note
frontend_model
才能呈現備註。您也可以建立自訂欄位型別。 這通常在需要特殊按鈕及動作時完成。 若要這麼做,需要兩個主要元素:
- 在
adminhtml
區域中建立區塊 - 正在將
type=""
設定為此區塊的路徑
區塊本身至少需要__construct
方法和getElementHtml()
方法。 Magento_OfflineShipping是自訂型別的簡單範例。
例如,在OfflineShipping模組中, Export按鈕定義於Magento\OfflineShipping\Block\Adminhtml\Form\Field\Export
,而欄位定義如下:
<field id="export" translate="label" type="Magento\OfflineShipping\Block\Adminhtml\Form\Field\Export" sortOrder="5" showInDefault="0" showInWebsite="1" showInStore="0">
<label>Export</label>
</field>
欄位節點參考
<field>
— 標籤可以有下列子系:
label
string
comment
<![CDATA[//]]>
可套用HTML。string
tooltip
string
hint
frontend_model
。string
frontend_class
string
frontend_model
typeModel
backend_model
typeModel
source_model
typeModel
config_path
typeConfigPath
validate
string
can_be_empty
type
為multiselect
時使用,以指定欄位可為空白。int
if_module_enabled
typeModule
base_url
upload_dir
搭配使用以進行檔案上傳。typeUrl
upload_dir
typeUploadDir
button_url
button_url
和button_label
,則顯示按鈕。 通常與自訂前端模型結合使用。typeUrl
button_label
button_label
和button_url
,則顯示按鈕。 通常與自訂前端模型結合使用。string
more_url
typeUrl
demo_url
typeUrl
hide_in_single_store_mode
1
隱藏群組;0
顯示群組。int
options
complexType
depends
1
時,僅用於顯示特定欄位/群組。 此節點需要section/group/field
字串。complexType
attribute
complexType
requires
complexType
more_url
、demo_url
、requires
和options
是由不同的核心付款模式所定義,而且只使用一次。 這些節點無法重複使用。範例:在指定群組中建立兩個欄位
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
<system>
<tab id="A_UNIQUE_ID" translate="label" class="a-custom-css-class-to-style-this-tab" sortOrder="10">
<label>A meaningful label</label>
</tab>
<section id="A_UNIQUE_SECTION_ID" showInDefault="1" showInWebsite="0" showInStore="1" sortOrder="10" translate="label">
<label>A meaningful section label</label>
<tab>A_UNIQUE_ID</tab>
<resource>VENDOR_MODULE::path_to_the_acl_resource</resource>
<group id="A_UNIQUE_GROUP_ID" translate="label" sortOrder="10" showInDefault="1" showInWebsite="0" showInStore="1">
<label>A meaningful group label</label>
<comment>An additional comment helping users to understand the effect when configuring the fields defined in this group.</comment>
<field id="A_UNIQUE_FIELD_ID" translate="label" sortOrder="10" showInDefault="0" showInWebsite="0" showInStore="1" type="select">
<label>Feature Flag Example</label>
<comment>This field is an example for a basic yes or no select.</comment>
<tooltip>Usually these kinds of fields are used to enable or disable a given feature. Other fields might be dependent to this and will only appear if this field is set to yes.</tooltip>
<source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
</field>
<field id="ANOTHER_UNIQUE_FIELD_ID" translate="label" sortOrder="10" showInDefault="0" showInWebsite="0" showInStore="1" type="text">
<label>A meaningful field label</label>
<comment>A descriptive text explaining this configuration field.</comment>
<tooltip>Another possible frontend element that also can be used to describe the meaning of this field. Will be displayed as a small icon beside the field.</tooltip>
<validate>required-entry no-whitespace</validate> <!-- Field is required and must not contain any whitespace. -->
<if_module_enabled>VENDOR_MODULE</if_module_enabled>
<depends> <!-- This field will only be visible if the field with the id A_UNIQUE_FIELD_ID is set to value 1 -->
<field id="A_UNIQUE_FIELD_ID">1</field>
</depends>
</field>
</group>
</section>
</system>
</config>
上述範例會建立兩個欄位,兩者在預設和存放區檢視中均為可見/可設定。 這兩個欄位都有註解和工具提示,可向使用者說明其用途。 label
節點是可翻譯的。
當if_module_enabled
中的指定模組全域啟用時,識別碼為ANOTHER_UNIQUE_FIELD_ID
的欄位會顯示。 欄位也依據規則required-entry
和no-whitespace
驗證其值。
識別碼為A_UNIQUE_FIELD_ID
的欄位定義不同的來源模型,提供該值Yes
和No
。
通用來源模型
Commerce 2核心提供下列來源模型。 一般而言,來源模型還有許多;以下清單說明最常見的模型。 請注意,這些來源模型需要欄位屬性type
設定為select
才能正常運作。
Magento\Config\Model\Config\Source\Yesnocustom
Yes
、No
和Specified
。Magento\Config\Model\Config\Source\Enabledisable
Enable
, Disable
。 在資料庫中將值儲存為0
和1
。Magento\AdminNotification\Model\Config\Source\Frequency
1 Hour
、2 Hours
、6 Hours
、12 Hours
和24 Hours
。 值會儲存為整數。Magento\Catalog\Model\Config\Source\TimeFormat
Magento\Cron\Model\Config\Source\Frequency
Daily
、Weekly
和Monthly
。 值在資料庫中儲存為D
、W
和M
。Magento\GoogleAdwords\Model\Config\Source\Language
Magento\Config\Model\Config\Source\Locale
欄位驗證
欄位可以指派一或多個驗證器類別,以確保使用者的輸入符合擴充功能的需求。 驗證規則可與<validate>
標籤一起套用。
下列範例會驗證欄位並新增數個不同的驗證規則。
<field id="A_CUSTOM_IDENTIFIER" showInDefault="1" showInWebsite="0" showInStore="1">
<validate>required-entry validate-clean-url no-whitespace</validate>
</field>
可使用下列驗證規則:
alphanumeric
integer
ipv4
ipv6
letters-only
abcABC
。letters-with-basic-punc
必須傳遞下列運算式:
/^[a-z\-.,()\u0027\u0022\s]+$/i
。mobileUK
no-marginal-whitespace
no-whitespace
phoneUK
phoneUS
required-entry
validate-no-empty
的驗證)。驗證失敗訊息:「這是必填欄位。」
time
15
、15:05
或15:05:48
。time12h
3 am
、11:30 pm
、02:15:00 pm
。validate-admin-password
validate-alphanum-with-spaces
validate-clean-url
https://www.example.com
或www.example.com
。validate-currency-dollar
validate-data
第一個字元必須是字母。
(必須符合運算式:
/^[A-Za-z]+[A-Za-z0-9_]+$/
)驗證失敗訊息:「在此欄位中僅使用字母(a-z或A-Z)、數字(0-9)或底線(_),第一個字元應為字母。」
validate-date-au
validate-email
validate-emailSender
validate-fax
validate-no-empty
requried-entry
的驗證)。驗證失敗訊息:「空值」。
validate-no-html-tags
validate-password
validate-phoneLax
validate-phoneStrict
validate-select
null
值、字串值none
或字串長度0。validate-ssn
validate-street
validate-url
validate-xml-identifier
validate-zip-us
vinUS
預設值
可在section/group/field_ID
節點中指定預設值,以在模組的etc/config.xml
檔案中設定欄位預設值。
範例:設定ANOTHER_UNIQUE_FIELD_ID
的預設值(預設範圍)
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Store:etc/config.xsd">
<default>
<A_UNIQUE_SECTION_ID>
<A_UNIQUE_GROUP_ID>
<ANOTHER_UNIQUE_FIELD_ID>This is the default value</ANOTHER_UNIQUE_FIELD_ID>
</A_UNIQUE_GROUP_ID>
</A_UNIQUE_SECTION_ID>
</default>
</config>
範例:設定ANOTHER_UNIQUE_FIELD_ID
的預設值(網站範圍)
使用websites
標籤,指定特定網站的預設值。
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Store:etc/config.xsd">
<websites>
<WEBSITE_CODE>
<A_UNIQUE_SECTION_ID>
<A_UNIQUE_GROUP_ID>
<ANOTHER_UNIQUE_FIELD_ID>This is the default value</ANOTHER_UNIQUE_FIELD_ID>
</A_UNIQUE_GROUP_ID>
</A_UNIQUE_SECTION_ID>
</WEBSITE_CODE>
</websites>
</config>