在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

romkatv/powerlevel10k

菜单

自定义片段

相关源文件

本页面介绍了如何在 Powerlevel10k 中创建自定义提示段。自定义段允许您通过自己的功能扩展提示，显示对您的工作流程至关重要的信息，超出了内置段所提供的功能。

有关配置现有段的信息，请参阅 参数参考。

什么是自定义段？

提示段是构成 Powerlevel10k 提示的各个组件。每个段通常显示特定的信息（如当前目录、git 状态等），并具有自己的样式和图标。

自定义段允许您

  • 显示您自己的命令或脚本的输出
  • 创建工作流特定的指示符
  • 集成内置段不支持的工具
  • 组合或修改现有功能

自定义段的位置

来源：internal/p10k.zsh1125-1632 config/p10k-rainbow.zsh26-112

创建自定义段

添加自定义段到您的提示有三种主要方式：

  1. 使用配置变量的简单自定义段方法
  2. 创建自定义基于函数的段
  3. 扩展现有段

让我们来看看每种方法。

方法 1：通过配置实现简单的自定义段

创建自定义段最简单的方法是在您的 .p10k.zsh 配置文件中定义一个变量。

POWERLEVEL9K_CUSTOM_SEGMENT_NAME="command to execute"

当您将 custom_segment_name 添加到 POWERLEVEL9K_LEFT_PROMPT_ELEMENTS 或 POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS 时，Powerlevel10k 将执行该命令并在提示中显示其输出。

示例

在提示中显示当前日期

# In your .p10k.zsh file
POWERLEVEL9K_CUSTOM_DATE="date +%D"
POWERLEVEL9K_CUSTOM_DATE_FOREGROUND="black"
POWERLEVEL9K_CUSTOM_DATE_BACKGROUND="blue"

# Add to your prompt elements
POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS+=(custom_date)

这会创建一个段，以 MM/DD/YY 格式显示当前日期，具有蓝色背景和黑色前景。

简单自定义段的工作流程

来源：internal/p10k.zsh1688-1699

方法 2：基于函数的自定义段

为了获得更多控制，您可以创建 shell 函数。这与内置段的工作方式类似。

创建基于函数的段的步骤

  1. 创建一个名为 prompt_your_segment_name 的函数
  2. 使用 p10k segment 输出段内容
  3. 将 your_segment_name 添加到您的提示元素中

p10k 段函数

p10k 段函数（它是 _p9k_prompt_segment 的别名）是创建段的核心 API。

p10k segment SEGMENT_NAME BACKGROUND_COLOR FOREGROUND_COLOR [ICON] [EXPAND_PARAMS] [CONTENT]

参数

参数描述
SEGMENT_NAME段的标识符（用于样式设置）
BACKGROUND_COLOR背景颜色（名称或编号）
FOREGROUND_COLOR前景色（名称或编号）
ICON可选的图标标识符
EXPAND_PARAMS参数扩展的 0/1 标志
CONTENT要显示的文本

基于函数的段示例

这是一个显示您当前 IP 地址的简单函数示例。

基于函数的段生命周期

来源：internal/p10k.zsh1101-1102 internal/p10k.zsh614-850 internal/p10k.zsh853-1099

方法 3：扩展现有段

您还可以创建增强或修改现有 Powerlevel10k 段的段。

  1. 研究您想扩展的内置段的实现。
  2. 创建您自己的函数以添加所需的功能。
  3. 使用与原始段相同的样式参数。

高级段技术

条件段

您可以使段仅在某些条件下显示。

1. 使用空内容检查

如果内容为空，段将不会显示。

2. 使用可选条件参数

为了获得更多控制，请使用可选的条件参数（p10k segment 的第 6 个参数）。

只有当 condition_var 非空时，该段才会显示。

3. 使用 SHOW_ON_UPGLOB

您可以使段仅在包含某些文件的目录中显示。

这将在包含 .txt 文件或 Makefile（或其父目录）的目录中显示该段。

来源：internal/p10k.zsh245-295 internal/p10k.zsh614-850

异步段

对于可能运行慢命令的段，您可以使用异步工作系统。

异步段的示例

来源：internal/p10k.zsh1250-1298 internal/p10k.zsh1350-1368

样式和图标

您可以使用以下方式自定义段的外观：

  1. 背景和前景色 - 直接在 p10k segment 调用中。
  2. 图标 - 使用内置图标系统。
  3. 其他样式参数 - 在您的 .p10k.zsh 文件中。

使用图标

Powerlevel10k 拥有一个全面的图标系统。您可以：

  1. 按名称使用现有图标（请参阅 internal/icons.zsh 获取完整列表）。
  2. 在您的配置中定义自己的图标。

这将显示 Node.js 图标在 "Content" 前面，并具有正确的样式。

自定义样式

为了获得一致的样式，请在您的 .p10k.zsh 文件中定义特定于段的样式变量。

来源：internal/icons.zsh1-489 config/p10k-rainbow.zsh117-132 internal/p10k.zsh509-530

自定义段架构

了解段的内部工作原理可以帮助您创建更复杂的自定义段。

来源：internal/p10k.zsh295-376 internal/p10k.zsh614-850 internal/p10k.zsh853-1099 internal/icons.zsh1-489

完整示例

这是一个显示当前内存使用情况的完整自定义段示例。

此段

  1. 读取系统内存信息
  2. 以人类可读的方式格式化它
  3. 根据内存使用阈值更改颜色
  4. 显示内置图标集中的图标

来源：internal/p10k.zsh324-342 internal/p10k.zsh1243-1298

自定义段最佳实践

  1. 保持段函数简洁并专注。

    • 每个段都应该做好一件事。
    • 复杂的逻辑应移至辅助函数。

  2. 对耗时操作使用异步工作程序。

    • 网络调用、磁盘 I/O 或长时间运行的命令应异步执行。
    • 即使在异步完成之前也要初始化结果变量。

  3. 适当时缓存结果。

    • 使用缓存函数来处理不经常更改的值。
    • 考虑数据需要多久刷新一次。

  4. 使段具有条件性。

    • 仅在相关时显示段
    • 使用条件参数或 SHOW_ON_UPGLOB

  5. 保持风格一致

    • 遵循内置段的风格模式
    • 为您的段定义配置变量

  6. 优雅地处理错误

    • 在使用命令前检查命令可用性
    • 在命令失败时提供备用行为

  7. 记录您的段

    • 注释您的代码，特别是复杂的段
    • 如果您共享段，请描述配置选项

来源： internal/p10k.zsh377-507 internal/p10k.zsh1250-1362

故障排除

如果您的自定义段未显示或未按预期工作

  1. 检查段的顺序 - 确保您的段已正确添加到 POWERLEVEL9K_LEFT_PROMPT_ELEMENTS 或 POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS

  2. 验证函数命名 - 函数必须命名为 prompt_your_segment_name

  3. 单独测试命令 - 直接在终端中运行您的命令，以确保它产生输出

  4. 检查空条件 - 如果您的段使用条件，请确保它们正确评估

  5. 查找错误消息 - 在提示渲染时检查终端中的错误

  6. 添加调试输出 - 暂时在您的段函数中添加 echo 或 print 语句

  7. 检查命令依赖项 - 确保您的段使用的所有命令都已安装

结论

自定义段是使用您自己的功能扩展 Powerlevel10k 的强大方式。通过结合本指南中的技术，您可以创建复杂的提示元素，以增强您的终端体验并与您的特定工作流程集成。

有关更多示例，请检查 internal/p10k.zsh 文件中的内置段函数，它们展示了您可以为自己的段改编的各种模式和技术。