片段

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。发现错误？报告问题 →

片段是提示符中具有特定上下文的部分。有多种开箱即用的类型，如果你想了解包含哪些片段，可以直接跳过这部分去浏览可用片段。继续阅读以了解如何配置片段。

json
yaml
toml

{
  "blocks": [
    {
      "segments": [
        {
          "type": "path",
          "style": "powerline",
          "powerline_symbol": "",
          "foreground": "#ffffff",
          "background": "#61AFEF",
          "template": " {{ .Path }} ",
          "include_folders": [
            "/Users/posh/Projects"
          ]
        }
      ]
    }
  ]
}

blocks:
  - segments:
      - type: path
        style: powerline
        powerline_symbol: 
        foreground: "#ffffff"
        background: "#61AFEF"
        template: " {{ .Path }} "
        include_folders:
          - /Users/posh/Projects

[[blocks]]
[[blocks.segments]]
type = "path"
style = "powerline"
powerline_symbol = ""
foreground = "#ffffff"
background = "#61AFEF"
template = " {{ .Path }} "
include_folders = [ "/Users/posh/Projects" ]

设置项

Name	Type	Default	Description
`type`	`string`		takes the `string` value referencing which segment logic it needs to run (see segments for possible values)
`style`	`string`	`plain`	see Style below. Possible values: `powerline` `plain` `diamond` `accordion` a go text/template template resolving to the above values
`powerline_symbol`	`string`		character to use at the end of the segment when `"style": "powerline"` (e.g., `\uE0B0`)
`leading_powerline_symbol`	`string`		character to use at the start of the segment when `"style": "powerline"`. By default, Oh My Posh uses an ANSI hack to invert the `powerline_symbol`, which provides the best alignment but may not work in all terminals. If you see black artifacts at segment starts, set this to the corresponding opening glyph (e.g., `\uE0D6` when using `\uE0B0`, or `\uE0D7` when using `\uE0B1`)
`invert_powerline`	`boolean`	`false`	if `true` swaps the foreground and background colors. Can be useful when the character you want does not exist in the perfectly mirrored variant for example - defaults to `false`
`leading_diamond`	`string`		character to use at the start of the segment. Will take the background color of the segment as its foreground color
`trailing_diamond`	`string`		character to use at the end of the segment. Will take the background color of the segment as its foreground color
`foreground`	`string`		color
`foreground_templates`	`[]Template`		color templates
`background`	`string`		color
`background_templates`	`[]Template`		color templates
`template`	`string`		a go text/template template to render the prompt
`templates`	`[]Template`		in some cases having a single template string is a bit cumbersome. Templates allows you to span the segment's template string multiple lines where every template is evaluated and depending on what you aim to achieve, there are two possible outcomes based on `templates_logic`
`templates_logic`	`string`	`join`	`first_match`: return the first non-whitespace string and skip everything else `join`:evaluate all templates and join all non-whitespace strings (default)
`options`	`[]Option`		see Options below
`interactive`	`boolean`	`false`	when true, the segment text is not escaped to allow the use of interactive prompt escape sequences in Bash/Zsh - defaults to `false`
`alias`	`string`		for use with cross segment template properties
`min_width`	`int`	`0`	if the terminal width is smaller than this value, the segment will be hidden. For your terminal width, see `oh-my-posh get width`. Defaults to `0` (disable)
`max_width`	`int`	`0`	if the terminal width exceeds this value, the segment will be hidden. For your terminal width, see `oh-my-posh get width`. Defaults to `0` (disable)
`cache`	`Cache`		how to cache the segment to avoid fetching information too much, see below
`include_folders`	`[]string`		define which folders to include to enable the segment, see below
`exclude_folders`	`[]string`		define which folders to exclude to disable the segment, see below
`force`	`boolean`	`false`	when true, the segment is always rendered, even when it's only whitespace - defaults to `false`
`timeout`	`int`	`0`	timeout in milliseconds for segment execution. If the segment takes longer than this value to complete, it will be disabled. Defaults to `0` (no timeout)
`index`	`int`		used to override a specific segment (1-based)

警告

在 Bash/Zsh 中，当片段的 interactive 属性设为 true 时，提示符长度计算可能出现偏差，这是由于字符串展开机制（例如 Bash 中的 \w 和 Zsh 中的 %d 都会展开为当前工作目录路径），导致右对齐区块无法正确对齐。

由于字符串展开由 Shell 自身处理，Oh My Posh 无法预知最终提示符长度，因此请谨慎使用此功能。

样式

样式决定提示符的渲染方式。根据主流主题设计，我们归纳出 4 种类型。不同样式需要不同的配置方式，具体采用哪种取决于你想要实现的效果。

Powerline

这是我们的起点样式。使用单个符号（powerline_symbol）分隔片段，该符号会继承前一片段的背景色（若无则为透明）和当前片段的前景色（若为末片段则为透明）。此样式要求片段设置背景色，否则效果有限。

当片段开头出现黑色三角符号（具体符号取决于你使用的 powerline_symbol）时，可将 leading_powerline_symbol 设置为 powerline_symbol 的"开启"版本。此方案不使用我们实现的反转 ANSI 技巧（并非所有终端都支持该技巧），可能需要调整字体设置以获得最佳对齐效果。

Git Bash

powerline 样式在 Git Bash 中存在图标宽度计算错误问题，可能导致输入长命令或搜索历史记录时提示符显示异常。

以下提示符配置也存在相同问题：

export PS1=" "

Plain

极简风格。透明背景上的彩色文字。建议设置 foreground 属性以获得最佳体验。

Diamond

Powerline 使用单一符号效果很好，但有时你可能希望片段使用不同的起始/结束符号。例如钻石样式：< my segment text >。与 Plain 样式的区别在于钻石符号会继承片段背景色作为自身前景色。

Accordion

类似 Powerline，但禁用时仍会显示无文本的符号。这样看起来像是未展开的片段，如同手风琴的折叠效果。

选项

options 属性允许您在默认设置之外自定义片段的行为和外观。这些选项可以是功能开关、配置项或仅适用于当前片段的附加样式细节。要了解特定片段可用的选项，请参考其对应的文档章节，其中会详细解释每个选项。

缓存

缓存属性用于控制片段刷新频率。当片段生成较慢或需要避免频繁获取信息时特别有用。缓存属性是包含以下属性的对象：

Name	Type	Description
`duration`	`string`	the duration for which the segment will be cached. The duration is a string in the format `1h2m3s`. The duration is parsed using the time.ParseDuration function from the Go standard library. To disable the cache, use `none`
`strategy`	`string`	the strategy to use to identify if we should show the segment's cache value. See below for more information on strategy

json
yaml
toml

{
  "cache": {
    "duration": "1h",
    "strategy": "folder"
  }
}

cache:
  duration: 1h
  strategy: folder

[cache]
duration = "1h"
strategy = "folder"

策略

会话

会话策略会基于当前 Shell 会话缓存段内容。适用于需要始终显示但不想频繁刷新的段。

文件夹

文件夹策略根据当前工作目录缓存片段，每个目录独立缓存。适用于语言片段或版本控制片段等场景。对于版本控制片段，此策略能识别代码库上下文（例如在 Git 仓库中时，无论当前目录位置如何，都使用相同的片段缓存值）。

设备

设备策略会基于当前设备缓存片段内容。这意味着无论工作目录或 Shell 会话如何变化，都会使用相同的缓存值。适用于生成缓慢但不常变化的片段，例如系统信息片段。

文件夹包含/排除规则

有时您可能希望仅在特定文件夹中渲染某个段。若指定了 include_folders，则该段仅在列出的路径位置才会渲染。若指定了 exclude_folders，则该段在排除的路径位置将不会渲染。

json
yaml
toml

{
  "include_folders": [
    "/Users/posh/Projects"
  ]
}

include_folders:
  - /Users/posh/Projects

include_folders = [ "/Users/posh/Projects" ]

json
yaml
toml

{
  "exclude_folders": [
    "/Users/posh/Projects"
  ]
}

exclude_folders:
  - /Users/posh/Projects

exclude_folders = [ "/Users/posh/Projects" ]

这些属性中的字符串会被当作正则表达式处理。您可以使用任何有效的正则表达式结构，但正则表达式必须完全匹配整个目录名。以下表达式会匹配 /Users/posh/Projects/Foo 但不会匹配 /home/Users/posh/Projects/Foo。

json
yaml
toml

{
  "include_folders": [
    "/Users/posh/Projects/.*"
  ]
}

include_folders:
  - /Users/posh/Projects/.*

include_folders = [ "/Users/posh/Projects/.*" ]

您也可以组合使用这些属性：

json
yaml
toml

{
  "include_folders": [
    "/Users/posh/Projects/.*"
  ],
  "exclude_folders": [
    "/Users/posh/Projects/secret-project.*"
  ]
}

include_folders:
  - /Users/posh/Projects/.*
exclude_folders:
  - /Users/posh/Projects/secret-project.*

include_folders = [ "/Users/posh/Projects/.*" ]
exclude_folders = [ "/Users/posh/Projects/secret-project.*" ]

信息

Oh My Posh 会同时接受 / 和 \ 作为路径分隔符，无论当前操作系统使用哪种分隔符都能匹配
由于字符串被当作正则表达式处理，在 Windows 目录名中使用反斜杠 (\) 时，需要写成双反斜杠 \\\\（JSON 格式中需转义为四反斜杠）
路径开头的 ~ 字符会匹配用户主目录
比较操作在 Windows 和 macOS 上不区分大小写，但在其他操作系统上区分大小写

这意味着用户 Bill 在 Windows 账户名为 Bill，在 Linux 账户名为 bill 时， ~/Foo 在 Windows 可能匹配 C:\Users\Bill\Foo 或 C:\Users\Bill\foo，但在 Linux 只会匹配 /home/bill/Foo

索引

段在配置中的索引位置，用于在基础配置中[覆盖]特定段。索引从 1 开始计数，因此第一个段的索引为 1。

隐藏段

条件式隐藏

要通过模板隐藏整个段（包括前后符号），模板必须 计算为空字符串。可通过条件语句 (if) 实现。以下示例将在环境变量 POSH_ENV 非空时渲染菱形段。

仅空格会被排除，这意味着您仍可添加换行符和制表符（如有需要）。

json
yaml
toml

{
  "type": "text",
  "style": "diamond",
  "leading_diamond": " ",
  "trailing_diamond": "",
  "foreground": "#ffffff",
  "background": "#d53c14",
  "template": "{{ if .Env.POSH_ENV }}  {{ .Env.POSH_ENV }} {{ end }}"
}

type: text
style: diamond
leading_diamond: " "
trailing_diamond: 
foreground: "#ffffff"
background: "#d53c14"
template: "{{ if .Env.POSH_ENV }}  {{ .Env.POSH_ENV }} {{ end }}"

type = "text"
style = "diamond"
leading_diamond = " "
trailing_diamond = ""
foreground = "#ffffff"
background = "#d53c14"
template = "{{ if .Env.POSH_ENV }}  {{ .Env.POSH_ENV }} {{ end }}"

动态切换

有时您可能希望隐藏特定片段，但该场景又不适合使用条件模板。此时可通过 oh-my-posh toggle <type> 命令临时切换片段的启用状态。此操作仅作用于当前 Shell 会话，即在某个 Shell 实例中禁用片段不会影响其他会话。

要查看当前已切换的段，请使用 oh-my-posh get toggles。

设置项​

样式​

Powerline​

Plain​

Diamond​

Accordion​

选项​

缓存​

策略​

会话​

文件夹​

设备​

文件夹包含/排除规则​

索引​

隐藏段​

条件式隐藏​

动态切换​

设置项

样式