[作者:David Lambauer]{class="badge informative" title="David Lambauer"} [僅限PaaS]{class="badge informative" title="僅適用於雲端專案(Adobe管理的PaaS基礎結構)和內部部署專案的Adobe Commerce 。"}
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> — 標籤可以有下列屬性:
idtypeIdtranslatelabel讓標籤可翻譯。stringsortOrderfloatclassstring索引標籤節點參考
<tab>標籤可以有下列子系:
labelstring範例:建立標籤
下列程式碼片段示範如何使用範例資料建立新標籤。
<?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專案。
值為sortOrder的10屬性定義轉譯時索引標籤在所有索引標籤清單中的位置。
部分
<section>-Tag參照到系統組態中的現有或新區段。
區段屬性參考
<section> — 標籤可以有下列屬性:
idtypeIdtranslatelabel讓標籤可翻譯。stringtypetext。stringsortOrderfloatshowInDefault1以顯示區段,指定0隱藏區段。intshowInStore1以顯示區段,指定0隱藏區段。intshowInWebsite1以顯示區段,指定0隱藏區段。intcanRestoreintadvancedboolextendsstring區段節點參考
<section> — 標籤可以有下列子系:
labelstringclassstringtabtypeTabIdheader_cssstringresourcetypeAclResourceIdgrouptypeGroupfrontend_modeltypeModelincludesystem_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> — 標籤可以有下列屬性:
idtypeIdtranslatelabel讓標籤可翻譯。 多個欄位應以空格分隔。stringtypetext。stringsortOrderfloatshowInDefault1以顯示群組,指定0隱藏群組。intshowInStore1以顯示群組,指定0隱藏群組。intshowInWebsite1以顯示群組,指定0隱藏群組。intcanRestoreintadvancedboolextendsstring群組節點參考
<group> — 標籤可以有下列子系:
labelstringfieldset_cssstringfrontend_modeltypeModelclone_modeltypeModelclone_fieldsinthelp_urltypeUrlmore_urltypeUrldemo_linktypeUrlcomment<![CDATA[//]]>即可套用HTML。stringhide_in_single_store_mode1隱藏群組;0顯示群組。intfieldfieldgroupunboundeddepends1時,才會用來顯示特定欄位/群組。 此節點需要section/group/field字串。dependsattributeattributeincludesystem_include.xsd個相容的檔案。 通常用於建構大型system.xml檔案。includeTypemore_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> — 標籤可以有下列屬性:
idtypeIdtranslatelabel讓標籤可翻譯。 多個欄位應以空格分隔。stringtypetext。stringsortOrderfloatshowInDefault1以顯示欄位,指定0隱藏欄位。intshowInStore1以顯示欄位,指定0隱藏欄位。intshowInWebsite1以顯示欄位,指定0隱藏欄位。intcanRestoreintadvancedboolextendsstring欄位型別參考
<field> — 標籤的type=""屬性可以有下列值:
texttextareaselectsource_model。 也用於Yes/No選擇。 如需範例,請參閱Magento\Search\Model\Adminhtml\System\Config\Source\Engine。multiselectselect,但多個選項有效。buttonMagento\ScheduledImportExport\Block\Adminhtml\System\Config\Clean。obscure**​**值的文字欄位。 在瀏覽器中使用「檢查元素」變更型別不會顯示值。passwordobscure,但隱藏值並未加密,在瀏覽器中使用「檢查元素」強制變更型別時,不會顯示值。filelabeltimeallowspecificsource_model,例如Magento\Shipping\Model\Config\Source\Allspecificcountriesimagenotefrontend_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> — 標籤可以有下列子系:
labelstringcomment<![CDATA[//]]>即可套用HTML。stringtooltipstringhintfrontend_model。stringfrontend_classstringfrontend_modeltypeModelbackend_modeltypeModelsource_modeltypeModelconfig_pathtypeConfigPathvalidatestringcan_be_emptytype為multiselect時使用,以指定欄位可為空白。intif_module_enabledtypeModulebase_urlupload_dir搭配使用以進行檔案上傳。typeUrlupload_dirtypeUploadDirbutton_urlbutton_url和button_label,則顯示按鈕。 通常與自訂前端模型結合使用。typeUrlbutton_labelbutton_label和button_url,則顯示按鈕。 通常與自訂前端模型結合使用。stringmore_urltypeUrldemo_urltypeUrlhide_in_single_store_mode1隱藏群組;0顯示群組。intoptionscomplexTypedepends1時,僅用於顯示特定欄位/群組。 此節點需要section/group/field字串。complexTypeattributecomplexTyperequirescomplexTypemore_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節點是可翻譯的。
當ANOTHER_UNIQUE_FIELD_ID中的指定模組全域啟用時,識別碼為if_module_enabled的欄位會顯示。 欄位也依據規則required-entry和no-whitespace驗證其值。
識別碼為A_UNIQUE_FIELD_ID的欄位定義不同的來源模型,提供該值Yes和No。
通用來源模型
Commerce 2核心提供下列來源模型。 一般而言,來源模型還有許多;以下清單說明最常見的模型。 請注意,這些來源模型需要欄位屬性type設定為select才能正常運作。
Magento\Config\Model\Config\Source\YesnocustomYes、No和Specified。Magento\Config\Model\Config\Source\EnabledisableEnable, Disable。 在資料庫中將值儲存為0和1。Magento\AdminNotification\Model\Config\Source\Frequency1 Hour、2 Hours、6 Hours、12 Hours和24 Hours。 值會儲存為整數。Magento\Catalog\Model\Config\Source\TimeFormatMagento\Cron\Model\Config\Source\FrequencyDaily、Weekly和Monthly。 值在資料庫中儲存為D、W和M。Magento\GoogleAdwords\Model\Config\Source\LanguageMagento\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>
可使用下列驗證規則:
alphanumericintegeripv4ipv6letters-onlyabcABC。letters-with-basic-punc必須傳遞下列運算式:
/^[a-z\-.,()\u0027\u0022\s]+$/i。mobileUKno-marginal-whitespaceno-whitespacephoneUKphoneUSrequired-entryvalidate-no-empty的驗證)。驗證失敗訊息:「這是必填欄位。」
time15、15:05或15:05:48。time12h3 am、11:30 pm、02:15:00 pm。validate-admin-passwordvalidate-alphanum-with-spacesvalidate-clean-urlhttps://www.example.com或www.example.com。validate-currency-dollarvalidate-data第一個字元必須是字母。
(必須符合運算式:
/^[A-Za-z]+[A-Za-z0-9_]+$/)驗證失敗訊息:「在此欄位中僅使用字母(a-z或A-Z)、數字(0-9)或底線(_),第一個字元應為字母。」
validate-date-auvalidate-emailvalidate-emailSendervalidate-faxvalidate-no-emptyrequried-entry的驗證)。驗證失敗訊息:「空值」。
validate-no-html-tagsvalidate-passwordvalidate-phoneLaxvalidate-phoneStrictvalidate-selectnull值、字串值none或字串長度0。validate-ssnvalidate-streetvalidate-urlvalidate-xml-identifiervalidate-zip-usvinUS預設值
可在etc/config.xml節點中指定預設值,以在模組的section/group/field_ID檔案中設定欄位預設值。
範例:設定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>