ContextMenu

套件	flash.ui
類別	public final class ContextMenu
繼承	ContextMenu NativeMenu EventDispatcher Object

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9

ContextMenu 類別提供了對快顯選單中所顯示項目的控制。

行動裝置瀏覽器支援：行動裝置瀏覽器不支援此類別。

AIR 描述檔支援：行動裝置或 AIR for TV 裝置不支援此功能。如需有關跨多個描述檔之 API 支援的詳細資訊，請參閱 AIR 描述檔支援。

在 Flash Player 中，使用者可以按一下滑鼠右鍵 (Windows 或 Linux) 或 Control+按一下 (Macintosh) 開啟快顯選單。您可使用 ContextMenu 類別的方法和屬性來新增自訂的選單項目、控制內建快顯選單項目的顯示 (例如，「放大顯示」和「列印」) 或建立選單的副本。在 AIR 中並沒有內建項目，也未提供標準快顯選單。

在 Flash Professional 中，您可將 ContextMenu 物件附加到特定的按鈕、影片片段、文字欄位物件或附加到整個影片的層級。使用 InteractiveObject 類別的 contextMenu 屬性來做到這點。

在 Flex 或 Flash Builder 中，只有應用程式的最上層組件可以有快顯選單。例如，如果 DataGrid 控制項是 TabNavigator 或 VBox 容器的子系，則 DataGrid 控制項無法擁有它自己的快顯選單。

若要將新的項目加入 ContextMenu 物件中，請先建立 ContextMenu 物件，然後將該物件加入 ContextMenu.customItems 陣列。如需有關建立快顯選單項目的詳細資訊，請參閱 ContextMenuItem 類別項目。

Flash Player 有三種快顯選單的類型：標準選單 (會在 Flash Player 中按滑鼠右鍵時出現)、編輯選單 (會在可選取或可編輯的文字欄位上方按一下滑鼠右鍵時出現)，以及錯誤選單 (會在 SWF 檔載入至 Flash Player 失敗時出現)。只有標準選單和編輯選單才能使用 ContextMenu 類別來修改。AIR 僅提供編輯選單。

自訂選單的項目永遠會出現在 Flash Player 快顯選單的最上方，並且會在所有可見的內建選單項目上方；可用分隔列來區別內建和自訂的選單項目。您無法從快顯選單中移除「設定」選單項目。 Flash 需要「設定」選單項目，以便讓使用者存取影響其電腦上私用與儲存方面的設定。您也無法從快顯選單移除「關於」選單，這個必要的選單可讓使用者找出目前使用的 Flash Player 版本資訊 (AIR 並無內建「設定」與「關於」選單項目)。

在 Flash Player 的快顯選單中，最多只能加入 15 個自訂項目。AIR 則未明確限制快顯選單的項目個數。

在呼叫 ContextMenu 物件的方法以前，您必須先使用 ContextMenu() 建構函式來建立該物件。

檢視範例

公用屬性

隱藏繼承公用屬性

顯示繼承公用屬性

	屬性		定義自
		builtInItems : ContextMenuBuiltInItems 具有下列屬性的 ContextMenuBuiltInItems 類別實體：forwardAndBack、loop、play、print、quality、rewind、save 和 zoom。	ContextMenu
		clipboardItems : ContextMenuClipboardItems 具有下列屬性的 ContextMenuClipboardItems 類別實體：cut、copy、paste、delete、selectAll。	ContextMenu
		clipboardMenu : Boolean 指定是否應該使用剪貼簿選單。	ContextMenu
		constructor : Object 類別物件的參照或是特定物件實體的建構函數。	Object
		customItems : Array ContextMenuItem 物件的陣列。	ContextMenu
		isSupported : Boolean [靜態] [唯讀] 如果目前的平台支援 ContextMenu 類別，則 isSupported 屬性會設為 true，否則會設為 false。	ContextMenu
		items : Array [覆寫] 此選單中的自訂項目陣列。	ContextMenu
		link : URLRequest 連結的 URLRequest。	ContextMenu
		numItems : int [覆寫] [唯讀] 此選單中的項目數目。	ContextMenu
		parent : NativeMenu [唯讀] 父選單。	NativeMenu

公用方法

隱藏繼承公用方法

顯示繼承公用方法

	方法		定義自
		ContextMenu() 會建立 ContextMenu 物件。	ContextMenu
		addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void 會在 EventDispatcher 物件註冊事件偵聽程式，以便讓偵聽程式收到事件的通知。	EventDispatcher
		addItem(item:NativeMenuItem):NativeMenuItem 將選單項目加入至選單底部。	NativeMenu
		addItemAt(item:NativeMenuItem, index:int):NativeMenuItem [覆寫] 將選單項目加入至選單底部。	ContextMenu
		addSubmenu(submenu:NativeMenu, label:String):NativeMenuItem 插入新的選單項目以便將子選單加入至選單。	NativeMenu
		addSubmenuAt(submenu:NativeMenu, index:int, label:String):NativeMenuItem 將新的選單項目插入指定位置，以便將子選單加入選單。	NativeMenu
		clone():NativeMenu [覆寫] 建立指定之 ContextMenu 物件的副本。	ContextMenu
		containsItem(item:NativeMenuItem):Boolean [覆寫] 報告此選單是否包含指定的選單項目。	ContextMenu
		dispatchEvent(event:Event):Boolean 會將事件傳送到事件流程。	EventDispatcher
		display(stage:Stage, stageX:Number, stageY:Number):void [覆寫] 在指定位置彈出此選單。	ContextMenu
		getItemAt(index:int):NativeMenuItem [覆寫] 取得指定索引位置的選單項目。	ContextMenu
		getItemByName(name:String):NativeMenuItem 取得指定名稱的選單項目。	NativeMenu
		getItemIndex(item:NativeMenuItem):int [覆寫] 取得指定項目的位置。	ContextMenu
		hasEventListener(type:String):Boolean 會檢查 EventDispatcher 物件是否有對特定的事件類型註冊偵聽程式。	EventDispatcher
		hasOwnProperty(name:String):Boolean 指出物件是否有已定義的指定屬性。	Object
		hideBuiltInItems():void 會將指定之 ContextMenu 物件中所有的內建選單項目隱藏起來 (「設定」除外)。	ContextMenu
		isPrototypeOf(theClass:Object):Boolean 指出 Object 類別的實體是否位於指定為參數的物件原型鏈中。	Object
		propertyIsEnumerable(name:String):Boolean 指出指定的屬性是否存在，以及是否可列舉。	Object
		removeAllItems():void [覆寫] 移除選單的所有項目。	ContextMenu
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void 會從 EventDispatcher 物件移除偵聽程式。	EventDispatcher
		removeItem(item:NativeMenuItem):NativeMenuItem 移除特定選單項目。	NativeMenu
		removeItemAt(index:int):NativeMenuItem [覆寫] 移除並傳回位於指定索引位置的選單項目。	ContextMenu
		setItemIndex(item:NativeMenuItem, index:int):void 將選單項目移至指定位置。	NativeMenu
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void 為迴圈作業設定動態屬性的可用性。	Object
		toLocaleString():String 傳回代表此物件的字串，根據地區特定慣例進行格式化。	Object
		toString():String 會傳回指定之物件的字串形式。	Object
		valueOf():Object 會傳回指定之物件的基本值。	Object
		willTrigger(type:String):Boolean 檢查此 EventDispatcher 物件是否已註冊事件偵聽程式，或者此物件的任何祖系已為特定事件類型註冊事件偵聽程式。	EventDispatcher

事件

按一下以瞭解事件的詳細資訊

隱藏繼承事件

顯示繼承事件

	摘要	定義自
activate	[廣播事件] 當 Flash Player 或 AIR 應用程式取得作業系統焦點並成為作用中時傳送。	EventDispatcher
deactivate	[廣播事件] 當 Flash Player 或 AIR 應用程式失去作業系統焦點並成為非作用中時傳送。	EventDispatcher
displaying	在顯示選單之前，由此 NativeMenu 物件立即傳送。	NativeMenu
menuSelect	會在使用者第一次產生快顯選單，但是在快顯選單的內容顯示之前傳送。	ContextMenu
preparing	在按下對等按鍵但尚未顯示選單之前，會由 NativeMenu 物件傳送。	NativeMenu
select	在選取了所屬的任何一個選單項目或是所屬子選單後代 (任何一個) 中的某個項目時，由此 NativeMenu 物件傳送。	NativeMenu

屬性詳細資訊

builtInItems

屬性

builtInItems:ContextMenuBuiltInItems

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9

具有下列屬性的 ContextMenuBuiltInItems 類別實體：forwardAndBack、loop、play、print、quality、rewind、save 和 zoom。將這些屬性設定為 false，便會從指定的 ContextMenu 物件中移除對應的選單項目。這些屬性是可列舉的，且預設會設定為 true。

注意：AIR 中的快顯選單不具有內建項目。

實作
public function get builtInItems():ContextMenuBuiltInItems
public function set builtInItems(value:ContextMenuBuiltInItems):void

clipboardItems

屬性

clipboardItems:ContextMenuClipboardItems

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 10, AIR 1.5

具有下列屬性的 ContextMenuClipboardItems 類別實體：cut、copy、paste、delete、selectAll。將其中一個屬性設定為 false 會停用剪貼簿選單中的對應項目。

實作
public function get clipboardItems():ContextMenuClipboardItems
public function set clipboardItems(value:ContextMenuClipboardItems):void

相關 API 元素

ContextMenuClipboardItems 類別

範例 ( 如何使用本範例 )

下列範例會示範 ContextMenu 物件之 clipboardItems 屬性的用法。建立 ContextMenu 並將其 clipboardMenu 屬性設定為 true。加入 MENU_SELECT (通常是按一下右鍵) 事件的事件處理常式，並將選單指定給顯示物件。在這種情況下，copy 和 paste 選單會啟用。

package {
    import flash.ui.ContextMenu;
    import flash.events.ContextMenuEvent;
    import flash.display.Sprite;

    public class ContextMenuClipboardItemsExample extends Sprite {
        public function ContextMenuClipboardItemsExample() {
            var myContextMenu:ContextMenu = new ContextMenu();
            myContextMenu.clipboardMenu = true;
            myContextMenu.addEventListener(ContextMenuEvent.MENU_SELECT, menuSelectHandler);
            var rc:Sprite = new Sprite();
            rc.graphics.beginFill(0xDDDDDD);
            rc.graphics.drawRect(0,0,100,30);
            addChild(rc);
            rc.contextMenu = myContextMenu;
        }
        function menuSelectHandler(event:ContextMenuEvent):void {
            event.contextMenuOwner.contextMenu.clipboardItems.copy = true;
            event.contextMenuOwner.contextMenu.clipboardItems.paste = true;
        }
    }
}

clipboardMenu

屬性

clipboardMenu:Boolean

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 10, AIR 1.5

指定是否應該使用剪貼簿選單。如果這個值是 true，clipboardItems 屬性就會判斷剪貼簿選單上啟用或停用哪些項目。

如果 link 屬性不是 null，將會忽略這個 clipBoardMenu 屬性。

實作
public function get clipboardMenu():Boolean
public function set clipboardMenu(value:Boolean):void

customItems

屬性

customItems:Array

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9

ContextMenuItem 物件的陣列。陣列中的每個物件都代表一個您所定義的快顯選單項目。請使用這個屬性來新增、移除或修改這些自訂選單項目。

若要加入新的選單項目，您要建立 ContextMenuItem 物件，然後將其加入 customItems 陣列 (例如，使用 Array.push())。如需有關建立選單項目的詳細資訊，請參閱 ContextMenuItem 類別項目。

實作
public function get customItems():Array
public function set customItems(value:Array):void

isSupported

屬性

isSupported:Boolean [唯讀]

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 10.1, AIR 2

如果目前的平台支援 ContextMenu 類別，則 isSupported 屬性會設為 true，否則會設為 false。

實作
public static function get isSupported():Boolean

items

屬性

items:Array[覆寫]

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0

此選單中的自訂項目陣列。

使用此屬性就相當於使用 customItems 屬性。此陣列是依照顯示順序來排序。

實作
override public function get items():Array
override public function set items(value:Array):void

link

屬性

link:URLRequest

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 10, AIR 1.5

連結的 URLRequest。如果這個屬性為 null，就會顯示一般快顯選單。如果這個屬性不是 null，就會顯示連結快顯選單，而且將會在指定的 url 上運作。

如果指定了 link，則會忽略 clipboardMenu 屬性。

預設值為 null。

實作
public function get link():URLRequest
public function set link(value:URLRequest):void

numItems

屬性

numItems:int [唯讀] [覆寫]

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0

此選單中的項目數目。

實作
override public function get numItems():int

建構函式詳細資料

()

建構函式

public function ContextMenu()

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9

會建立 ContextMenu 物件。

方法詳細資訊

addItemAt

()

方法

override public function addItemAt(item:NativeMenuItem, index:int):NativeMenuItem

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0

將選單項目加入至選單底部。

建立快顯選單時，您可以加入 NativeMenuItem 或 ContextMenuItem 物件。不過，建議整個快顯選單只用一種物件類型，以確保選單中的所有項目具有相同的屬性。

參數

	`item:NativeMenuItem` — 要加入選單底端的項目。

	`index:int`

傳回值

NativeMenuItem

擲回值

	`ArgumentError` — 如果 `item` 為 `null`。

	`ArgumentError` — 如果 `item` 是另一個選單的成員。

clone

()

方法

override public function clone():NativeMenu

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9

建立指定之 ContextMenu 物件的副本。副本會繼承原始選單物件的所有屬性。

傳回值

NativeMenu — 具有原始選單物件之所有屬性的 ContextMenu 物件。

containsItem

()

方法

override public function containsItem(item:NativeMenuItem):Boolean

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0

報告此選單是否包含指定的選單項目。

參數

item:NativeMenuItem — 要尋找的項目。

傳回值

Boolean — true 表示 item 位於此選單中。

display

()

方法

override public function display(stage:Stage, stageX:Number, stageY:Number):void

執行階段版本:

AIR 1.0

在指定位置彈出此選單。

注意：在 Flash Player 中不支援此方法。

參數

	`stage:Stage` — 要在其中顯示此選單的 Stage 物件。

	`stageX:Number` — 水平像素數 (相對於舞台的原點，此選單將在這個位置出現)。

	`stageY:Number` — 垂直像素數 (相對於舞台的原點，此選單將在這個位置出現)。

getItemAt

()

方法

override public function getItemAt(index:int):NativeMenuItem

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0

取得指定索引位置的選單項目。

參數

index:int — 要傳回之項目的 (從零開始) 位置。

傳回值

NativeMenuItem — 位於選單中指定之位置的項目。

擲回值

RangeError — 如果 index 超出此選單之 items 陣列的邊界。

getItemIndex

()

方法

override public function getItemIndex(item:NativeMenuItem):int

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0

取得指定項目的位置。

參數

item:NativeMenuItem — 要尋找的 NativeMenuItem 物件。

傳回值

int — 此選單中指定之項目的 (從零開始) 位置，如果選單中沒有該項目則為 -1。

hideBuiltInItems

()

方法

public function hideBuiltInItems():void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9

會將指定之 ContextMenu 物件中所有的內建選單項目隱藏起來 (「設定」除外)。如果正在執行 Flash Player 的除錯程式版本，儘管對並未啟用遠端除錯功能的 SWF 檔而言，該選單項目將會變成灰色，但「除錯」選單項目仍會出現。

這個方法只會隱藏出現在標準快顯選單內的選單項目，而不會影響出現在編輯和錯誤選單中的項目。

這個方法的作業方式是將 my_cm .builtInItems 所有的 Boolean 成員設定為 false。您可以選擇性地使內建項目變成可以看見，做法是將其在 my_cm .builtInItems 中的對應成員設定為 true。

注意：AIR 中的快顯選單不具有內建項目。呼叫此方法將毫無作用。

removeAllItems

()

方法

override public function removeAllItems():void

執行階段版本:

AIR 1.0

移除選單的所有項目。

removeItemAt

()

方法

override public function removeItemAt(index:int):NativeMenuItem

執行階段版本:

AIR 1.0

移除並傳回位於指定索引位置的選單項目。

參數

index:int — 要移除之項目的 (從零開始) 位置。

傳回值

NativeMenuItem — 已移除的 NativeMenuItem 物件。

事件詳細資訊

menuSelect

事件

事件物件類型: flash.events.ContextMenuEvent
屬性 ContextMenuEvent.type = flash.events.ContextMenuEvent.MENU_SELECT

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9

會在使用者第一次產生快顯選單，但是在快顯選單的內容顯示之前傳送。這讓您的程式能在顯示選單之前，先修改快顯選單項目組。使用者可以藉由按一下指向裝置的右鍵以產生快顯選單。

定義 menuSelect 事件物件的 type 屬性值。

這個事件具有下列屬性：

屬性	值
`bubbles`	`false`
`cancelable`	`false`；沒有要取消的預設行為指令。
`contextMenuOwner`	選單所附加至的顯示清單物件。
`currentTarget`	正主動使用事件偵聽程式處理 Event 物件的物件。
`mouseTarget`	使用者在其上按一下右鍵以顯示快顯選單的顯示清單物件。
`target`	將要顯示的 ContextMenu 物件。這個 target 並非永遠都是註冊事件偵聽程式之顯示清單中的物件。請使用 `currentTarget` 屬性，存取目前正在處理該事件之顯示清單中的物件。

範例如何使用本範例

ContextMenuExample.as

下列範例會使用 ContextMenuExample 類別，從舞台移除預設的快顯選單項目，並加入新的選單項目，當按一下此項目時，會改變舞台上的方形顏色。您可以使用下列步驟：

宣告 myContextMenu 屬性，然後將其指定給新的 ContextMenu 物件，再宣告 Sprite 類型的 redRectangle 屬性。
會呼叫 removeDefaultItems() 方法，它會移除「列印」以外的所有內建快顯選單項目。
會呼叫 addCustomMenuItems() 方法，它會使用 Array 的 push() 方法，將名為 Red to Black 選單選擇的選單項目放入 defaultItems 陣列中。 menuItemSelect 事件偵聽程式會加入至 ContextMenuItem 物件，而相關的方法稱為 menuItemSelectHandler()。每當存取此快顯選單並選取 Red to Black 時，這個方法都會使用 trace() 將某些陳述式列印出來。同時移除紅色正方形，並以黑色正方形取代。
會加入 menuSelect 類型的事件偵聽程式，連同關聯的方法 menuSelectHandler，每當開啟快顯選單中的項目時，這個方法都會使用 trace() 將三個陳述式列印出來。
然後 addChildren() 會繪製一個紅色的方形，並將它加入到顯示清單，它就會立刻顯示在此清單中。
最後，會將 myContextMenu 指定給 redRectangle Sprite 的快顯選單，如此一來，只有當滑鼠指標放在方形上方時，才會顯示自訂的快顯選單。

package {
    import flash.ui.ContextMenu;
    import flash.ui.ContextMenuItem;
    import flash.ui.ContextMenuBuiltInItems;
    import flash.events.ContextMenuEvent;
    import flash.display.Sprite;
    import flash.display.Shape;
    import flash.text.TextField;

    public class ContextMenuExample extends Sprite {
        private var myContextMenu:ContextMenu;
        private var menuLabel:String = "Reverse Colors";
        private var textLabel:String = "Right Click";
        private var redRectangle:Sprite;
        private var label:TextField;
        private var size:uint = 100;
        private var black:uint = 0x000000;
        private var red:uint = 0xFF0000;

        public function ContextMenuExample() {
            myContextMenu = new ContextMenu();
            removeDefaultItems();
            addCustomMenuItems();
            myContextMenu.addEventListener(ContextMenuEvent.MENU_SELECT, menuSelectHandler);

            addChildren();
            redRectangle.contextMenu = myContextMenu;
        }

        private function addChildren():void {
            redRectangle = new Sprite();
            redRectangle.graphics.beginFill(red);
            redRectangle.graphics.drawRect(0, 0, size, size);
            addChild(redRectangle);
            redRectangle.x = size;
            redRectangle.y = size;
            label = createLabel();
            redRectangle.addChild(label);
        }

        private function removeDefaultItems():void {
            myContextMenu.hideBuiltInItems();
            var defaultItems:ContextMenuBuiltInItems = myContextMenu.builtInItems;
            defaultItems.print = true;
        }

        private function addCustomMenuItems():void {
            var item:ContextMenuItem = new ContextMenuItem(menuLabel);
            myContextMenu.customItems.push(item);
            item.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, menuItemSelectHandler);
        }

        private function menuSelectHandler(event:ContextMenuEvent):void {
            trace("menuSelectHandler: " + event);
        }

        private function menuItemSelectHandler(event:ContextMenuEvent):void {
            trace("menuItemSelectHandler: " + event);
            var textColor:uint = (label.textColor == black) ? red : black;
            var bgColor:uint = (label.textColor == black) ? black : red;
            redRectangle.graphics.clear();
            redRectangle.graphics.beginFill(bgColor);
            redRectangle.graphics.drawRect(0, 0, size, size);
            label.textColor = textColor;
        }

        private function createLabel():TextField {
            var txtField:TextField = new TextField();
            txtField.text = textLabel;
            return txtField;
        }
    }
}

法律聲明 | 線上隱私權政策

ContextMenu - AS3

套件x

語言元素

附錄

套件 flash.ui

builtInItems

clipboardItems

clipboardMenu

customItems

isSupported

items

link

numItems

ContextMenu

addItemAt

clone

containsItem

display

getItemAt

getItemIndex

hideBuiltInItems

removeAllItems

removeItemAt

menuSelect