ContextActionService

方法

BindAction(actionName : string,functionToBind : function,createTouchButton : bool,inputTypes : Tuple):void
將使用者輸入綁定到一個行動處理功能。
BindActionAtPriority(actionName : string,functionToBind : function,createTouchButton : bool,priorityLevel : number,inputTypes : Tuple):void
行為像 BindAction 但也允許優先權被分配至綁定的動作對於交叉輸入類型 (更高的前提)。
BindActivate(userInputTypeForActivation : Enum.UserInputType,keyCodesForActivation : Tuple):void
將 Class.Tool.Activation 和 1> Class.ClickDetector1> 事件綁定到一起，以啟動 4> Class.Tool.Activation4> 和 7>Class.ClickDetector7> 事件。
GetAllBoundActionInfo():Dictionary
取得所有綁定操作的資訊表 (鍵是傳送到 BindAction 的名稱，值是由 GetBoundActionInfo 來調用時的表)。
GetBoundActionInfo(actionName : string):Dictionary
取得一個名為 BindAction 的表，其內容包含原來傳送至 Class.ContextActionService:BindAction()|BindAction 的資訊。
GetCurrentLocalToolIcon():string
將 BackpackItem.TextureId 的 Tool 返回 equipped 的 2>Class.Tool.Equipped|equipped2> 。
SetDescription(actionName : string,description : string):void
提供一個有觸摸按鈕的關聯動作的名稱，設置動作的說明。
SetImage(actionName : string,image : string):void
如果 actionName 鍵包含一個綁定操動作，則 image 設為碰觸按鈕的圖像。
SetPosition(actionName : string,position : UDim2):void
提供一個有觸摸按鈕的關聯動作的名稱，設定按鈕在 ContextButtonFrame 中的位置。
SetTitle(actionName : string,title : string):void
提供一個有觸摸按鈕的關聯動作的名稱，設定按鈕上顯示的文字。
UnbindAction(actionName : string):void
從輸入中取消行動的綁定。
UnbindActivate(userInputTypeForActivation : Enum.UserInputType,keyCodeForActivation : Enum.KeyCode):void
將 Enum.KeyCode 與特定 Enum.UserInputType 從 Tool.Activation 中解除綁定時，發生錯誤。
UnbindAllActions():void
移除所有綁定功能。所有 actionNames 將不會剩餘。所有 touch 按鈕將被移除。
GetButton(actionName : string):Instance
暫停
取回 ImageButton 的 Class.ContextActionService:BindAction()|bound 行動，該行動有一個已建立的觸輸入按鈕。

活動

LocalToolEquipped(toolEquipped : Instance):RBXScriptSignal
發射當前玩家裝備 Tool 時。
LocalToolUnequipped(toolUnequipped : Instance):RBXScriptSignal
發生當前玩家卸下 Tool 時。

屬性

方法

BindAction

void

將一個行動綁定給指定的使用者輸入的行動處

下面的代碼示例顯示了如何使用 Sound 來在 played 鍵 ( H ) 、遊戲控制器按鈕或觸摸屏幕按鈕時按下。


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")

行動處理器參數

動作處理器會以下參數來啟動：


<tr>
  <td>1</td>
  <td><code>字串</code></td>
  <td>與原始傳入 BindAction 的相同串</td>
</tr>

<tr>
  <td>2</td>
  <td><code>枚列使用者輸入狀態</code></td>
  <td>輸入狀態 (開始、變更、結束或取消)\*</td>
</tr>

<tr>
  <td>3</td>
  <td><code>輸入對象</code></td>
  <td>一個包含輸入資訊的對象(視乎使用者輸入類型而異)</td>
</tr>

類型

說明

※這允許一個功能處理多個操作，如有需要。*取消是發生在有輸入進行中，或是在有輸入和其他操作綁定在進行中，或是有進度操作綁定在進行中，或是有進度操作綁定在進行中，或是有進度操作綁定在進行中，或是有進度操作綁定在進行中，或是有進度操作綁定在進行中，或是有進度操作綁定在進行中，或是有進度操

動作綁定堆疊

觸摸按鈕

除了輸入類型外，此功能的第三個參數控制按鈕是否為 Class.UserInputService.TouchEnabled|TouchEnabled

參數

actionName: string

代表要執行的動作的字串(例如「HonkHorn」或「OpenDoor」)。

functionToBind: function

當綁定輸入啟動時，會呼叫以下參數：string (actionName)、Enum.UserInputState 和輸入對象。

createTouchButton: bool

是否需要為觸摸輸入設備創建按鈕。

inputTypes: Tuple

任何數字的 Enum.KeyCode 或 Enum.UserInputType 代表輸入以綁定操動作。

void

範例程式碼

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

void

BindActionAtPriority 與 BindAction 相似，但也允許指定優先權。如果多個操作綁定到同一個輸入，則優先權高度函數無視不同操作的訂單。在其他 words，這個函數會重新定義 BindAction 的預期行為。

參數

actionName: string

代表要執行的動作的字串(例如「HonkHorn」或「OpenDoor」)。

functionToBind: function

當綁定輸入啟動時，會呼叫以下參數：string (actionName)、Enum.UserInputState 和輸入對象。

createTouchButton: bool

是否需要為觸摸輸入設備創建按鈕。

priorityLevel: number

行動應該綁定的優先級等級(最高值在下方)。

inputTypes: Tuple

任何數字的 Enum.KeyCode 或 Enum.UserInputType 代表輸入以綁定到操動作。

void

範例程式碼

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

void

將 Enum.KeyCode 綁定到 Enum.UserInputType 使用 ClickDetector 事件，2> Class.Tool|Tools2> 和 5> Class.GuiButton|GuiButtons

注意，Enum.UserInputType 指定必須為 Keyboard 或 Gamepad1 通過 1>Gamepad81> 以獲得有效。

參數

userInputTypeForActivation: Enum.UserInputType

必須是鍵盤或 Gamepad1 通過 Gamepad8。

keyCodesForActivation: Tuple

void

GetAllBoundActionInfo

GetAllBindActioninfo 返回一個表，其中將所有行動的名稱 (原來傳送至 Class.ContextActionService:BindAction()|BindAction) 映射到表 (使用此函數時，您可以檢查所有正在綁定的行動) 返回 Class.ContextActionService:GetBindActionInfo()|GetBindAction 時。使用此功能，您可以檢查所有現

GetBoundActionInfo

GetBoundActionInfo 返回一個包含以下鍵描述鍵定義的動作的表。要獲得所有動作的相同資訊，請使用 GetAllBoundActionInfo 。


<tr>
  <td><code>stackOrder</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>boolean</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>
    Class.ContextActionService:SetDescription()|SetDescription的描述
  </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>
    Class.ContextActionService:SetImage()|SetImage 設定的動作按鈕圖像
  </td>
</tr>

名稱

類型

說明

※優先級等級仍會包含，即使 BindActionAtPriority 未使用 - 預設為 2000。

※ 指示此欄位將會是 nil 如果沒有呼叫指定的動作法。

參數

actionName: string