添加自定义模块

非官方测试版翻译

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

为 Oh My Posh 添加新模块需要完成多个步骤以确保正确集成。本指南将带您完成创建完整模块所需的所有文件创建和注册流程。

规划您的模块

编码前需明确定义以下关键属性：

• 模块 ID：配置文件中使用的短横线分隔标识符（例如：new-feature）

• Go 类型名称：代码中使用的 PascalCase 结构体名称（例如：NewFeature）

• 分类：从 cli、cloud、health、languages、music、scm、system 或 web 中选择

• 描述：清晰说明模块功能的单行摘要

• 属性：可配置属性列表（含类型和默认值）

• 模板：默认模板字符串（例如：{{ .Text }}）

自动化设置（VS Code）

若使用 VS Code，可通过 VS Code 聊天中的自动化模块创建命令完成：

1. 打开 VS Code 聊天（使用侧边栏聊天图标或命令面板："Chat: Focus on Chat View"）

2. 输入 /segment 并按照提示操作

3. 根据系统提示提供模块详情

4. 该命令将自动创建所有必需的文件和注册项

此自动化方式确保所有文件均按正确命名规范和字母顺序创建。若您倾向手动创建模块或希望理解流程细节，请继续阅读下方手动步骤。

手动设置步骤

步骤 1：创建 Go 实现

在 ./src/segments/ 目录创建以模块 ID 命名的新文件：new_feature.go。

package segments

import (
	"github.com/jandedobbeleer/oh-my-posh/src/segments/options"
)

type NewFeature struct {
	Base

	// Fields that will be available in your template
	Text string
}

// Define constants for each configurable property
const (
	// EnableNewThing enables the new functionality
	EnableNewThing options.Property = "enable_new_thing"
	// CustomText sets custom display text
	CustomText options.Property = "custom_text"
)

func (n *NewFeature) Enabled() bool {
	// Set up data for the template using property values
	n.Text = n.props.GetString(CustomText, "default value")

	// Return true if the segment should be displayed
	// You can add logic here to determine if the segment is relevant
	return true
}

func (n *NewFeature) Template() string {
	return "{{ .Text }}"
}

关键准则：

• 使用 UTF32 编码表示图标（例如："\uEFF1"），而非直接使用图标字符

• 在 Nerd Fonts 速查表 查找图标代码

• 确保 Enabled() 中的逻辑专注于数据准备和可见性判断

步骤 2：注册模块

编辑 src/config/segment_types.go 以注册新模块：

添加 Gob 注册

在 init() 函数中将模块添加至 gob 注册表（保持字母顺序）：

gob.Register(&segments.NewFeature{})

添加模块常量

为模块类型添加常量（保持字母顺序）：

// NEWFEATURE displays new feature information
NEWFEATURE SegmentType = "new-feature"

添加到 Segments 映射

在 Segments 映射中注册模块（保持字母顺序）：

NEWFEATURE: func() SegmentWriter { return &segments.NewFeature{} },

步骤 3：创建文档

在 website/docs/segments/[category]/[segment-id].mdx 路径创建文档：

---
id: new-feature
title: New Feature
sidebar_label: New Feature
---

## What

Displays information about the new feature in your environment.

## Sample Configuration

import Config from "@site/src/components/Config.js";

<Config
  data={{
    type: "new-feature",
    style: "powerline",
    powerline_symbol: "\uE0B0",
    foreground: "#193549",
    background: "#ffeb3b",
    options: {
      enable_new_thing: true,
      custom_text: "Hello World",
    },
  }}
/>

## Options

| Name               | Type      | Default | Description                   |
| ------------------ | --------- | ------- | ----------------------------- |
| `enable_new_thing` | `boolean` | `false` | Enables the new functionality |
| `custom_text`      | `string`  | `""`    | Custom text to display        |

步骤 4：更新侧边栏导航

编辑 website/sidebars.js 并将文档添加至对应分类（保持字母顺序）：

{
  type: "category",
  label: "🖥️ System", // or appropriate category
  collapsed: true,
  items: [
    // ... other segments
    "segments/system/new-feature",
    // ... more segments
  ]
}

步骤 5：添加 JSON 模式定义

在 themes/schema.json 中更新以下两处：

添加到类型枚举

在模块类型枚举中添加模块 ID（保持字母顺序）：

{
  "enum": [
    "angular",
    // ... other types
    "new-feature"
    // ... more types
  ]
}

添加模式定义

在 allOf 数组中添加模块属性模式（保持字母顺序）：

{
  "if": {
    "properties": {
      "type": { "const": "new-feature" }
    }
  },
  "then": {
    "title": "New Feature Segment",
    "description": "https://ohmyposh.dev/docs/segments/system/new-feature",
    "properties": {
      "options": {
        "properties": {
          "enable_new_thing": {
            "type": "boolean",
            "title": "Enable New Thing",
            "description": "Enables the new functionality",
            "default": false
          },
          "custom_text": {
            "type": "string",
            "title": "Custom Text",
            "description": "Custom text to display",
            "default": ""
          }
        }
      }
    }
  }
}

步骤 6：添加测试

使用表格驱动测试创建测试文件 src/segments/new_feature_test.go：

package segments

import (
	"testing"

	"github.com/jandedobbeleer/oh-my-posh/src/segments/options"
	"github.com/jandedobbeleer/oh-my-posh/src/runtime/mock"
)

func TestNewFeature(t *testing.T) {
	cases := []struct {
		Case     string
		Template string
		CustomText string
		Expected string
	}{
		{Case: "default", CustomText: "", Expected: ""},
		{Case: "custom text", CustomText: "Hello", Expected: "Hello"},
	}

	for _, tc := range cases {
		t.Run(tc.Case, func(t *testing.T) {
			env := &mock.Environment{}
			props := options.Map{
				CustomText: tc.CustomText,
			}

			segment := &NewFeature{}
			segment.Init(props, env)

			if !segment.Enabled() {
				t.Error("Expected segment to be enabled")
			}

			if segment.Text != tc.Expected {
				t.Errorf("Expected %s, got %s", tc.Expected, segment.Text)
			}
		})
	}
}

可参考现有模块测试获取更复杂的示例和灵感。

步骤七：构建与测试

通过构建项目验证实现：

go build -v

运行专属测试：

go test ./src/segments/new_feature_test.go

重要准则

文件组织规范

• 模块文件：src/segments/[segment_id].go

• 测试文件：src/segments/[segment_id]_test.go

• 文档：website/docs/segments/[category]/[segment-id].mdx### 字母顺序要求 在以下位置保持字母顺序：

• segment_types.go 文件中的 init() gob 注册项

• segment_types.go 中的模块类型常量

• segment_types.go 中的模块映射条目

• themes/schema.json 中的模式类型枚举

• themes/schema.json 的 allOf 定义项

• sidebars.js 中的侧边栏导航项

代码质量要求

• 使用语义明确的属性名和常量

• 为选项添加描述性注释

• 保持 Enabled() 逻辑精简高效

• 使用 UTF32 编码表示图标（非实际图标字符）

• 遵循 Go 命名规范（导出项采用 PascalCase）

文档编写标准

• 文档文件使用 .mdx 扩展名

• 包含完整的属性表格（类型/描述/默认值）

• 提供实际可用的配置示例

• 单行长度不超过 120 字符

• 采用规范的标题层级和格式

参考资源

• Nerd Fonts 速查表 - 获取图标 UTF32 编码

• 现有测试案例 - 测试模式参考

• 表格驱动测试 - Go 测试最佳实践

提交 Pull Request

完成所有步骤后：

1. 验证编译：执行 go build -v

2. 运行测试：go test ./src/segments/[your_segment]_test.go

3. 格式检查：确保符合 Go 代码规范

4. 核对清单：确认所有文件按规范创建/更新

5. 创建 PR：清晰描述模块功能

请耐心等待代码审查！🏎