设置 PSReadLineOption (PSReadLine)

设置 PSReadLineOption

自定义 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 以在灰色背景上显示带有绿色前景文本的 Comment 标记。在示例中使用的转义序列中，32 表示前景色，47 表示背景色。

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

您可以选择仅设置前景文本颜色。例如，Comment 标记的亮绿色前景文本颜色："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 开头，则脚本块将返回 $false。这与返回 SkipAdding AddToHistory 枚举具有相同的效果。如果命令不是以 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 相同。

Func[System.String,System.Object]

命名

None

False

False

False

-AnsiEscapeTimeout

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

通过 Windows 上的重定向输入，许多键都作为以转义字符开头的字符序列发送。无法区分后面跟着多个字符的单个转义字符和有效的转义序列。

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

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

整数32

命名

100

False

False

False

-BellStyle

指定 PSReadLine 如何响应各种错误和不明确的情况。

有效值如下：

• 声音：短促的蜂鸣声。
• 视觉：文字短暂闪烁。
• 无：没有反馈。

BellStyle

命名

有声的

False

False

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 颜色代码的更多信息，请参阅 Wikipedia 文章 ANSI 转义代码。

有效的密钥包括：

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

哈希表

命名

None

False

False

False

-CommandValidationHandler

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

在引发异常之前，验证处理程序可以将光标放置在错误点，以便更容易修复。验证处理程序还可以更改命令行以纠正常见的印刷错误。

ValidateAndAcceptLine 用于避免无法运行的命令使您的历史记录变得混乱。

操作[CommandAst]

命名

None

False

False

False

-CompletionQueryItems

指定在没有提示的情况下显示的完成项目的最大数量。

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

整数32

命名

100

False

False

False

-ContinuationPrompt

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

String

命名

>>

False

False

False

-DingDuration

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

整数32

命名

50毫秒

False

False

False

-DingTone

指定当 BellStyle 设置为 Audible 时蜂鸣声的音调，以赫兹 (Hz) 为单位。

整数32

命名

1221

False

False

False

-EditMode

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

有效值如下：

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

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

EditMode

命名

Windows

False

False

False

-ExtraPromptLineCount

指定额外行数。

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

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

整数32

命名

0

False

False

False

-HistoryNoDuplicates

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

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

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

(Get-PSReadLineOption).HistoryNoDuplicates = $False

SwitchParameter

命名

False

False

False

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

String

命名

Windows 上的 $env:APPDATA\Microsoft\Windows\PowerShell\PSReadLine 和 $env:XDG_DATA_HOME/powershell/PSReadLine 或 $HOME/.local/share/powershell/ 中名为 $ ($Host.Name)_history.txt 的文件非 Windows 平台上的 PSReadLine

False

False

False

-HistorySaveStyle

指定PSReadLine如何保存历史记录。

有效值如下：

• 增量保存：执行每个命令后保存历史记录并在多个 PowerShell 实例之间共享。
• SaveAtExit：PowerShell 退出时附加历史文件。
• SaveNothing：不使用历史文件。

笔记

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

历史保存样式

命名

SaveIncrementally

False

False

False

-HistorySearchCaseSensitive

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

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

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

(Get-PSReadLineOption).HistorySearchCaseSensitive = $False

SwitchParameter

命名

False

False

False

False

-HistorySearchCursorMovesToEnd

指示光标移动到您通过搜索从历史记录中加载的命令的末尾。当此参数设置为 $False 时，光标将保留在按向上或向下箭头时的位置。

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

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

(Get-PSReadLineOption).HistorySearchCursorMovesToEnd = $False

SwitchParameter

命名

False

False

False

False

-MaximumHistoryCount

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

PSReadLine 历史记录与 PowerShell 历史记录是分开的。

整数32

命名

None

False

False

False

-MaximumKillRingCount

指定杀死环中存储的最大项目数。

整数32

命名

10

False

False

False

-PredictionSource

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

有效值为：

• 无 - 禁用预测 IntelliSense 功能（默认）。
• 历史记录 - 启用预测 IntelliSense 功能并使用 PSReadLine 历史记录作为唯一来源。
• 插件 - 启用预测 IntelliSense 功能并使用插件 (CommandPrediction) 作为唯一来源。该值是在 PSReadLine 2.2.0 中添加的
• HistoryAndPlugin - 启用预测性 IntelliSense 功能并使用历史记录和插件作为来源。该值是在 PSReadLine 2.2.0 中添加的

Microsoft.PowerShell.PredictionSource

命名

None

False

False

False

-PredictionViewStyle

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

• InlineView - 现有的样式，类似于 Fish shell 和 zsh 中的样式。 （默认）
• ListView - 建议在下拉列表中呈现，用户可以使用 UpArrow 和 DownArrow 进行选择。

PSReadLine 2.2.0 中添加此参数

Microsoft.PowerShell.PredictionViewStyle

命名

InlineView

False

False

False

-PromptText

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

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

该参数的值可以是单个字符串或两个字符串的数组。第一个字符串是提示字符串中出现解析错误时希望更改为红色的部分。第二个字符串是出现解析错误时使用的备用字符串。

String[]

命名

>

False

False

False

-ShowToolTips

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

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

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

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

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

(Get-PSReadLineOption).ShowToolTips = $False

SwitchParameter

命名

True

False

False

False

-TerminateOrphanedConsoleApps

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

在 Windows 上，当您按 Ctrl+c 终止进程时，附加到控制台的每个进程都会收到终止信号，而不仅仅是活动 shell。有时，当 shell 启动一些大型子进程树时（例如，想象一个构建系统），某些进程可能会退出，从而使多个进程同时尝试使用控制台输入。

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

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

SwitchParameter

命名

None

False

False

False

-ViModeChangeHandler

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

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

ScriptBlock

命名

None

False

False

False

-ViModeIndicator

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

有效值如下：

• 无：没有指示符。
• 提示：提示会改变颜色。
• 光标：光标改变大小。
• 脚本：打印用户指定的文本。

ViMode风格

命名

None

False

False

False

-WordDelimiters

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

String

命名

;:,.[]{}()/\|^&*-=+'"---

False

False

False

输入

无

您无法将对象通过管道传输到此 cmdlet。

输出

无

此 cmdlet 不返回任何输出。