Set-PSReadLineOption

參考

模組:: PSReadLine

自定義 PSReadLine 中命令行編輯的行為。

語法

Set-PSReadLineOption
   [-EditMode <EditMode>]
   [-ContinuationPrompt <String>]
   [-HistoryNoDuplicates]
   [-AddToHistoryHandler <System.Func[System.String,System.Object]>]
   [-CommandValidationHandler <System.Action[System.Management.Automation.Language.CommandAst]>]
   [-HistorySearchCursorMovesToEnd]
   [-MaximumHistoryCount <Int32>]
   [-MaximumKillRingCount <Int32>]
   [-ShowToolTips]
   [-ExtraPromptLineCount <Int32>]
   [-DingTone <Int32>]
   [-DingDuration <Int32>]
   [-BellStyle <BellStyle>]
   [-CompletionQueryItems <Int32>]
   [-WordDelimiters <String>]
   [-HistorySearchCaseSensitive]
   [-HistorySaveStyle <HistorySaveStyle>]
   [-HistorySavePath <String>]
   [-AnsiEscapeTimeout <Int32>]
   [-PromptText <String[]>]
   [-ViModeIndicator <ViModeStyle>]
   [-ViModeChangeHandler <ScriptBlock>]
   [-Colors <Hashtable>]
   [<CommonParameters>]

Description

Cmdlet Set-PSReadLineOption 會在編輯命令行時自定義 PSReadLine 模組的行為。若要檢視 PSReadLine 設定，請使用 Get-PSReadLineOption。

此命令所設定的選項僅適用於目前的工作階段。若要保存任何選項，請將它們新增至配置檔腳本。如需詳細資訊，請參閱 about_Profiles 和自定義殼層環境。

範例

範例 1：設定前景和背景色彩

本範例會將 PSReadLine 設定為在灰色背景上顯示具有綠色前景文字的批註標記。在範例中使用的逸出序列中， 32 代表前景色彩， 47 代表背景色彩。

Set-PSReadLineOption -Colors @{ "Comment"="$([char]0x1b)[32;47m" }

您可以選擇只設定前景文字色彩。例如，批註標記的亮綠色前景文字色彩："Comment"="$([char]0x1b)[92m"。

範例 2：設定鈴鐺樣式

在此範例中， PSReadLine 會回應需要使用者注意的錯誤或條件。 BellStyle 設定為以 60 毫秒發出 1221 Hz 的聽覺嗶聲。

Set-PSReadLineOption -BellStyle Audible -DingTone 1221 -DingDuration 60

注意

此功能可能無法在平臺上的所有主機上運作。

範例 3：設定多個選項

Set-PSReadLineOption 可以使用哈希表來設定多個選項。

$PSReadLineOptions = @{
    EditMode = "Emacs"
    HistoryNoDuplicates = $true
    HistorySearchCursorMovesToEnd = $true
    Colors = @{
        "Command" = "#8181f7"
    }
}
Set-PSReadLineOption @PSReadLineOptions

哈希表會 $PSReadLineOptions 設定索引鍵和值。 Set-PSReadLineOption 使用的索引鍵和值 @PSReadLineOptions 來更新 PSReadLine 選項。

您可以在 PowerShell 命令列上檢視輸入哈希表名稱 $PSReadLineOptions 的索引鍵和值。

範例 4：設定多個色彩選項

這個範例示範如何在單一命令中設定多個色彩值。

Set-PSReadLineOption -Colors @{
  Command            = 'Magenta'
  Number             = 'DarkGray'
  Member             = 'DarkGray'
  Operator           = 'DarkGray'
  Type               = 'DarkGray'
  Variable           = 'DarkGreen'
  Parameter          = 'DarkGreen'
  ContinuationPrompt = 'DarkGray'
  Default            = 'DarkGray'
}

範例 5：設定多個類型的色彩值

此範例示範三種不同的方法，說明如何設定 PSReadLine 中顯示的標記色彩。

Set-PSReadLineOption -Colors @{
 # Use a ConsoleColor enum
 "Error" = [ConsoleColor]::DarkRed

 # 24 bit color escape sequence
 "String" = "$([char]0x1b)[38;5;100m"

 # RGB value
 "Command" = "#8181f7"
}

範例 6：使用 ViModeChangeHandler 顯示 Vi 模式變更

此範例會發出數據指標變更 VT 逸出，以回應 Vi 模式變更。

function OnViModeChange {
    if ($args[0] -eq 'Command') {
        # Set the cursor to a blinking block.
        Write-Host -NoNewLine "$([char]0x1b)[1 q"
    } else {
        # Set the cursor to a blinking line.
        Write-Host -NoNewLine "$([char]0x1b)[5 q"
    }
}
Set-PSReadLineOption -ViModeIndicator Script -ViModeChangeHandler $Function:OnViModeChange

OnViModeChange 函式會設定 Vi 模式的游標選項：插入和命令。 ViModeChangeHandler 會Function:使用提供者將 OnViModeChange 參考為腳本區塊物件。

如需詳細資訊，請參閱 about_Providers。

範例 7：使用 HistoryHandler 篩選新增至歷程記錄的命令

下列範例示範如何使用 AddToHistoryHandler 來防止將任何 Git 命令儲存至歷程記錄。

$ScriptBlock = {
    Param([string]$line)

    if ($line -match "^git") {
        return $false
    } else {
        return $true
    }
}

Set-PSReadLineOption -AddToHistoryHandler $ScriptBlock

如果命令以開頭git，則 scriptblock 會傳$false回。這與傳SkipAdding回 AddToHistory 列舉的效果相同。如果命令不是以 git開頭，處理程式會 $true 傳回，而 PSReadLine 會將命令儲存在歷程記錄中。

範例 8：在命令執行之前，使用 CommandValidationHandler 來驗證命令

此範例示範如何在執行命令之前，使用 CommandValidationHandler 參數執行驗證命令。此範例會特別使用子命令cmt檢查命令git，並以完整名稱 commit取代該命令。如此一來，您可以建立子命令的速記別名。

# Load the namespace so you can use the [CommandAst] object type
using namespace System.Management.Automation.Language

Set-PSReadLineOption -CommandValidationHandler {
    param([CommandAst]$CommandAst)

    switch ($CommandAst.GetCommandName()) {
        'git' {
            $gitCmd = $CommandAst.CommandElements[1].Extent
            switch ($gitCmd.Text) {
                'cmt' {
                    [Microsoft.PowerShell.PSConsoleReadLine]::Replace(
                        $gitCmd.StartOffset, $gitCmd.EndOffset - $gitCmd.StartOffset, 'commit')
                }
            }
        }
    }
}
# This checks the validation script when you hit enter
Set-PSReadLineKeyHandler -Chord Enter -Function ValidateAndAcceptLine

範例 9：使用 PromptText 參數

當發生剖析錯誤時， PSReadLine 會變更提示紅色的一部分。 PromptText 參數會告訴 PSReadLine 提示字串的一部分，使其成為紅色。

例如，下列範例會建立包含目前路徑的提示，後面接著大於字元（>）和空格。

function prompt { "PS $pwd> " }`
Set-PSReadLineOption -PromptText '> ' # change the '>' character red
Set-PSReadLineOption -PromptText '> ', 'X ' # replace the '>' character with a red 'X'

第一個字串是當發生剖析錯誤時，您想要讓提示字串成為紅色的部分。第二個字串是剖析錯誤時要使用的替代字串。

參數

-AddToHistoryHandler

指定 ScriptBlock ，控制命令新增至 PSReadLine 歷程記錄的方式。

ScriptBlock 會接收命令行做為輸入。

ScripBlock 應該傳回 AddToHistoryOption 列舉的成員、其中一個成員的字串名稱，或布爾值。下列清單描述可能的值及其效果。

MemoryAndFile - 將命令新增至歷程記錄檔和目前的工作階段。
MemoryOnly - 將命令新增至目前會話的歷程記錄。
SkipAdding - 請勿將命令新增至目前工作階段的歷程記錄檔。
$false - 與值 SkipAdding相同。
$true - 與值 MemoryAndFile相同。

類型:	Func<T,TResult>[System.String,System.Object]
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-AnsiEscapeTimeout

當輸入重新導向時，此選項專屬於 Windows，例如，在或screen下tmux執行時。

透過 Windows 上的重新導向輸入，許多索引鍵會以逸出字元開頭的字元序列傳送。無法區分單一逸出字元後面接著更多字元和有效的逸出序列。

假設終端機可以比用戶類型更快傳送字元。 PSReadLine 會先等候此逾時，再結束它收到完整的逸出序列。

如果您在輸入時看到隨機或非預期的字元，您可以調整此逾時。

類型:	Int32
Position:	Named
預設值:	100
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-BellStyle

指定 PSReadLine 如何回應各種錯誤和模棱兩可的情況。

有效值如下：

聽著：一個簡短的嗶聲。
視覺效果：文字會短暫閃爍。
無：沒有意見反應。

類型:	BellStyle
Position:	Named
預設值:	Audible
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Colors

Colors 參數會指定 PSReadLine 所使用的各種色彩。

自變數是哈希表，其中索引鍵會指定元素，而值則指定色彩。如需詳細資訊，請參閱 about_Hash_Tables。

色彩可以是 ConsoleColor 的值，例如 [ConsoleColor]::Red或有效的 ANSI 逸出序列。有效的逸出序列取決於您的終端機。在 PowerShell 5.0 中，紅色文字的範例逸出序列為 $([char]0x1b)[91m。在 PowerShell 6 和更新版本中，相同的逸出序列是 `e[91m。您可以指定其他逸出序列，包括下列類型：

256 色彩
24 位色彩
前景、背景或兩者
反向，粗體

如需 ANSI 色彩代碼的詳細資訊，請參閱維琪百科文章 ANSI 逸出程式碼。

有效的金鑰包括：

ContinuationPrompt：接續提示的色彩。
強調：強調色彩。例如，搜尋歷程記錄時的相符文字。
錯誤：錯誤色彩。例如，在提示字元中。
選取範圍：要反白顯示功能表選取範圍或選取文字的色彩。
預設值：預設令牌色彩。
批註：批註標記色彩。
關鍵詞：關鍵詞標記色彩。
字串：字串標記色彩。
運算子：運算符標記色彩。
變數：變數標記色彩。
命令：命令令牌色彩。
參數：參數令牌色彩。
類型：類型令牌色彩。
數位：數字標記色彩。
成員：成員名稱令牌色彩。

類型:	Hashtable
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-CommandValidationHandler

指定從 ValidateAndAcceptLine 呼叫的 ScriptBlock。如果擲回例外狀況，驗證會失敗，並回報錯誤。

擲回例外狀況之前，驗證處理程式可以將游標放在錯誤點，以便更容易修正。驗證處理程式也可以變更命令行，以更正常見的印刷錯誤。

ValidateAndAcceptLine 可用來避免使用無法運作的命令來雜亂您的歷程記錄。

類型:	Action<T>[CommandAst]
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-CompletionQueryItems

指定顯示而不提示的完成項目數目上限。

如果要顯示的項目數目大於此值， PSReadLine 會在顯示完成專案之前提示 是/否 。

類型:	Int32
Position:	Named
預設值:	100
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ContinuationPrompt

指定輸入多行輸入時，在後續行開頭顯示的字串。預設值為大於符號的雙精度浮點數（>>）。空字串有效。

類型:	String
Position:	Named
預設值:	>>
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-DingDuration

指定當 BellStyle 設定為 Audible 時，嗶聲的持續時間。

類型:	Int32
Position:	Named
預設值:	50ms
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-DingTone

指定當 BellStyle 設定為 Audible 時，嗶聲的音調（Hz）。

類型:	Int32
Position:	Named
預設值:	1221
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-EditMode

指定命令行編輯模式。使用此參數會重設所 Set-PSReadLineKeyHandler設定的任何金鑰系結。

有效值如下：

Windows：金鑰系結會模擬 PowerShell、Cmd 和 Visual Studio。
Emacs：金鑰系結會模擬 Bash 或 Emacs。
Vi：按鍵系結模擬 Vi。

用來 Get-PSReadLineKeyHandler 查看目前設定 之 EditMode 的索引鍵系結。

類型:	EditMode
Position:	Named
預設值:	Windows
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ExtraPromptLineCount

指定額外的行數。

如果您的提示跨越一行以上，請指定此參數的值。當您想要在 PSReadLine 顯示某些輸出之後顯示提示時，請使用此選項。例如， PSReadLine 會傳回完成清單。

這個選項比舊版 PSReadLine 少，但在使用函式時 InvokePrompt 很有用。

類型:	Int32
Position:	Named
預設值:	0
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-HistoryNoDuplicates

此選項會控制召回行為。重複的命令仍會新增至歷程記錄檔。設定此選項時，只會在叫用命令時出現最新的調用。重複的命令會新增至歷程記錄，以在召回期間保留順序。不過，您通常不想在召回或搜尋歷程記錄時多次看到命令。

根據預設，全域 PSConsoleReadLineOptions 物件的 HistoryNoDuplicates 屬性會設定為 True。若要變更屬性值，您必須指定 SwitchParameter 的值，如下所示：-HistoryNoDuplicates:$False。您可以只使用 SwitchParameter 來-HistoryNoDuplicates設定回 True 。

使用下列命令，您可以直接設定屬性值：

(Get-PSReadLineOption).HistoryNoDuplicates = $False

類型:	SwitchParameter
Position:	Named
預設值:	False
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-HistorySavePath

指定儲存歷程記錄之檔案的路徑。執行 Windows 或非 Windows 平台的電腦會將檔案儲存在不同的位置。檔案名會儲存在變數 $($Host.Name)_history.txt中，例如 ConsoleHost_history.txt。

如果您未使用此參數，預設路徑為：

$env:APPDATA\Microsoft\Windows\PowerShell\PSReadLine\$($Host.Name)_history.txt

類型:	String
Position:	Named
預設值:	A file named $($Host.Name)_history.txt in $env:APPDATA\Microsoft\Windows\PowerShell\PSReadLine on Windows and $env:XDG_DATA_HOME/powershell/PSReadLine or $HOME/.local/share/powershell/PSReadLine on non-Windows platforms
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-HistorySaveStyle

指定 PSReadLine 如何儲存歷程記錄。

有效值如下所示：

SaveIncrementally：執行每個命令後儲存歷程記錄，並在PowerShell的多個實例之間共用。
SaveAtExit:P owerShell 結束時附加歷程記錄檔。
SaveNothing：請勿使用歷程記錄檔。

注意

如果您將 HistorySaveStyle 設定為 SaveNothing ，然後將它設定為SaveIncrementally稍後在同一個會話中，PSReadLine 會儲存先前在會話中執行的所有命令。

類型:	HistorySaveStyle
Position:	Named
預設值:	SaveIncrementally
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-HistorySearchCaseSensitive

指定在 ReverseSearchHistory 或 HistorySearchBackward 等函式中，歷程記錄搜尋會區分大小寫。

根據預設，全域 PSConsoleReadLineOptions 物件的 HistorySearchCaseSensitive 屬性會設定為 False。 使用此 SwitchParameter 會將屬性值設定為 True。若要將屬性值變更回來，您必須指定 SwitchParameter 的值，如下所示：-HistorySearchCaseSensitive:$False。

使用下列命令，您可以直接設定屬性值：

(Get-PSReadLineOption).HistorySearchCaseSensitive = $False

類型:	SwitchParameter
Position:	Named
預設值:	False
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-HistorySearchCursorMovesToEnd

表示游標會使用搜尋，移至您從歷程記錄載入的命令結尾。當此參數設定為 $False時，游標會保留在按下向上或向下箭號時的位置。

根據預設，全域 PSConsoleReadLineOptions 物件的 HistorySearchCursorMovesToEnd 屬性會設定為 False。 使用此 SwitchParameter 會將屬性值設定為 True。若要將屬性值變更回來，您必須指定 SwitchParameter 的值，如下所示：-HistorySearchCursorMovesToEnd:$False。

使用下列命令，您可以直接設定屬性值：

(Get-PSReadLineOption).HistorySearchCursorMovesToEnd = $False

類型:	SwitchParameter
Position:	Named
預設值:	False
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-MaximumHistoryCount

指定要儲存在 PSReadLine 歷程記錄中的命令數目上限。

PSReadLine 歷程記錄與 PowerShell 歷程記錄不同。

類型:	Int32
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-MaximumKillRingCount

指定儲存在終止環中的項目數目上限。

類型:	Int32
Position:	Named
預設值:	10
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-PromptText

此參數會設定 PromptText 屬性的值。預設值是 "> "。

PSReadLine 會分析您的提示函式，以判斷如何只變更部分提示的色彩。此分析不可靠 100%。如果 PSReadLine 以非預期的方式變更您的提示，請使用此選項。包含任何尾端空格符。

此參數的值可以是單一字串或兩個字串的陣列。第一個字串是您想要在剖析錯誤時變更為紅色的提示字串部分。第二個字串是剖析錯誤時要使用的替代字串。

類型:	String[]
Position:	Named
預設值:	>
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ShowToolTips

顯示可能的完成時，工具提示會顯示在完成清單中。

此選項預設為啟用。在舊版 PSReadLine 中，預設不會啟用此選項。若要停用，請將此選項設定為 $False。

根據預設，全域 PSConsoleReadLineOptions 物件的 ShowToolTips 屬性會設定為 True。 使用此 SwitchParameter 會將屬性值設定為 True。若要變更屬性值，您必須指定 SwitchParameter 的值，如下所示：-ShowToolTips:$False。

使用下列命令，您可以直接設定屬性值：

(Get-PSReadLineOption).ShowToolTips = $False

類型:	SwitchParameter
Position:	Named
預設值:	True
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ViModeChangeHandler

當 ViModeIndicator 設定為 Script時，每次模式變更時，都會叫用提供的腳本區塊。腳本區塊會提供類型的 ViMode一個自變數。

此參數是在 PowerShell 7 中引進的。

類型:	ScriptBlock
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ViModeIndicator

此選項會設定目前 Vi 模式的視覺指標。插入模式或命令模式。

有效值如下：

無：沒有指標。
提示：提示會變更色彩。
數據指標：數據指標會變更大小。
文稿：列印使用者指定的文字。

類型:	ViModeStyle
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-WordDelimiters

指定為 ForwardWord 或 KillWord 等函式分隔文字的字元。

類型:	String
Position:	Named
預設值:	;:,.[]{}()/\\|^&*-=+'"---
必要:	False
接受管線輸入:	False
接受萬用字元:	False

輸入

None

您無法使用管線將物件傳送至此 Cmdlet。

輸出

None

此 Cmdlet 不會傳回任何輸出。

共用方式為

Set-PSReadLineOption

語法

Description

範例

範例 1：設定前景和背景色彩

範例 2：設定鈴鐺樣式

範例 3：設定多個選項

範例 4：設定多個色彩選項

範例 5：設定多個類型的色彩值

範例 6：使用 ViModeChangeHandler 顯示 Vi 模式變更

範例 7：使用 HistoryHandler 篩選新增至歷程記錄的命令

範例 8：在命令執行之前，使用 CommandValidationHandler 來驗證命令

範例 9：使用 PromptText 參數

參數

-AddToHistoryHandler

-AnsiEscapeTimeout

-BellStyle

-Colors

-CommandValidationHandler

-CompletionQueryItems

-ContinuationPrompt

-DingDuration

-DingTone

-EditMode

-ExtraPromptLineCount

-HistoryNoDuplicates

-HistorySavePath

-HistorySaveStyle

-HistorySearchCaseSensitive

-HistorySearchCursorMovesToEnd

-MaximumHistoryCount

-MaximumKillRingCount

-PromptText

-ShowToolTips

-ViModeChangeHandler

-ViModeIndicator

-WordDelimiters

輸入

輸出

相關連結

其他資源