Native Settings UI Lib

Yap Native Settings UI（Yap_NativeSettingsUI）

簡體中文 | English

-: Native_Settings_UI_Lib

• GitHub: YapYap_Native-Settings-UI-Lib

倉庫結構

• 庫源碼：YapYap_Native-Settings-UI-Lib/
• 使用例程（包含所有組件）：YapYap_Native-Settings-UI-Demo/

更新日誌

• 2026-02-15
• 修復 UI 注入路徑：適配新 UI 結構與對象名，增加多路徑回退
• 更新 DLL 引用 HintPath：解決編譯引用路徑問題
• 新增示例項目：YapYap_Native-Settings-UI-Demo 覆蓋所有常用控件

簡體中文

一個用於 YapYap（BepInEx） 的設置界面注入庫：在遊戲自帶 UISettings 界面中，自動創建自定義 Tab 與 Section，並在其中生成按鈕、開關、下拉、滑條、標籤、編輯框等控件。

本 README 重點介紹 公開接口 與參數含義。

快速開始

典型用法：

var tab = NativeSettingsUI.RegisterTab(

guid: "com.yourmod.settings.tab",

title: new LocalText("TAB_TITLE", "我的設置", "My Settings"),

showInGame: true

);

tab.CreateToggle(

id: "Toggle_Enabled",

settingKey: "com.yourmod.Enabled",

title: new LocalText("ENABLED", "啓用", "Enabled"),

initialValue: true,

onChanged: v => enabled = v,

showInGame: true

);

核心概念

• Tab / Section 注入

RegisterTab(...) 會在 UISettings 可用時，自動：

• 在左側 Tab 列表創建一個按鈕（Tab）
• 在右側 Section 區創建一個面板（Section）
• 點擊 Tab 時切換到該 Section（通過綁定到 UISettings.sections 實現）
• LocalText（簡易本地化文本）

LocalText 用來提供“中文/英文”兩套文本：

new LocalText(key: "EXAMPLE", chinese: "中文", english: "English")

• 如果你不打算製作多語言 UI,可以把 chinese或者 english 留空,但是至少要提供一個非空字符串
• 當前語言爲中文（Chinese/ChineseSimplified/ChineseTraditional）時顯示 chinese
• 否則顯示 english
• 該庫會監聽語言變化並自動刷新綁定過的文本
• UiRef（延遲拿到真實 UI 引用）

UISettings 的對象不是在 Awake 立刻存在，控件會“稍後”才被克隆/創建出來。

CreateXxx() 返回 UiRef：

• IsReady：是否已經拿到了真實 UI 組件引用
• Value：真實引用（未就緒時爲 null）
• Ready：當真實引用出現時觸發

UiRef labelRef = tab.CreateLabel(...);

labelRef.Ready += tmp =>

{

// tmp 就是真實的 TMP_Text

};

公共接口：NativeSettingsUI

命名空間：Yap_NativeSettingsUI

RegisterTab

public static SettingsTab RegisterTab(string guid, LocalText title, bool showInGame)

• guid：Tab 的唯一標識（建議用你的 ModId 前綴），重複註冊同 guid 會返回同一個 Tab
• title：Tab 標題（支持中/英切換）
• showInGame：是否在“遊戲內打開的設置界面”也顯示該 Tab（Tab 自身不開啓則控件再開也不會顯示）

BindText / UnbindText

用於給某個 TMP_Text 綁定/解綁 LocalText 的自動刷新邏輯。

public static void BindText(TMP_Text tmp, LocalText text)

public static void UnbindText(TMP_Text tmp)

適用場景：

• 你想讓某個文本跟隨語言變化：用 BindText
• 你想把某個標籤改成“運行時動態文本”，不再被本地化刷新覆蓋：先 UnbindText 再 tmp.text =...

公共接口：SettingsTab（創建控件）

RegisterTab(...) 返回 SettingsTab，所有控件都在 Tab 上創建。

通用參數說明

以下參數在多數控件中都有：

• id
• 控件對象名（用於查找/避免重複創建）
• 建議保持唯一，例如："Toggle_Enabled"、"Button_Save"
• showInGame
• 該控件是否在“遊戲內設置界面”顯示
• 前提：Tab 的 showInGame=true
• preferredSize（可選）
• 期望尺寸（寬高）
• 不傳則使用遊戲原生模板的默認尺寸/佈局
• 當你給某些控件設置了較大的寬度時，庫會啓用“自定義兩列流式佈局”，以支持跨列/換行
• anchoredPositionOffset（可選）
• 在最終位置基礎上做少量偏移（用於微調）
• 注意：如果父級佈局組件會重排，偏移可能會被佈局覆蓋或產生不可預期效果

CreateButton

public UiRef CreateButton(

string id,

LocalText text,

Action onClick,

bool showInGame = true,

Vector2? preferredSize = null,

Vector2? anchoredPositionOffset = null)

• text：按鈕顯示文本（中/英）
• onClick：點擊回調

CreateLabel

public UiRef CreateLabel(

string id,

LocalText text,

bool showInGame = true,

Vector2? preferredSize = null,

Vector2? anchoredPositionOffset = null)

• text：標籤文本（中/英）

CreateToggle

public UiRef CreateToggle(

string id,

string settingKey,

LocalText title,

bool initialValue,

Action onChanged,

bool showInGame = true,

Vector2? preferredSize = null,

Vector2? anchoredPositionOffset = null)

• title：控件標題（中/英）
• initialValue：初始值
• onChanged：值變化回調
• settingKey：持久化鍵名（見下文“settingKey 是什麼”）

CreateDropdownString

public UiRef CreateDropdownString(

string id,

string settingKey,

LocalText title,

IList options,

string initialValue,

Action onChanged,

bool showInGame = true,

Vector2? preferredSize = null,

Vector2? anchoredPositionOffset = null)

• options：下拉可選項（字符串列表）
• initialValue：初始選中項
• onChanged：選擇變化回調
• settingKey：持久化鍵名

CreateSliderInt

public UiRef CreateSliderInt(

string id,

string settingKey,

LocalText title,

int minValue,

int maxValue,

int initialValue,

Action onChanged,

bool showInGame = true,

Vector2? preferredSize = null,

Vector2? anchoredPositionOffset = null)

• minValue / maxValue：整數範圍
• initialValue：初始值（會被 clamp 到範圍內）
• onChanged：值變化回調
• settingKey：持久化鍵名

CreateInputStrin