starship/docs/zh-CN/advanced-config/README.md

高级配置

Starship 功能繁多，有时您必须在编辑 starship.toml 之外做更多工作才能实现某些效果。 此页面详细介绍了一些在 starship 中使用的高级配置技巧。

::: warning

本节所述的配置内容可能随 Starship 未来版本的更新而改变。

:::

TransientPrompt in PowerShell

It is possible to replace the previous-printed prompt with a custom string. This is useful in cases where all the prompt information is not always needed. To enable this, run Enable-TransientPrompt in the shell session. To make it permanent, put this statement in your $PROFILE. Transience can be disabled on-the-fly with Disable-TransientPrompt.

By default, the left side of input gets replaced with >. To customize this, define a new function called Invoke-Starship-TransientFunction. For example, to display Starship's character module here, you would do

function Invoke-Starship-TransientFunction {
  &starship module character
}

Invoke-Expression (&starship init powershell)

Enable-TransientPrompt

TransientPrompt and TransientRightPrompt in Cmd

Clink allows you to replace the previous-printed prompt with custom strings. This is useful in cases where all the prompt information is not always needed. To enable this, run clink set prompt.transient <value> where <value> can be one of:

• always: always replace the previous prompt
• same_dir: replace the previous prompt only if the working directory is same
• off: do not replace the prompt (i.e. turn off transience)

You need to do this only once. Make the following changes to your starship.lua to customize what gets displayed on the left and on the right:

• By default, the left side of input gets replaced with >. To customize this, define a new function called starship_transient_prompt_func. This function receives the current prompt as a string that you can utilize. For example, to display Starship's character module here, you would do

function starship_transient_prompt_func(prompt)
  return io.popen("starship module character"
    .." --keymap="..rl.getvariable('keymap')
  ):read("*a")
end
load(io.popen('starship init cmd'):read("*a"))()

• By default, the right side of input is empty. To customize this, define a new function called starship_transient_rprompt_func. This function receives the current prompt as a string that you can utilize. For example, to display the time at which the last command was started here, you would do

function starship_transient_rprompt_func(prompt)
  return io.popen("starship module time"):read("*a")
end
load(io.popen('starship init cmd'):read("*a"))()

在 Cmd 中自定义提示符显示前和执行前的命令

Clink 提供了很灵活的 API，能在 Cmd shell 中运行预提示和执行前命令。 在 Starship 中使用这些 API 很容易。 对你的 starship.lua 按需做出如下修改：

• 为了在提示符显示前运行一个自定义函数，你需要定义一个名为 starship_preprompt_user_func 的函数。 这个函数接受当前的提示符作为字符串参数，你可以在函数中使用它。 例如，如果想在提示符前绘制一个火箭，可以这样写：

function starship_preprompt_user_func(prompt)
  print("🚀")
end

load(io.popen('starship init cmd'):read("*a"))()

• 为了在命令执行前运行一个自定义函数，你需要定义一个名为 starship_precmd_user_func 的函数。 这个函数接受当前的命令行内容作为字符串参数，同样，你可以在函数中使用它。 例如，要打印即将被执行的命令，可以这样写：

function starship_precmd_user_func(line)
  print("Executing: "..line)
end

load(io.popen('starship init cmd'):read("*a"))()

在 Bash 中自定义预提示和预执行命令

Bash 并没有类似大多数其它 shell 的正式预执行/预命令框架。 因此，很难在 bash 中提供完全可自定义的 hook 机制。 然而，Starship 确实能使您有限地在提示符渲染过程中插入自己的函数执行：

• 若要在提示符显示之前运行自定义函数，需要定义此函数，然后将函数名赋值给 starship_reserved_user_func。 例如，要在提示符之前绘制一枚火箭，您应该写

function blastoff(){
    echo "🚀"
}
starship_precmd_user_func="blastoff"

• 要在一个命令运行前运行自定义函数，您可以使用 DEBUG trap 机制。 然而，您必须在捕捉 DEBUG 信号_之前_启动 Starship！ Starship 可以保留 DEBUG trap 的值，但如果该 trap 在 starship 启动后被覆盖，一些功能将会被破坏。

function blastoff(){
    echo "🚀"
}
trap blastoff DEBUG     # Trap DEBUG *before* running starship
set -o functrace
eval $(starship init bash)
set +o functrace

在 Powershell 中自定义提示符显示前和执行前的命令

Powershell 不像多数其他的 Shell 有成体系的预执行框架。 因此，很难在 Powershell 中提供完全可自定义的 hook 机制。 然而，Starship 确实能使您有限地在提示符渲染过程中插入自己的函数执行：

创建一个名为 Invoke-Starship-PreCommand 的函数

function Invoke-Starship-PreCommand {
    $host.ui.Write("🚀")
}

更改窗口标题

一些 shell 会自动更改您的窗口标题（比如改成您的工作目录）。 Fish 甚至默认会执行此功能。 Starship 没有实现此功能，但将这个功能添加到 bash、zsh、cmd 或 powershell 是相当简单的。

首先，定义窗口标题更改函数（在 bash 和 zsh 中相同）：

function set_win_title(){
    echo -ne "\033]0; YOUR_WINDOW_TITLE_HERE \007"
}

您可以使用变量来定制标题（常用的有 $USER，$HOSTNAME 和 $PWD）。

在 bash 中，设置此函数为 starship 预执行函数：

starship_precmd_user_func="set_win_title"

在 zsh中，将此函数添加到 reservmd_functions 列表：

precmd_functions+=(set_win_title)

如果您对产生的效果感到满意，请将以上代码添加到您的 shell 配置文件（~/.bashrc 或 ~/zsrhc）中以使其永久化。

例如，如果您想要在终端标签标题中显示当前目录， 将以下代码添加到您的 ~/.ashrc 或 ~/.zshrc:

function set_win_title(){
    echo -ne "\033]0; $(basename "$PWD") \007"
}
starship_precmd_user_func="set_win_title"

对于 Cmd，您可以使用 starship_preprompt_user_func 函数修改窗口标题。

function starship_preprompt_user_func(prompt)
  console.settitle(os.getenv('USERNAME').."@"..os.getenv('COMPUTERNAME')..": "..os.getcwd())
end

load(io.popen('starship init cmd'):read("*a"))()

您也可以为 Powershell 创建一个函数 Invoke-Starship-PreCommand，来设置类似的输出。

# edit $PROFILE
function Invoke-Starship-PreCommand {
  $host.ui.Write("`e]0; PS> $env:USERNAME@$env:COMPUTERNAME`: $pwd `a")
}

Invoke-Expression (&starship init powershell)

启用右侧提示

一些 Shell 支持右侧提示, 它与输入区渲染在同一行。 Starship 可以设置右侧提示的内容，使用 right_format 选项。 所有支持 format 的组件也同时支持 right_format。 未显式在 format 或 right_format 中使用的组件，会保存在变量 $all 中。

注意：右侧提示和输入区显示在同一行。 如果需要在输入区的上方显示右对齐的组件，请查阅 fill 组件。

right_format 现支持 elvish、fish、zsh、xonsh、cmd。

示例

# ~/.config/starship.toml

# A minimal left prompt
format = """$character"""

# move the rest of the prompt to the right
right_format = """$all"""

会显示成如下方案

▶                                   starship on  rprompt [!] is 📦 v0.57.0 via 🦀 v1.54.0 took 17s

多行提示符

一些 Shell 也同时支持多行提示符。 若用户输入了不完整的命令（例如一个左括号或引号），Shell 会渲染多行提示符。

使用 continuation_prompt 选项来设置 Starship 的多行提示符。 它的默认值为 [∙](bright-black)。

注意：continuation_prompt 应设置为没有变量的字符串。

注意，仅以下 Shell 支持多行提示符：

• bash
• zsh
• PowerShell

示例

# ~/.config/starship.toml

# A continuation prompt that displays two filled in arrows
continuation_prompt = "▶▶"

样式设定

样式字符串是用空格分隔的单词列表。 其中单词不是大小写敏感的（例如 bold 和 BoLd 被视为同一字符串）。 每个单词可以是以下之一：

• bold
• italic
• underline
• dimmed
• inverted
• blink
• hidden
• strikethrough
• bg:<color>
• fg:<color>
• <color>
• none

<color> 是颜色说明符（下面解释）。 fg:<color> 和 <color> 的功能暂时相同，未来可能会更改。 inverted 会反转背景和文字的颜色。 字符串中的单词顺序不影响显示结果。

若 none 不是 bg: 的一部分，则它会覆盖其他的设置：比如 fg:red none fg:blue 不会更改任何样式。 bg:none 会设置成默认背景色，因此 fg:red bg:none、red、fg:red 的作用相同；类似，bg:green fg:red bg:none、fg:red、red 的作用也相同。 未来可能会将 none 与其它标识符一起使用视为一种错误。

颜色说明符可以是以下内容之一：

• 任一标准的终端颜色：black, red, green, blue, yellow, purple, cyan, white。 您也可以使用前缀 bright- 定义浅色版本（例如 bright-white）。
• 一个 # 后跟一个六位十六进制数。 这将指定一个 十六进制 RGB 颜色代码。
• 0-255 之间的数字。 这将指定一个 8 位 ANSI 颜色码。

如果为文本/背景指定了多个颜色，字符串中最后指定的颜色将具有最高优先级。

Not every style string will be displayed correctly by every terminal. In particular, the following known quirks exist:

• Many terminals disable support for blink by default
• hidden is not supported on iTerm (https://gitlab.com/gnachman/iterm2/-/issues/4564).
• strikethrough is not supported by the default macOS Terminal.app