Set-PSReadLineOption

参考

模块:: PSReadLine

自定义 PSReadLine 中命令行编辑的行为。

语法

Set-PSReadLineOption
   [-EditMode <EditMode>]
   [-ContinuationPrompt <String>]
   [-HistoryNoDuplicates]
   [-AddToHistoryHandler <System.Func`2[System.String,System.Object]>]
   [-CommandValidationHandler <System.Action`1[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>]
   [-PredictionSource <PredictionSource>]
   [-PredictionViewStyle <PredictionViewStyle>]
   [-Colors <Hashtable>]
   [<CommonParameters>]

说明

编辑 Set-PSReadLineOption 命令行时，cmdlet 自定义 PSReadLine 模块的行为。若要查看 PSReadLine 设置，请使用 Get-PSReadLineOption。

此命令设置的选项仅适用于当前会话。若要保留任何选项，请将它们添加到配置文件脚本。有关详细信息，请参阅 about_Profiles 和自定义 shell 环境。

示例

示例 1：设置前景色和背景色

本示例将 PSReadLine 设置为在灰色背景上显示带有绿色前景文本的 “注释” 标记。在示例中使用的转义序列中， 32 表示前景色， 47 表示背景色。

Set-PSReadLineOption -Colors @{ "Comment"="`e[32;47m" }

可以选择仅设置前景色。例如，注释标记的亮绿色前景色为： "Comment"="`e[92m"。

示例 2：设置铃铛样式

在此示例中， PSReadLine 将响应需要用户注意的错误或条件。 BellStyle 设置为在 1221 Hz 下发出 60 毫秒的可听到的蜂鸣声。

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 "`e[1 q"
    } else {
        # Set the cursor to a blinking line.
        Write-Host -NoNewLine "`e[5 q"
    }
}
Set-PSReadLineOption -ViModeIndicator Script -ViModeChangeHandler $Function:OnViModeChange

OnViModeChange 函数设置 Vi 模式的光标选项：insert 和 command。 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开头，则脚本块将返回 $false 。这与返回 SkipAddingAddToHistory 枚举的效果相同。如果命令不以 git开头，则处理程序返回 $true ，PSReadLine 会将命令保存在历史记录中。

示例 8：在执行命令之前使用 CommandValidationHandler 验证命令

此示例演示如何使用 CommandValidationHandler 参数在执行命令之前运行验证命令。该示例专门检查具有子命令 git 的命令，并将该命令 cmt 替换为全名 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

指定用于控制如何将命令添加到 PSReadLine 历史记录的 ScriptBlock。

ScriptBlock 接收命令行作为输入。

ScripBlock 应返回 AddToHistoryOption 枚举的成员、其中一个成员的字符串名称或布尔值。以下列表描述了可能的值及其效果。

MemoryAndFile - 将命令添加到历史记录文件和当前会话。
MemoryOnly - 仅将命令添加到当前会话的历史记录中。
SkipAdding - 不要将命令添加到当前会话的历史记录文件。
$false - 与值相同 SkipAdding。
$true - 与值相同 MemoryAndFile。

Type:	Func<T,TResult>[System.String,System.Object]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-AnsiEscapeTimeout

当重定向输入时，此选项特定于 Windows，例如，在或 screen下tmux运行时。

使用 Windows 上的重定向输入时，许多键作为从转义字符开始的字符序列发送。无法区分单个转义字符后跟更多字符和有效的转义序列。

假设终端发送字符的速度比用户类型快。 PSReadLine 会等待此超时，然后得出结论，它已收到完整的转义序列。

如果在键入时看到随机或意外字符，可以调整此超时。

Type:	Int32
Position:	Named
Default value:	100
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-BellStyle

指定 PSReadLine 如何响应各种错误和不明确条件。

有效值如下：

可听到：短暂的哔哔声。
视觉对象：文本短暂闪烁。
无：无反馈。

Type:	BellStyle
Position:	Named
Default value:	Audible
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Colors

Colors 参数指定 PSReadLine 使用的各种颜色。

参数是一个哈希表，其中键指定元素，值指定颜色。有关详细信息，请参阅 about_Hash_Tables。

颜色可以是 ConsoleColor 中的值（例如 [ConsoleColor]::Red），也可以是有效的 ANSI 转义序列。有效的转义序列取决于终端。在 PowerShell 5.0 中，红色文本的示例转义序列为 $([char]0x1b)[91m。在 PowerShell 6 及更新版本中，相同的转义序列为 `e[91m。可以指定其他转义序列，包括以下类型：

添加了两个颜色设置以支持在 PSReadLine 2.2.0 中自定义 ListView ：

ListPredictionColor - 设置前导 > 字符和尾随源名称的颜色，例如 [History]。默认情况下，它使用 DarkYellow 作为前景色。
ListPredictionSelectedColor - 设置用于指示已选中列表项的颜色。默认情况下，它使用 DarkBlack 作为背景色。
256 色
24 位颜色
前台和/或背景
反，粗体

有关 ANSI 颜色代码的详细信息，请参阅维基百科文章 ANSI 转义代码。

有效密钥包括：

ContinuationPrompt：继续提示的颜色。
强调：强调颜色。例如，搜索历史记录时匹配的文本。
错误：错误颜色。例如，在提示符中。
选择：用于突出显示菜单选定内容或所选文本的颜色。
默认值：默认标记颜色。
注释：批注标记颜色。
关键字：关键字 (keyword) 标记颜色。
字符串：字符串标记颜色。
运算符：运算符标记颜色。
变量：变量标记颜色。
命令：命令标记颜色。
参数：参数标记颜色。
类型：类型标记颜色。
数字：数字标记颜色。
成员：成员名称标记颜色。
InlinePrediction：预测建议的内联视图的颜色。
ListPrediction：前导 > 字符和预测源名称的颜色。
ListPredictionSelected：列表视图中所选预测的颜色。

Type:	Hashtable
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CommandValidationHandler

指定从 ValidateAndAcceptLine 调用的 ScriptBlock。如果引发异常，则验证失败并报告错误。

在引发异常之前，验证处理程序可以将光标置于错误点，以便更轻松地修复。验证处理程序还可以更改命令行以更正常见的排版错误。

ValidateAndAcceptLine 用于避免无法使用的命令使历史记录混乱。

Type:	Action<T>[CommandAst]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CompletionQueryItems

指定在不提示的情况下显示的最大完成项数。

如果要显示的项目数大于此值， PSReadLine 在显示完成项之前会提示 是/否 。

Type:	Int32
Position:	Named
Default value:	100
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ContinuationPrompt

指定输入多行时在后续行的开头显示的字符串。默认值是双倍大于 (>>) 的符号。空字符串有效。

Type:	String
Position:	Named
Default value:	>>
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-DingDuration

指定当 BellStyle 设置为 Audible 时发出蜂鸣声的持续时间。

Type:	Int32
Position:	Named
Default value:	50ms
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-DingTone

指定将 BellStyle 设置为 Audible 时，蜂鸣声的 Hz (Hz) 音。

Type:	Int32
Position:	Named
Default value:	1221
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-EditMode

指定命令行编辑模式。使用此参数可重置由 Set-PSReadLineKeyHandler设置的任何键绑定。

有效值如下：

Windows：键绑定模拟 PowerShell、cmd 和 Visual Studio。
Emacs：密钥绑定模拟 Bash 或 Emacs。
Vi：键绑定模拟 Vi。

使用 Get-PSReadLineKeyHandler 查看当前配置的 EditMode 的键绑定。

Type:	EditMode
Position:	Named
Default value:	Windows
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ExtraPromptLineCount

指定额外的行数。

如果提示跨多行，请指定此参数的值。当 PSReadLine 在显示某些输出后显示提示时，希望额外的行可用时，请使用此选项。例如， PSReadLine 返回完成列表。

与以前版本的 PSReadLine 相比，需要此选项，但在使用函数时 InvokePrompt 很有用。

Type:	Int32
Position:	Named
Default value:	0
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-HistoryNoDuplicates

此选项控制召回行为。重复的命令仍会添加到历史记录文件。设置此选项后，调用命令时仅显示最近的调用。重复的命令将添加到历史记录中，以在召回期间保留顺序。但是，在回忆或搜索历史记录时，通常不希望多次看到该命令。

默认情况下，全局 PSConsoleReadLineOptions 对象的 HistoryNoDuplicates 属性设置为 True。若要更改属性值，必须指定 SwitchParameter 的值，如下所示： -HistoryNoDuplicates:$False。只需使用 SwitchParameter-HistoryNoDuplicates 即可将设置为 True 。

使用以下命令，可以直接设置属性值：

(Get-PSReadLineOption).HistoryNoDuplicates = $False

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-HistorySavePath

指定保存历史记录的文件的路径。运行 Windows 或非 Windows 平台的计算机将文件存储在不同的位置。文件名存储在变量 $($Host.Name)_history.txt中，例如 ConsoleHost_history.txt。

如果不使用此参数，则默认路径如下所示：

Windows

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

非 Windows

$env:XDG_DATA_HOME/powershell/PSReadLine/$($Host.Name)_history.txt
$HOME/.local/share/powershell/PSReadLine/$($Host.Name)_history.txt

Type:	String
Position:	Named
Default value:	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
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-HistorySaveStyle

指定 PSReadLine 保存历史记录的方式。

以下是有效值：

SaveIncrementally：执行每个命令后保存历史记录，并在多个 PowerShell 实例之间共享。
SaveAtExit：在 PowerShell 退出时追加历史记录文件。
SaveNothing：请勿使用历史记录文件。

注意

如果将 HistorySaveStyle 设置为 SaveNothing ，然后在同一会话中稍后将其设置为 SaveIncrementally ，PSReadLine 将保存以前在会话中运行的所有命令。

Type:	HistorySaveStyle
Position:	Named
Default value:	SaveIncrementally
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-HistorySearchCaseSensitive

指定在 ReverseSearchHistory 或 HistorySearchBackward 等函数中历史记录搜索区分大小写。

默认情况下，全局 PSConsoleReadLineOptions 对象的 HistorySearchCaseSensitive 属性设置为 False。使用此 SwitchParameter 将属性值设置为 True。若要更改属性值，必须指定 SwitchParameter 的值，如下所示： -HistorySearchCaseSensitive:$False。

使用以下命令，可以直接设置属性值：

(Get-PSReadLineOption).HistorySearchCaseSensitive = $False

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-HistorySearchCursorMovesToEnd

指示光标移动到使用搜索从历史记录加载的命令的末尾。当此参数设置为 $False时，光标将停留在按下向上或向下键时所处的位置。

默认情况下，全局 PSConsoleReadLineOptions 对象的 HistorySearchCursorMovesToEnd 属性设置为 False。使用此 SwitchParameter 将属性值设置为 True。若要更改属性值，必须指定 SwitchParameter 的值，如下所示： -HistorySearchCursorMovesToEnd:$False。

使用以下命令，可以直接设置属性值：

(Get-PSReadLineOption).HistorySearchCursorMovesToEnd = $False

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaximumHistoryCount

指定要在 PSReadLine 历史记录中保存的最大命令数。

PSReadLine 历史记录独立于 PowerShell 历史记录。

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaximumKillRingCount

指定终止环中存储的最大项数。

Type:	Int32
Position:	Named
Default value:	10
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-PredictionSource

指定 PSReadLine 获取预测建议的源。

有效值为：

无 - 禁用预测 IntelliSense 功能 (默认) 。
历史记录 - 启用预测 IntelliSense 功能，并将 PSReadLine 历史记录用作唯一源。
插件 - 启用预测 IntelliSense 功能，并使用 () CommandPrediction 插件作为唯一源。此值已添加到 PSReadLine 2.2.0 中
HistoryAndPlugin - 启用预测 IntelliSense 功能，并使用历史记录和插件作为源。此值已添加到 PSReadLine 2.2.0 中

Type:	Microsoft.PowerShell.PredictionSource
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-PredictionViewStyle

设置预测文本的显示样式。默认值为 InlineView。

InlineView - 与目前一样存在的样式，类似于鱼壳和 zsh。（默认值）
ListView - 建议在下拉列表中呈现，用户可以选择使用 UpArrow 和 DownArrow。

此参数已添加到 PSReadLine 2.2.0 中

Type:	Microsoft.PowerShell.PredictionViewStyle
Position:	Named
Default value:	InlineView
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-PromptText

此参数设置 PromptText 属性的值。默认值为 "> "。

PSReadLine 分析提示函数，以确定如何仅更改提示部分的颜色。此分析并非 100% 可靠。如果 PSReadLine 以意外方式更改提示，请使用此选项。包括任何尾随空格。

此参数的值可以是单个字符串，也可以是两个字符串的数组。第一个字符串是提示字符串中出现分析错误时要更改为红色的部分。第二个字符串是用于分析错误的备用字符串。

Type:	String[]
Position:	Named
Default value:	>
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ShowToolTips

显示可能的完成时，工具提示将显示在完成列表中。

默认情况下会启用此选项。默认情况下，在 PSReadLine 的早期版本中未启用此选项。若要禁用，请将此选项设置为 $False。

默认情况下，全局 PSConsoleReadLineOptions 对象的 ShowToolTips 属性设置为 True。使用此 SwitchParameter 将属性值设置为 True。若要更改属性值，必须指定 SwitchParameter 的值，如下所示： -ShowToolTips:$False。

使用以下命令，可以直接设置属性值：

(Get-PSReadLineOption).ShowToolTips = $False

Type:	SwitchParameter
Position:	Named
Default value:	True
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ViModeChangeHandler

当 ViModeIndicator 设置为 Script时，每次模式更改时，都会调用提供的脚本块。为脚本块提供了一个类型的 ViMode参数。

此参数是在 PowerShell 7 中引入的。

Type:	ScriptBlock
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ViModeIndicator

此选项设置当前 Vi 模式的视觉指示器。插入模式或命令模式。

有效值如下：

无：没有指示器。
提示：提示更改颜色。
游标：游标更改大小。
脚本：打印用户指定的文本。

Type:	ViModeStyle
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-WordDelimiters

指定用于分隔 ForwardWord 或 KillWord 等函数的单词的字符。

Type:	String
Position:	Named
Default value:	;:,.[]{}()/\\|^&*-=+'"---
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

输入

None

无法通过管道将对象传递给此 cmdlet。

输出

None

此 cmdlet 不返回任何输出。

通过

Set-PSReadLineOption

语法

说明

示例

示例 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

-PredictionSource

-PredictionViewStyle

-PromptText

-ShowToolTips

-ViModeChangeHandler

-ViModeIndicator

-WordDelimiters

输入

输出

相关链接

其他资源