Set-PSReadLineOption

参考

模块:: PSReadLine

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

语法

Set-PSReadLineOption
   [-EditMode <EditMode>]
   [-ContinuationPrompt <string>]
   [-HistoryNoDuplicates]
   [-AddToHistoryHandler <Func[string,Object]>]
   [-CommandValidationHandler <Action[CommandAst]>]
   [-HistorySearchCursorMovesToEnd]
   [-MaximumHistoryCount <int>]
   [-MaximumKillRingCount <int>]
   [-ShowToolTips]
   [-ExtraPromptLineCount <int>]
   [-DingTone <int>]
   [-DingDuration <int>]
   [-BellStyle <BellStyle>]
   [-CompletionQueryItems <int>]
   [-WordDelimiters <string>]
   [-HistorySearchCaseSensitive]
   [-HistorySaveStyle <HistorySaveStyle>]
   [-HistorySavePath <string>]
   [-AnsiEscapeTimeout <int>]
   [-PromptText <string[]>]
   [-ViModeIndicator <ViModeStyle>]
   [-ViModeChangeHandler <scriptblock>]
   [-PredictionSource <PredictionSource>]
   [-PredictionViewStyle <PredictionViewStyle>]
   [-Colors <hashtable>]
   [-TerminateOrphanedConsoleApps]
   [<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 模式的游标选项：插入和命令。 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。这与返回 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

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

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，例如，在 tmux 或 screen 下运行时。

在 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：延续提示的颜色。
Emphasis：强调颜色。例如，搜索历史记录时匹配的文本。
Error：错误颜色。例如，在提示中。
Selection：突出显示菜单选择或所选文本的颜色。
Default：默认标记颜色。
Comment：注释标记颜色。
Keyword：关键字标记颜色。
String：字符串标记颜色。
Operator：运算符标记颜色。
Variable：变量标记颜色。
Command：命令标记颜色。
Parameter：参数标记颜色。
Type：类型标记颜色。
Number：数字标记颜色。
Member：成员名称标记颜色。
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 设置为声音时，提示音的持续时间。

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

-DingTone

指定当 BellStyle 设置为声音时，以赫兹 (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 即可设置回 True，-HistoryNoDuplicates。

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

(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 的数据源以获取预测建议。

有效值为：

None - 禁用预测 IntelliSense 功能（默认值）。
History - 启用预测 IntelliSense 功能，并使用 PSReadLine 历史记录作为唯一源。
Plugin - 启用预测 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 - 建议呈现在下拉列表中，用户可以使用向上箭头和向下箭头选择。

在 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。

在 PSReadLine 2.3.4 中添加了此参数和选项。

默认情况下，全局 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

-TerminateOrphanedConsoleApps

此参数将 TerminateOrphanedConsoleApps 选项设置为 $true。

在 Windows 上，按 ctrl c+c 终止进程时，附加到主机的每个进程都会收到终止信号，而不会收到活动的 shell。有时，当 shell 启动一些大型子进程树（例如，假设生成系统）时，某些进程可能会退出，让多个进程同时尝试使用控制台输入。

将 TerminateOrphanedConsoleApps 选项设置为 $true 时，PSReadLine 记录当前附加到控制台的进程列表。之后，每当 PSReadLine 运行时，它将获取附加到控制台的新进程列表，并终止不在原始列表中的进程。

在 PSReadLine 2.3.4 中添加了此参数和选项。

Type:	SwitchParameter
Position:	Named
Default value:	None
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 模式的可视指示。插入模式或命令模式。

有效值如下：

None：没有指示。
Prompt：提示更改颜色。
Cursor：游标改变大小。
Script：打印用户指定的文本。

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

-TerminateOrphanedConsoleApps

-ViModeChangeHandler

-ViModeIndicator

-WordDelimiters

输入

输出

相关链接

反馈

其他资源