ContextActionService

方法

BindAction(actionName : string,functionToBind : function,createTouchButton : boolean,inputTypes : Tuple):()
將使用者輸入綁定到給予行動處理功能的行動。
BindActionAtPriority(actionName : string,functionToBind : function,createTouchButton : boolean,priorityLevel : number,inputTypes : Tuple):()
行為像 BindAction 但也允許指定優先級給覆蓋輸入類型的綁定行動（先高於低）。
BindActivate(userInputTypeForActivation : Enum.UserInputType,keyCodesForActivation : Tuple):()
用特定的 Enum.KeyCode 與 Enum.UserInputType 綁定一個，以觸發 Tool.Activation 和 ClickDetector 事件。
GetAllBoundActionInfo():Dictionary
取得所有綁定行動的資訊表（鑰匙是傳給 BindAction 的名稱，值是在使用鍵時從 GetBoundActionInfo 獲得的表）。
GetBoundActionInfo(actionName : string):Dictionary
取得有關綁定行動的資訊表，其原始名稱傳送到 BindAction 的表。
GetCurrentLocalToolIcon():string
返回 BackpackItem.TextureId 的 Tool 目前 equipped 由 Player 。
SetDescription(actionName : string,description : string):()
根據觸摸按鈕的綁定行動名稱設置行動作的說明。
SetImage(actionName : string,image : string):()
如果 actionName 鍵包含綁定的動作，則 image 設為觸摸按鈕的圖像。
SetPosition(actionName : string,position : UDim2):()
根據觸摸按鈕的綁定行動名稱，設置按鈕在 ContextButtonFrame 中的位置。
SetTitle(actionName : string,title : string):()
根據觸摸按鈕的綁定行動名稱設置按鈕上顯示的文字。
UnbindAction(actionName : string):()
從輸入中解除行動的綁定，並將其名稱更改為其名稱。
UnbindActivate(userInputTypeForActivation : Enum.UserInputType,keyCodeForActivation : Enum.KeyCode):()
使用特定的 Enum.KeyCode 與 Enum.UserInputType 從觸發 Tool.Activation 當與 ContextActionService:BindActivate() 綁定時解除綁定。
UnbindAllActions():()
移除所有已綁定的功能。沒有行動名稱會留下。所有觸摸按鈕將被移除。
GetButton(actionName : string):Instance
暫停
取回一個 ImageButton 的 bound 行動，其中創建了一個觸摸輸入按鈕。

活動

LocalToolEquipped(toolEquipped : Instance):RBXScriptSignal
當現有玩家配備 Tool 時發生火災。
LocalToolUnequipped(toolUnequipped : Instance):RBXScriptSignal
當現有玩家卸下 Tool 時發生火災。

屬性

方法

BindAction

()

將行動綁定到使用者輸入，並提供行動處理函數。當匹配的輸入執行時，行動處理器功能會被稱為以下列參數呼叫。有效輸入枚列項目包括以追蹤中項目：Enum.KeyCode、Enum.UserInputType或Enum.PlayerActions 。當玩家進入可執行行動的上下文時，呼叫此函數。當玩家離開上下文時，呼叫 UnbindAction 使用相同的 actionName 。您可以使用 CallFunction 手動呼叫行動處理功能的行動。

下面的代碼示例顯示了如何在按下鍵(H)、遊戲控制板按鈕或觸摸屏按鈕時，Sound可以成為played


local ContextActionService = game:GetService("ContextActionService")

-- 汽笛聲音
local honkSound = Instance.new("Sound", workspace)
honkSound.Looped = true
honkSound.SoundId = "rbxassetid://9120386436"

local function handleAction(actionName, inputState, inputObject)
	if actionName == "HonkHorn" then
		if inputState == Enum.UserInputState.Begin then
			honkSound:Play()
		else
			honkSound:Pause()
		end
	end
end

-- 當玩家坐在車輛時：
ContextActionService:BindAction("HonkHorn", handleAction, true, Enum.KeyCode.H, Enum.KeyCode.ButtonY)

-- 當玩家離開時：
ContextActionService:UnbindAction("HonkHorn")

行動處理器參數

行動處理器功能會以下列參數呼叫：


<th>類型</th>

  <th>說明</th>
</tr>

<tr>
  <td>1</td>

  <td><code>字串</code></td>

  <td>最初傳送給 BindAction† 的相同字串</td>
</tr>

<tr>
  <td>2</td>

  <td><code>Enum.UserInputState</code></td>

  <td>輸入狀態(開始、變更、結束或取消)*</td>
</tr>

<tr>
  <td>3</td>

  <td><code>輸入對象</code></td>

  <td>包含輸入資訊的對象(根據使用者輸入類型而變化)</td>
</tr>

† 這樣可以讓一個功能一次處理多個行動，如有需要。※如果某些輸入正在進行中，且另一個動作綁定到進行中的輸入，或進行中的綁定動作為 unbound ，則取消將被發送。

行動綁定堆疊

行動綁定會像棧子一樣行動：如果兩個行動綁定到同一個使用者輸入，最近綁定的行動處理器將被使用。如果行動處理器返回 Enum.ContextActionResult.Pass，下一個最近綁定的行動處理器將被呼叫，直到行動處理器將輸入沉沒（通過返回 nil 或 Enum.ContextActionResult.Sink）。當 UnbindAction 被呼叫時，行動處理器將從堆中移除。這種堆疊行為可以使用 BindActionAtPriority 來覆蓋，其中在 createTouchButton 之後的額外優先級參數可能會覆蓋行動綁定的順序（先高後低）。

觸摸按鈕

除了輸入類型外，此函數的第三個參數控制是否為 TouchEnabled 裝置創建按鈕。在第一個觸摸按鈕創作品時,一個名為"ContextActionGui"的ScreenGui被添加到PlayerGui。在 ScreenGui 內部添加了 Frame 稱為 "ContextButtonFrame" 的項目。在這個框架中，ImageButtons 用於綁定操作的父級；您可以使用 GetButton 來恢復這些按鈕以進行自訂。

參數

actionName: string

代表正在執行的動作的字串（例如「HonkHorn」或「OpenDoor」）。

預設值：""

functionToBind: function

當綁定輸入被觸發時，使用以下參數呼叫行動處理功能：string(actionName)、Enum.UserInputState 和一個輸入對象。

預設值：""

createTouchButton: boolean

是否應為觸摸輸入裝置上的操作創建 GUI 按鈕。

預設值：""

inputTypes: Tuple

任何數量的 Enum.KeyCode 或 Enum.UserInputType 代表要綁定到行動作的輸入。

預設值：""

()

範例程式碼

ContextActionService Tool Reload

local ContextActionService = game:GetService("ContextActionService")

local ACTION_RELOAD = "Reload"

local tool = script.Parent

local function handleAction(actionName, inputState, _inputObject)
	if actionName == ACTION_RELOAD and inputState == Enum.UserInputState.Begin then
		print("Reloading!")
	end
end

tool.Equipped:Connect(function()
	ContextActionService:BindAction(ACTION_RELOAD, handleAction, true, Enum.KeyCode.R)
end)

tool.Unequipped:Connect(function()
	ContextActionService:UnbindAction(ACTION_RELOAD)
end)

This code sample uses ContextActionService to bind an action named "BoundAction" to a general action handler function on the F key. Place this in a LocalScript inside StarterPlayerScripts and press F to see the message "Handling action: BoundAction".

General Action Handler

local ContextActionService = game:GetService("ContextActionService")

local function handleAction(actionName, inputState, inputObj)
	if inputState == Enum.UserInputState.Begin then
		print("Handling action: " .. actionName)
		print(inputObj.UserInputType)
	end

	-- Since this function does not return anything, this handler will
	-- "sink" the input and no other action handlers will be called after
	-- this one.
end

ContextActionService:BindAction("BoundAction", handleAction, false, Enum.KeyCode.F)

This code sample demonstrates how BindAction acts like a stack. It binds two actions, FirstAction (Z, X, and C keys) and SecondAction (Z and X keys) to two action handling functions. The second one will pass on a certain input (the X key).

Both actions use the Z and X keys, however the second handler will pass input only if X is pressed. So, when X is pressed, the second handler is called and then the first. The first action is also bound to the C key, and can be triggered even though the other two inputs are "covered" by the second action.

Test this code out by pasting it into a LocalScript within StarterPlayerScripts, then pressing Z, X and C. Observe which action handlers are called with what actions.

Stacked Action Handlers

local ContextActionService = game:GetService("ContextActionService")

-- Define an action handler for FirstAction
local function actionHandlerOne(actionName, inputState, _inputObj)
	if inputState == Enum.UserInputState.Begin then
		print("Action Handler One: " .. actionName)
	end
	-- This action handler returns nil, so it is assumed that
	-- it properly handles the action.
end

-- Binding the action FirstAction (it's on the bottom of the stack)
ContextActionService:BindAction("FirstAction", actionHandlerOne, false, Enum.KeyCode.Z, Enum.KeyCode.X, Enum.KeyCode.C)

-- Define an action handler for SecondAction
local function actionHandlerTwo(actionName, inputState, inputObj)
	if inputState == Enum.UserInputState.Begin then
		print("Action Handler Two: " .. actionName)
	end

	if inputObj.KeyCode == Enum.KeyCode.X then
		return Enum.ContextActionResult.Pass
	else
		-- Returning nil implicitly Sinks inputs
		return Enum.ContextActionResult.Sink
	end
end

-- Binding SecondAction over the first action (since it bound more recently, it is on the top of the stack)
-- Note that SecondAction uses the same keys as
ContextActionService:BindAction("SecondAction", actionHandlerTwo, false, Enum.KeyCode.Z, Enum.KeyCode.X)

BindActionAtPriority

()

BindActionAtPriority 會像 BindAction 一樣行動，但也允許指定優先級給綁定的動作動。如果多個行動綁定到相同的輸入，優先級更高的函數將無視行動綁定的順序來執行。換言之，此功能會覆蓋 BindAction 的正常「堆疊」行為。

參數

actionName: string

代表正在執行的動作的字串（例如「HonkHorn」或「OpenDoor」）。

預設值：""

functionToBind: function

當綁定輸入被觸發時，使用以下參數呼叫行動處理功能：string(actionName)、Enum.UserInputState 和一個輸入對象。

預設值：""

createTouchButton: boolean

是否應為觸摸輸入裝置上的操作創建 GUI 按鈕。

預設值：""

priorityLevel: number

行動應該綁定的優先級(先考慮高於低)。

預設值：""

inputTypes: Tuple

任何數量的 Enum.KeyCode 或 Enum.UserInputType 代表要綁定到行動作的輸入。

預設值：""

()

範例程式碼

This code sample demonstrates how ContextActionService:BindActionAtPriority() can be used to bind actions out of order yet still have the same priority levels. Normally, BindAction() would operate on order (last bound action has highest priority), but priority levels override this. You can test this code by pasting it into a Script with RunContext = Client in ReplicatedStorage.

ContextActionService BindAction Priorities

local ContextActionService = game:GetService("ContextActionService")

local INPUT_KEY1 = Enum.KeyCode.Q
local INPUT_KEY2 = Enum.KeyCode.E

local function handleThrow(actionName: string, inputState: Enum.UserInputState, inputObject: InputObject)
	if inputState ~= Enum.UserInputState.Begin then
		return Enum.ContextActionResult.Pass
	end
	print(`Action [{actionName}] occurred. KeyCode [{inputObject.KeyCode}] pressed.`)

	return Enum.ContextActionResult.Sink
end

local function handlePunch(actionName: string, inputState: Enum.UserInputState, inputObject: InputObject)
	if inputState ~= Enum.UserInputState.Begin then
		return Enum.ContextActionResult.Pass
	end
	print(`Action [{actionName}] occurred. KeyCode [{inputObject.KeyCode}] pressed.`)

	return Enum.ContextActionResult.Sink
end

-- Without specifying priority, the most recently bound action is called first,
-- so pressing INPUT_KEY1 prints "Punch" and then sinks the input.
ContextActionService:BindAction("DefaultThrow", handleThrow, false, INPUT_KEY1)
ContextActionService:BindAction("DefaultPunch", handlePunch, false, INPUT_KEY1)

-- Here we bind both functions in the same order as above, but with explicitly swapped priorities.
-- That is, we give "Throw" a higher priority of 2 so it will be called first,
-- despite "Punch" still being bound more recently.
-- Pressing INPUT_KEY2 prints "Throw" and then sinks the input.
ContextActionService:BindActionAtPriority("PriorityThrow", handleThrow, false, 2, INPUT_KEY2)
ContextActionService:BindActionAtPriority("PriorityPunch", handlePunch, false, 1, INPUT_KEY2)

BindActivate

()

綁定一個 Enum.KeyCode 可以使用 Enum.UserInputType 來啟用 ClickDetector 事件、Tools 和 GuiButtons 。當指定的鍵/按鈕按下時,會發射Mouse.Button1Down事件到鼠標傳送到Tool.Equipped。這會引發 Tool.Activated 事件，如果 Tool.ManualActivationOnly 未設為真值。對於遊戲手柄輸入，此功能由預設控制腳本呼叫，以便綁定按鈕 R2 Enum.KeyCode 。

請注意，指定的 Enum.UserInputType 必須是 Keyboard 或 Gamepad1 通過 Gamepad8 才能有效。

參數

userInputTypeForActivation: Enum.UserInputType

必須是鍵盤或遊戲控制器1通過遊戲控制器8。

預設值：""

keyCodesForActivation: Tuple

預設值：""

()

GetAllBoundActionInfo

GetAllBoundActioninfo 返回一個表，將所有行動的名稱 (原本傳送到 BindAction ) 映射到由 GetBoundActionInfo 返回的表，當以行動名稱本身呼叫時。使用此功能，您可以檢查所有目前已綁定的行動。在檢查優先級或堆疊命令時，這很有用。

GetBoundActionInfo

GetBoundActionInfo 返回包含以下鑰匙的表，描述綁定的行動給予其名稱。要一次獲得所有行動的相同資訊，請使用 GetAllBoundActionInfo 。


<th>類型</th>

  <th>說明</th>
</tr>

<tr>
  <td><code>堆疊順序</code></td><td>數量</td>

  <td>
    描述堆疊上的動作指數(增加)
  </td>
</tr>

<tr>
  <td><code>優先級</code> \*</td>   <td>數量</td>

  <td>
    描述行動作的 <code>Class.ContextActionService:BindActionAtPriority()|priority</code> 等級
  </td>
</tr>

<tr>
  <td><code>創建觸摸按鈕</code></td><td>bool</td>

  <td>
    描述是否應在 <code>Class.UserInputService.TouchEnabled|TouchEnabled</code> 設備上創建觸摸按鈕
  </td>
</tr>

<tr>
  <td><code>輸入類型</code></td>  <td>表</td>

  <td>
    傳送到 <code>Class.ContextActionService:BindAction()|BindAction</code> 的輸入類型，此動作將因此而發生
  </td>
</tr>

<tr>
  <td><code>說明</code> †</td><td>字串</td>

  <td>
    由 <code>Class.ContextActionService:SetDescription()|SetDescription</code> 設置的行動說明
  </td>
</tr>

<tr>
  <td><code>標題</code> †</td><td>字串</td>

  <td>
    由 <code>Class.ContextActionService:SetTitle()|SetTitle</code> 設置的動作標題
  </td>
</tr>

<tr>
  <td><code>圖像</code> †</td><td>字串</td>

  <td>
    由 <code>Class.ContextActionService:SetImage()|SetImage 設置的動作動觸發按鈕圖像</code>
  </td>
</tr>

名稱

※優先級仍然會包含，即使BindActionAtPriority未使用 - 默認值為 2000。

† 指示此欄位將是 nil 如果相關方法未被呼叫到給定的動作動。

參數

actionName: string

預設值：""