mirror of
https://github.com/godotengine/godot-docs-l10n.git
synced 2026-01-04 10:09:56 +03:00
288 lines
19 KiB
ReStructuredText
288 lines
19 KiB
ReStructuredText
:github_url: hide
|
||
|
||
.. _class_ResourceFormatLoader:
|
||
|
||
ResourceFormatLoader
|
||
====================
|
||
|
||
**繼承：** :ref:`RefCounted<class_RefCounted>` **<** :ref:`Object<class_Object>`
|
||
|
||
從檔案中載入特定資源型別。
|
||
|
||
.. rst-class:: classref-introduction-group
|
||
|
||
說明
|
||
----
|
||
|
||
Godot 在編輯器或匯出的遊戲中使用 ResourceFormatLoaders 來載入資源。它們通過 :ref:`ResourceLoader<class_ResourceLoader>` 單例自動查詢，或在載入具有內部依賴項的資源時自動查詢。每種文件型別可以作為不同的資源型別載入，因此在引擎中註冊多個 ResourceFormatLoaders。
|
||
|
||
擴充此類可讓你定義自己的載入器。請確保遵守文件中記錄的返回型別和值。你應該使用 ``class_name`` 給它一個全域類別名稱以進行註冊。像內建的 ResourceFormatLoaders 一樣，當載入其處理的型別的資源時，它將自動被呼叫。你還可以實作 :ref:`ResourceFormatSaver<class_ResourceFormatSaver>`\ 。
|
||
|
||
\ **注意：**\ 如果你需要的資源型別存在，但 Godot 無法載入其格式，則也可以擴充 :ref:`EditorImportPlugin<class_EditorImportPlugin>`\ 。選擇哪種方法取決於該格式是否適用於最終匯出的遊戲。例如，最好首先將 ``.png`` 紋理作為 ``.ctex``\ （\ :ref:`CompressedTexture2D<class_CompressedTexture2D>`\ ）匯入，以便在圖形卡上能更高效的載入它們。
|
||
|
||
.. rst-class:: classref-reftable-group
|
||
|
||
方法
|
||
----
|
||
|
||
.. table::
|
||
:widths: auto
|
||
|
||
+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`bool<class_bool>` | :ref:`_exists<class_ResourceFormatLoader_private_method__exists>`\ (\ path\: :ref:`String<class_String>`\ ) |virtual| |const| |
|
||
+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`PackedStringArray<class_PackedStringArray>` | :ref:`_get_classes_used<class_ResourceFormatLoader_private_method__get_classes_used>`\ (\ path\: :ref:`String<class_String>`\ ) |virtual| |const| |
|
||
+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`PackedStringArray<class_PackedStringArray>` | :ref:`_get_dependencies<class_ResourceFormatLoader_private_method__get_dependencies>`\ (\ path\: :ref:`String<class_String>`, add_types\: :ref:`bool<class_bool>`\ ) |virtual| |const| |
|
||
+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`PackedStringArray<class_PackedStringArray>` | :ref:`_get_recognized_extensions<class_ResourceFormatLoader_private_method__get_recognized_extensions>`\ (\ ) |virtual| |const| |
|
||
+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`String<class_String>` | :ref:`_get_resource_script_class<class_ResourceFormatLoader_private_method__get_resource_script_class>`\ (\ path\: :ref:`String<class_String>`\ ) |virtual| |const| |
|
||
+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`String<class_String>` | :ref:`_get_resource_type<class_ResourceFormatLoader_private_method__get_resource_type>`\ (\ path\: :ref:`String<class_String>`\ ) |virtual| |const| |
|
||
+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`int<class_int>` | :ref:`_get_resource_uid<class_ResourceFormatLoader_private_method__get_resource_uid>`\ (\ path\: :ref:`String<class_String>`\ ) |virtual| |const| |
|
||
+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`bool<class_bool>` | :ref:`_handles_type<class_ResourceFormatLoader_private_method__handles_type>`\ (\ type\: :ref:`StringName<class_StringName>`\ ) |virtual| |const| |
|
||
+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`Variant<class_Variant>` | :ref:`_load<class_ResourceFormatLoader_private_method__load>`\ (\ path\: :ref:`String<class_String>`, original_path\: :ref:`String<class_String>`, use_sub_threads\: :ref:`bool<class_bool>`, cache_mode\: :ref:`int<class_int>`\ ) |virtual| |required| |const| |
|
||
+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`bool<class_bool>` | :ref:`_recognize_path<class_ResourceFormatLoader_private_method__recognize_path>`\ (\ path\: :ref:`String<class_String>`, type\: :ref:`StringName<class_StringName>`\ ) |virtual| |const| |
|
||
+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`_rename_dependencies<class_ResourceFormatLoader_private_method__rename_dependencies>`\ (\ path\: :ref:`String<class_String>`, renames\: :ref:`Dictionary<class_Dictionary>`\ ) |virtual| |const| |
|
||
+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||
|
||
.. rst-class:: classref-section-separator
|
||
|
||
----
|
||
|
||
.. rst-class:: classref-descriptions-group
|
||
|
||
列舉
|
||
----
|
||
|
||
.. _enum_ResourceFormatLoader_CacheMode:
|
||
|
||
.. rst-class:: classref-enumeration
|
||
|
||
enum **CacheMode**: :ref:`🔗<enum_ResourceFormatLoader_CacheMode>`
|
||
|
||
.. _class_ResourceFormatLoader_constant_CACHE_MODE_IGNORE:
|
||
|
||
.. rst-class:: classref-enumeration-constant
|
||
|
||
:ref:`CacheMode<enum_ResourceFormatLoader_CacheMode>` **CACHE_MODE_IGNORE** = ``0``
|
||
|
||
Neither the main resource (the one requested to be loaded) nor any of its subresources are retrieved from cache nor stored into it. Dependencies (external resources) are loaded with :ref:`CACHE_MODE_REUSE<class_ResourceFormatLoader_constant_CACHE_MODE_REUSE>`.
|
||
|
||
.. _class_ResourceFormatLoader_constant_CACHE_MODE_REUSE:
|
||
|
||
.. rst-class:: classref-enumeration-constant
|
||
|
||
:ref:`CacheMode<enum_ResourceFormatLoader_CacheMode>` **CACHE_MODE_REUSE** = ``1``
|
||
|
||
The main resource (the one requested to be loaded), its subresources, and its dependencies (external resources) are retrieved from cache if present, instead of loaded. Those not cached are loaded and then stored into the cache. The same rules are propagated recursively down the tree of dependencies (external resources).
|
||
|
||
.. _class_ResourceFormatLoader_constant_CACHE_MODE_REPLACE:
|
||
|
||
.. rst-class:: classref-enumeration-constant
|
||
|
||
:ref:`CacheMode<enum_ResourceFormatLoader_CacheMode>` **CACHE_MODE_REPLACE** = ``2``
|
||
|
||
Like :ref:`CACHE_MODE_REUSE<class_ResourceFormatLoader_constant_CACHE_MODE_REUSE>`, but the cache is checked for the main resource (the one requested to be loaded) as well as for each of its subresources. Those already in the cache, as long as the loaded and cached types match, have their data refreshed from storage into the already existing instances. Otherwise, they are recreated as completely new objects.
|
||
|
||
.. _class_ResourceFormatLoader_constant_CACHE_MODE_IGNORE_DEEP:
|
||
|
||
.. rst-class:: classref-enumeration-constant
|
||
|
||
:ref:`CacheMode<enum_ResourceFormatLoader_CacheMode>` **CACHE_MODE_IGNORE_DEEP** = ``3``
|
||
|
||
Like :ref:`CACHE_MODE_IGNORE<class_ResourceFormatLoader_constant_CACHE_MODE_IGNORE>`, but propagated recursively down the tree of dependencies (external resources).
|
||
|
||
.. _class_ResourceFormatLoader_constant_CACHE_MODE_REPLACE_DEEP:
|
||
|
||
.. rst-class:: classref-enumeration-constant
|
||
|
||
:ref:`CacheMode<enum_ResourceFormatLoader_CacheMode>` **CACHE_MODE_REPLACE_DEEP** = ``4``
|
||
|
||
Like :ref:`CACHE_MODE_REPLACE<class_ResourceFormatLoader_constant_CACHE_MODE_REPLACE>`, but propagated recursively down the tree of dependencies (external resources).
|
||
|
||
.. rst-class:: classref-section-separator
|
||
|
||
----
|
||
|
||
.. rst-class:: classref-descriptions-group
|
||
|
||
方法說明
|
||
--------
|
||
|
||
.. _class_ResourceFormatLoader_private_method__exists:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`bool<class_bool>` **_exists**\ (\ path\: :ref:`String<class_String>`\ ) |virtual| |const| :ref:`🔗<class_ResourceFormatLoader_private_method__exists>`
|
||
|
||
.. container:: contribute
|
||
|
||
There is currently no description for this method. Please help us by `contributing one <https://contributing.godotengine.org/en/latest/documentation/class_reference.html>`__!
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ResourceFormatLoader_private_method__get_classes_used:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`PackedStringArray<class_PackedStringArray>` **_get_classes_used**\ (\ path\: :ref:`String<class_String>`\ ) |virtual| |const| :ref:`🔗<class_ResourceFormatLoader_private_method__get_classes_used>`
|
||
|
||
.. container:: contribute
|
||
|
||
There is currently no description for this method. Please help us by `contributing one <https://contributing.godotengine.org/en/latest/documentation/class_reference.html>`__!
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ResourceFormatLoader_private_method__get_dependencies:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`PackedStringArray<class_PackedStringArray>` **_get_dependencies**\ (\ path\: :ref:`String<class_String>`, add_types\: :ref:`bool<class_bool>`\ ) |virtual| |const| :ref:`🔗<class_ResourceFormatLoader_private_method__get_dependencies>`
|
||
|
||
Should return the dependencies for the resource at the given ``path``. Each dependency is a string composed of one to three sections separated by ``::``, with trailing empty sections omitted:
|
||
|
||
- The first section should contain the UID if the resource has one. Otherwise, it should contain the file path.
|
||
|
||
- The second section should contain the class name of the dependency if ``add_types`` is ``true``. Otherwise, it should be empty.
|
||
|
||
- The third section should contain the fallback path if the resource has a UID. Otherwise, it should be empty.
|
||
|
||
::
|
||
|
||
func _get_dependencies(path, add_types):
|
||
return [
|
||
"uid://fqgvuwrkuixh::Script::res://script.gd",
|
||
"uid://fqgvuwrkuixh::::res://script.gd",
|
||
"res://script.gd::Script",
|
||
"res://script.gd",
|
||
]
|
||
|
||
\ **Note:** Custom resource types defined by scripts aren't known by the :ref:`ClassDB<class_ClassDB>`, so ``"Resource"`` can be used for the class name.
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ResourceFormatLoader_private_method__get_recognized_extensions:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`PackedStringArray<class_PackedStringArray>` **_get_recognized_extensions**\ (\ ) |virtual| |const| :ref:`🔗<class_ResourceFormatLoader_private_method__get_recognized_extensions>`
|
||
|
||
獲取該載入器能夠讀取的檔的副檔名列表。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ResourceFormatLoader_private_method__get_resource_script_class:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`String<class_String>` **_get_resource_script_class**\ (\ path\: :ref:`String<class_String>`\ ) |virtual| |const| :ref:`🔗<class_ResourceFormatLoader_private_method__get_resource_script_class>`
|
||
|
||
返回與給定的 ``path`` 下的 :ref:`Resource<class_Resource>` 關聯的腳本類別名稱稱。如果資源沒有腳本或腳本不是一個命名的類，則應返回 ``""``\ 。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ResourceFormatLoader_private_method__get_resource_type:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`String<class_String>` **_get_resource_type**\ (\ path\: :ref:`String<class_String>`\ ) |virtual| |const| :ref:`🔗<class_ResourceFormatLoader_private_method__get_resource_type>`
|
||
|
||
獲取與給定路徑相關的資源的類別名稱。如果載入器不能處理它，它應該返回 ``""``\ 。
|
||
|
||
\ **注意：**\ :ref:`ClassDB<class_ClassDB>` 不知道腳本定義的自訂資源型別，因此你可能只為它們返回 ``"Resource"``\ 。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ResourceFormatLoader_private_method__get_resource_uid:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`int<class_int>` **_get_resource_uid**\ (\ path\: :ref:`String<class_String>`\ ) |virtual| |const| :ref:`🔗<class_ResourceFormatLoader_private_method__get_resource_uid>`
|
||
|
||
Should return the unique ID for the resource associated with the given path. If this method is not overridden, a ``.uid`` file is generated along with the resource file, containing the unique ID.
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ResourceFormatLoader_private_method__handles_type:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`bool<class_bool>` **_handles_type**\ (\ type\: :ref:`StringName<class_StringName>`\ ) |virtual| |const| :ref:`🔗<class_ResourceFormatLoader_private_method__handles_type>`
|
||
|
||
說明這個載入器可以載入哪個資源類。
|
||
|
||
\ **注意：**\ :ref:`ClassDB<class_ClassDB>` 不知道腳本定義的自訂資源型別，因此你可以只為它們處理 ``"Resource"``\ 。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ResourceFormatLoader_private_method__load:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`Variant<class_Variant>` **_load**\ (\ path\: :ref:`String<class_String>`, original_path\: :ref:`String<class_String>`, use_sub_threads\: :ref:`bool<class_bool>`, cache_mode\: :ref:`int<class_int>`\ ) |virtual| |required| |const| :ref:`🔗<class_ResourceFormatLoader_private_method__load>`
|
||
|
||
當引擎發現該載入程式相容時載入資源。如果載入的資源是匯入的結果，\ ``original_path`` 將以原始檔案為目標。成功時返回一個 :ref:`Resource<class_Resource>` 物件，失敗時返回一個 :ref:`Error<enum_@GlobalScope_Error>` 常數。
|
||
|
||
\ ``cache_mode`` 屬性定義載入資源時是否以及如何使用或更新快取。有關詳細信息，請參閱 :ref:`CacheMode<enum_ResourceFormatLoader_CacheMode>`\ 。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ResourceFormatLoader_private_method__recognize_path:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`bool<class_bool>` **_recognize_path**\ (\ path\: :ref:`String<class_String>`, type\: :ref:`StringName<class_StringName>`\ ) |virtual| |const| :ref:`🔗<class_ResourceFormatLoader_private_method__recognize_path>`
|
||
|
||
判斷該載入器是否應對於給定型別從其資源路徑載入資源。
|
||
|
||
如果未實作，則預設行為是檢查路徑的副檔名是否在\ :ref:`_get_recognized_extensions()<class_ResourceFormatLoader_private_method__get_recognized_extensions>`\ 提供的範圍內，以及型別是否在\ :ref:`_get_resource_type()<class_ResourceFormatLoader_private_method__get_resource_type>`\ 提供的範圍內。
|
||
|
||
.. rst-class:: classref-item-separator
|
||
|
||
----
|
||
|
||
.. _class_ResourceFormatLoader_private_method__rename_dependencies:
|
||
|
||
.. rst-class:: classref-method
|
||
|
||
:ref:`Error<enum_@GlobalScope_Error>` **_rename_dependencies**\ (\ path\: :ref:`String<class_String>`, renames\: :ref:`Dictionary<class_Dictionary>`\ ) |virtual| |const| :ref:`🔗<class_ResourceFormatLoader_private_method__rename_dependencies>`
|
||
|
||
如果被實作，將重命名給定資源中的依賴項並保存它。\ ``renames`` 是一個字典 ``{ String => String }``\ ，將舊依賴路徑對應到新路徑。
|
||
|
||
成功時返回 :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>`\ ，失敗時返回 :ref:`Error<enum_@GlobalScope_Error>` 常數。
|
||
|
||
.. |virtual| replace:: :abbr:`virtual (本方法通常需要使用者覆寫才能生效。)`
|
||
.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)`
|
||
.. |const| replace:: :abbr:`const (本方法沒有副作用。不會修改該實例的任何成員變數。)`
|
||
.. |vararg| replace:: :abbr:`vararg (本方法除了這裡描述的參數外，還可以接受任意數量的參數。)`
|
||
.. |constructor| replace:: :abbr:`constructor (本方法用於建構一個型別。)`
|
||
.. |static| replace:: :abbr:`static (本方法無需實例即可呼叫，因此可以直接使用類別名稱呼叫。)`
|
||
.. |operator| replace:: :abbr:`operator (本方法描述將本型別作為左運算元時可用的有效運算子。)`
|
||
.. |bitfield| replace:: :abbr:`BitField (此值是由下列旗標組成的位元遮罩整數。)`
|
||
.. |void| replace:: :abbr:`void (無回傳值。)`
|