Agregar un Segmento

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

Agregar un nuevo segmento a Oh My Posh requiere varios pasos para garantizar una integración adecuada. Esta guía te llevará por el proceso de crear un segmento completo con todos los archivos y registros necesarios.

Planificación de tu segmento

Antes de programar, define estas propiedades clave:

ID del segmento: Identificador en kebab-case usado en configuraciones (ej: new-feature)
Nombre del tipo en Go: Nombre de estructura en PascalCase para el código (ej: NewFeature)
Categoría: Elige entre cli, cloud, health, languages, music, scm, system o web
Descripción: Explicación clara de una línea sobre lo que hace el segmento
Propiedades: Lista de propiedades configurables con tipos y valores predeterminados
Plantilla: Cadena de plantilla predeterminada (ej: {{ .Text }})

Configuración automatizada (VS Code)

Si usas VS Code, puedes utilizar el comando automatizado de creación de segmentos en el Chat de VS Code:

Abre el Chat de VS Code (usa el ícono de Chat en la barra lateral o en la Paleta de Comandos: "Chat: Focus on Chat View")
Escribe /segment y sigue las indicaciones
Proporciona los detalles de tu segmento cuando se soliciten
El comando creará automáticamente todos los archivos y registros necesarios

Este enfoque automatizado garantiza que todos los archivos se creen correctamente con las convenciones de nomenclatura adecuadas y orden alfabético. Si prefieres crear el segmento manualmente o quieres entender el proceso, continúa con los pasos manuales a continuación.

Pasos de configuración manual

Paso 1: Crear la implementación en Go

Crea un nuevo archivo en ./src/segments/ con el nombre de tu ID de segmento: 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 }}"
}

Pautas clave:

Usa representación UTF32 para los íconos (ej: "\uEFF1") en lugar de los íconos reales
Encuentra códigos de íconos en la Hoja de referencia de Nerd Fonts
Mantén la lógica en Enabled() enfocada en preparación de datos y determinación de visibilidad

Paso 2: Registrar tu segmento

Edita src/config/segment_types.go para registrar tu nuevo segmento:

Añadir registro Gob

En la función init(), añade tu segmento al registro gob (mantén el orden alfabético):

gob.Register(&segments.NewFeature{})

Añadir constante de segmento

Añade una constante para tu tipo de segmento (mantén el orden alfabético):

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

Añadir al mapa de segmentos

Registra tu segmento en el mapa Segments (mantén el orden alfabético):

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

Paso 3: Crear documentación

Crea documentación en 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        |

Paso 4: Actualizar navegación lateral

Edita website/sidebars.js y añade tu documentación a la categoría correspondiente (mantén el orden alfabético):

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

Paso 5: Añadir definición de esquema JSON

Actualiza themes/schema.json en dos lugares:

Añadir al enum de tipos

En el enum de tipos de segmentos, añade tu ID de segmento (mantén el orden alfabético):

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

Añadir definición de esquema

En el arreglo allOf, añade el esquema de propiedades de tu segmento (mantén el orden alfabético):

{
  "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": ""
          }
        }
      }
    }
  }
}

Paso 6: Añadir pruebas

Crea un archivo de pruebas src/segments/new_feature_test.go usando pruebas basadas en tablas:

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)
			}
		})
	}
}

Consulta los tests de segmentos existentes para ver ejemplos más complejos y obtener inspiración.

Paso 7: Compilar y Probar

Valida tu implementación compilando el proyecto:

go build -v

Ejecuta tus tests específicos:

go test ./src/segments/new_feature_test.go

Directrices Importantes

Organización de Archivos

Archivos de segmento: src/segments/[segment_id].go
Archivos de test: src/segments/[segment_id]_test.go
Documentación: website/docs/segments/[category]/[segment-id].mdx### Orden Alfabético Mantén el orden alfabético en:
Registros gob en init() de segment_types.go
Constantes de tipos de segmento en segment_types.go
Entradas del mapa de segmentos en segment_types.go
Enumeración de tipos en el esquema en themes/schema.json
Definiciones allOf en themes/schema.json
Elementos de navegación en sidebars.js

Calidad de Código

Usa nombres de propiedades y constantes significativos
Incluye comentarios descriptivos para las opciones
Mantén la lógica en Enabled() enfocada y eficiente
Usa códigos UTF32 para íconos, no los íconos reales
Sigue convenciones de nombres en Go (PascalCase para elementos exportados)

Estándares de Documentación

Usa extensión .mdx para archivos de documentación
Incluye tablas completas de propiedades con tipos, descripciones y valores predeterminados
Proporciona configuraciones de ejemplo realistas
Mantén líneas de máximo 120 caracteres
Usa encabezados y formato adecuados

Recursos

Hoja de referencia de Nerd Fonts - Busca códigos UTF32 para íconos
Tests existentes - Ejemplos de patrones de pruebas
Pruebas basadas en tablas - Mejores prácticas para tests en Go

Crear un Pull Request

Una vez completados todos los pasos:

Verifica que todo compile: go build -v
Ejecuta tests: go test ./src/segments/[your_segment]_test.go
Revisa formato: Asegura que tu código siga los estándares de formato de Go
Revisa checklist: Todos los archivos creados/actualizados como se describió
Crea el PR: Incluye una descripción clara de lo que hace tu segmento

¡Sé paciente durante el proceso de revisión! 🏎

Planificación de tu segmento​

Configuración automatizada (VS Code)​

Pasos de configuración manual​

Paso 1: Crear la implementación en Go​

Paso 2: Registrar tu segmento​

Añadir registro Gob​

Añadir constante de segmento​

Añadir al mapa de segmentos​

Paso 3: Crear documentación​

Paso 4: Actualizar navegación lateral​

Paso 5: Añadir definición de esquema JSON​

Añadir al enum de tipos​

Añadir definición de esquema​

Paso 6: Añadir pruebas​

Paso 7: Compilar y Probar​

Directrices Importantes​

Organización de Archivos​

Calidad de Código​

Estándares de Documentación​

Recursos​

Crear un Pull Request​