TextSnapshot - Adobe ActionScript® 3 (AS3 ) API 參考

套件	flash.text
類別	public class TextSnapshot
繼承	TextSnapshot Object

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

您可以使用 TextSnapshot 物件，對影片片段中的靜態文字進行處理。舉例來說，您可以使用這些物件，對文字以更高的精確度加以呈現 (相對於動態文字允許的精確度而言)，但在存取文字時仍然採用唯讀方式。

請勿使用建構函式建立 TextSnapshot 物件，該物件是由 flash.display.DisplayObjectContainer.textSnapshot 屬性所傳回。

公用屬性

隱藏繼承公用屬性

顯示繼承公用屬性

	屬性		定義自
		charCount : int [唯讀] TextSnapshot 物件中的字元數。	TextSnapshot
		constructor : Object 類別物件的參照或是特定物件實體的建構函數。	Object

公用方法

隱藏繼承公用方法

顯示繼承公用方法

	方法		定義自
		findText(beginIndex:int, textToFind:String, caseSensitive:Boolean):int 會搜尋指定的 TextSnapshot 物件，並傳回 textToFind 第一次出現的位置 (在 beginIndex 或之後找到)。	TextSnapshot
		getSelected(beginIndex:int, endIndex:int):Boolean 傳回一個 Boolean 值，用來指定 TextSnapshot 物件是否包含了指定範圍中的已選取文字。	TextSnapshot
		getSelectedText(includeLineEndings:Boolean = false):String 會傳回字串，包含由對應的 setSelected() 方法指定的所有字元。	TextSnapshot
		getText(beginIndex:int, endIndex:int, includeLineEndings:Boolean = false):String 會傳回字串，包含由 beginIndex 及 endIndex 參數所指定的所有字元。	TextSnapshot
		getTextRunInfo(beginIndex:int, endIndex:int):Array 傳回物件的陣列，其中包含有關連續文字的資訊。	TextSnapshot
		hasOwnProperty(name:String):Boolean 指出物件是否有已定義的指定屬性。	Object
		hitTestTextNearPos(x:Number, y:Number, maxDistance:Number = 0):Number 可讓您判斷 TextSnapshot 物件中的哪一個字元位於或靠近影片片段 (包含 TextSnapshot 物件中的文字) 的指定 x, y 座標。	TextSnapshot
		isPrototypeOf(theClass:Object):Boolean 指出 Object 類別的實體是否位於指定為參數的物件原型鏈中。	Object
		propertyIsEnumerable(name:String):Boolean 指出指定的屬性是否存在，以及是否可列舉。	Object
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void 為迴圈作業設定動態屬性的可用性。	Object
		setSelectColor(hexColor:uint = 0xFFFF00):void 會在反白標示以 setSelected() 方法選取的字元時，指定要使用的顏色。	TextSnapshot
		setSelected(beginIndex:int, endIndex:int, select:Boolean):void 會在 TextSnapshot 物件中指定字元範圍，以選取或取消選取該範圍。	TextSnapshot
		toLocaleString():String 傳回代表此物件的字串，根據地區特定慣例進行格式化。	Object
		toString():String 會傳回指定之物件的字串形式。	Object
		valueOf():Object 會傳回指定之物件的基本值。	Object

屬性詳細資訊

charCount

屬性

charCount:int [唯讀]

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

TextSnapshot 物件中的字元數。

實作
public function get charCount():int

相關 API 元素

flash.text.TextSnapshot.getText()

方法詳細資訊

findText

()

方法

public function findText(beginIndex:int, textToFind:String, caseSensitive:Boolean):int

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

會搜尋指定的 TextSnapshot 物件，並傳回 textToFind 第一次出現的位置 (在 beginIndex 或之後找到)。如果找不到 textToFind，此方法會傳回 -1。

參數

	`beginIndex:int` — 指定要搜尋指定之文字的開始點。

	`textToFind:String` — 指定要搜尋的文字。若您指定的是字串常值，而非字串型態的變數，請將該字串置於引號中。

	`caseSensitive:Boolean` — 會指定文字是否必須符合 `textToFind` 中字串的大小寫。

傳回值

int — 指定之文字第一次出現的索引位置 (從零開始)，或是 -1。

相關 API 元素

flash.text.TextSnapshot.getText()

getSelected

()

方法

public function getSelected(beginIndex:int, endIndex:int):Boolean

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

傳回一個 Boolean 值，用來指定 TextSnapshot 物件是否包含了指定範圍中的已選取文字。

若要搜尋所有字元，請將 0 這個值傳遞給 start，並將 charCount (或任何非常大的數字) 傳遞給 end。若要搜尋單一字元，請將比 start 參數大 1 的值傳遞給 end 參數。

參數

	`beginIndex:int` — 指出要檢查之第一個字元的位置。 `beginIndex` 的有效值是從 `0` 到 `TextSnapshot.charCount - 1`。如果 `beginIndex` 是負值，就會使用 `0`。

	`endIndex:int` — 比要檢查之最後一個字元的索引大 1 的值。 `endIndex` 的有效值是從 `0` 到 `charCount`。索引為 `endIndex` 參數之字元將不會包含在擷取出來的字串之內。如果省略此參數，便會使用 `charCount`。若此值小於或等於 `beginIndex` 的值，則會使用 `beginIndex + 1`。

傳回值

Boolean — Boolean 值，指出是否至少有一個字元在指定的範圍中，由對應的 setSelected() 方法所選取 (true)；否則為 false。

getSelectedText

()

方法

public function getSelectedText(includeLineEndings:Boolean = false):String

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9., Flash Lite 4

傳回字串，包含由對應之 setSelected() 方法指定的所有字元。如果未使用 setSelected() 方法指定任何字元，則會傳回空字串。

如果您將 true 傳遞給 includeLineEndings，新行字元會插入到傳回字串中，且傳回字串可能會比輸入範圍長。如果省略 includeLineEndings 或是對其傳遞 false，則此方法會傳回選取的文字，且不會新增任何字元。

參數

includeLineEndings:Boolean (default = false) — 選擇性的 Boolean 值，指定是否要將換行字元插入傳回字串的適當位置。預設值是 false。

傳回值

String — 字串，包含由對應的 setSelected() 命令指定的所有字元。

getText

()

方法

public function getText(beginIndex:int, endIndex:int, includeLineEndings:Boolean = false):String

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9., Flash Lite 4

傳回字串，包含由 beginIndex 及 endIndex 參數指定的所有字元。如果未選取任何字元，則會傳回空字串。

若要傳回所有字元，請將 0 這個值傳遞給 beginIndex，並將 charCount (或任何非常大的數字) 傳遞給 endIndex。若要傳回單一字元，請將 beginIndex + 1 這個值傳遞給 endIndex。

如果您將 true 這個值傳遞給 includeLineEndings，則換行字元會插入傳回字串的適當位置。在此情況下，傳回字串的長度可能會大於輸入範圍。若 includeLineEndings 是 false 或是遭到省略，則會傳回並未加入任何字元之已選取文字。

參數

	`beginIndex:int` — 指出要包含在傳回字串中之第一個字元的位置。 `beginIndex` 的有效值是從 `0` 到 `charCount - 1`。如果 `beginIndex` 是負值，就會使用 `0`。

	`endIndex:int` — 比要檢查之最後一個字元的索引大 1 的值。 `endIndex` 的有效值是從 `0` 到 `charCount`。索引為 `endIndex` 參數之字元將不會包含在擷取出來的字串之內。如果省略此參數，便會使用 `charCount`。若此值小於或等於 `beginIndex` 的值，則會使用 `beginIndex + 1`。

	`includeLineEndings:Boolean` (default = `false`) — 選擇性的 Boolean 值，指定要在傳回字串中插入 (`true`) 或不插入 (`false`) 新行字元。預設值是 `false`。

傳回值

String — 字串，包含指定範圍中的字元，或是空字串 (如果指定範圍中找不到任何字元)。

getTextRunInfo

()

方法

public function getTextRunInfo(beginIndex:int, endIndex:int):Array

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9, Flash Lite 4

傳回物件的陣列，其中包含有關連續文字的資訊。每個物件都對應到由兩個方法參數所指定的字元範圍中的一個字元。

注意： 使用 getTextRunInfo() 方法，即可傳回大範圍文字的大型物件。 Adobe 建議您限制由 beginIndex 及 endIndex 參數定義的文字範圍。

參數

	`beginIndex:int` — TextSnapshot 物件中，字元範圍內第一個字元的索引值。

	`endIndex:int` — TextSnapshot 物件中，字元範圍內最後一個字元的索引值。

傳回值

Array — 物件的陣列，其中每個物件都包含字元範圍 (由 beginIndex 及 endIndex 參數指定) 中特定字元的相關資訊。每個物件都包含下列十一個屬性：

indexInRun -- 字元之從零開始的整數索引 (相對於整個字串而言，而非選取的連續文字)。
selected -- Boolean 值，true 表示已選取字元；否則為 false。
font -- 字元的字體名稱。
color -- 字元的混合 Alpha 及顏色值。前兩個十六進位數代表 Alpha 值，其餘的位數則代表顏色值。
height -- 字元的高度，以像素為單位。
matrix_a、matrix_b、matrix_c、matrix_d、matrix_tx 與 matrix_ty -- 矩陣的值，定義字元的幾何變形。一般來說不管文字的高度為何，向上文字一律會有 [1 0 0 1 x y] 格式的矩陣，其中 x 及 y 是父影片片段內字元的位置。矩陣位於父影片片段的座標系統中，且不包含任何可在影片片段本身 (或它的父輩) 存在的變形。
corner0x、corner0y、corner1x、corner1y、corner2x、corner2y、corner3x 與 corner3y -- 字元的範圍框角落，視父影片片段的座標系統而定。只有在字元使用的字體內嵌於 SWF 檔中，才可以使用這些值。

相關 API 元素

Matrix 類別

hitTestTextNearPos

()

方法

public function hitTestTextNearPos(x:Number, y:Number, maxDistance:Number = 0):Number

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9., Flash Lite 4

可讓您判斷 TextSnapshot 物件中的哪一個字元位於或靠近影片片段 (包含 TextSnapshot 物件中的文字) 的指定 x, y 座標。

若您省略傳遞給 maxDistance 的值，或是對其傳遞 0 的值，則 x, y 座標所指定的位置必須位於 TextSnapshot 物件的範圍框中。

只有在使用包含字元對照表資訊的字體時，這個方法才能正確運作。不過根據預設，Flash 不會在靜態文字欄位中加入這項資訊。因此，方法可能會傳回 -1 而不是索引值。若要確保傳回的是索引值，您可以迫使 Flash 編寫工具加入字體的字元對照表資訊。若要執行這項作業，請增加一個使用該字體的動態文字欄位，選取該動態文字欄位的「字元選項」，然後指定至少應該要針對一個字元來嵌入字體外框。(您可以指定任何字元，即使是用於靜態文字欄位中的字元，也沒有關係)。

參數

	`x:Number` — 數字，代表包含文字之影片片段的 `x` 座標。

	`y:Number` — 數字，代表包含文字之影片片段的 `y` 座標。

	`maxDistance:Number` (default = `0`) — 選擇性數字，代表與可用來搜尋文字之 `x`, `y` 之間的最大距離。這個距離是從每個字元的中心點測量。預設值為 `0`。

傳回值

Number — 數字，代表最靠近指定之 x, y 座標的字元索引值。如果找不到任何字元，或者如果字體不包含字元對照表資訊，則會傳回 -1。

setSelectColor

()

方法

public function setSelectColor(hexColor:uint = 0xFFFF00):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9., Flash Lite 4

會在反白標示以 setSelected() 方法選取的字元時，指定要使用的顏色。這個顏色永遠是不透明的；您不能指定一個透明度值。

參數

hexColor:uint (default = 0xFFFF00) — 字元周圍邊框使用的顏色，這些字元是由對應的 setSelected() 命令所選取，而顏色會以十六進位格式 (0xRRGGBB) 表示。

相關 API 元素

flash.text.TextSnapshot.setSelected()

setSelected

()

方法

public function setSelected(beginIndex:int, endIndex:int, select:Boolean):void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9., Flash Lite 4

會在 TextSnapshot 物件中指定字元範圍，以選取或取消選取該範圍。已選取的字元背後會繪出一個與該字元之範圍框相符的有色矩形。範圍框的顏色是由 setSelectColor() 定義。

若要選取或取消選取所有字元，請將 0 這個值傳遞給 beginIndex，並將 charCount (或是任何非常大的數字) 傳遞給 endIndex。若要指定單一字元，請將 start + 1 的值傳遞給 endIndex。

因為字元是分別被標示為已選取，因此您可以多次呼叫這個方法，以選取多個字元；換句話說，使用這個方法時，並不會將這個方法先前已經設定的字元取消選取。

有色矩形，指出只會顯示包含字元對照表之字體的選取範圍。根據預設，Flash 不會在靜態文字欄位加入這項資訊。在某些情況下，這項行為表示已選取的文字不會在螢幕上顯示為已選取。若要確保所有選取的文字已確實選取，您可以迫使 Flash 編寫工具加入字體的字元對照表資訊。若要執行這項作業，請增加一個使用該字體的動態文字欄位，選取該動態文字欄位的「字元選項」，然後指定至少應該要針對一個字元來嵌入字體外框。您可以指定任何字元，即使是用於靜態文字欄位中的字元，也沒有關係。

參數

	`beginIndex:int` — 指出要選取之第一個字元的位置。 `beginIndex` 的有效值是從 `0` 到 `charCount - 1`。如果 `beginIndex` 是負值，就會使用 `0`。

	`endIndex:int` — 整數，其值為 1 + 要檢查之最後一個字元的索引。 `end` 的有效值是從 `0` 到 `charCount`。索引為 `end` 參數之字元將不會包含在擷取出來的字串之內。如果略過此參數，則會使用 `TextSnapshot.charCount`。若 `beginIndex` 的值小於或等於 `endIndex` 的值，則會使用 `beginIndex + 1`。

	`select:Boolean` — Boolean 值，指定應該 (`true`) 或不應該 (`false`) 選取文字。

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

TextSnapshot - AS3

套件x

語言元素

附錄

套件 flash.text

charCount

findText

getSelected

getSelectedText

getText

getTextRunInfo

hitTestTextNearPos

setSelectColor

setSelected