# 星耀对象 (/zh/docs/go/star-object)

Star 的字段与亮度、四化判断，以及回溯所在宫的能力。



`Star` 是一颗落在某宫的星，带着它的类型、亮度与四化标记，并能回溯所在宫。

```go
ziwei, palace := chart.Star(iztro.StarZiweiMaj)
```

<Callout type="info">
  本页示例统一用 `"zh-CN"` 排盘，因此输出里的展示值都是中文。
</Callout>

## 字段 [#字段]

| 字段              | 类型       | 说明                             |
| --------------- | -------- | ------------------------------ |
| `Key`           | `string` | 星耀标识，与语言无关，判断时用它               |
| `Name`          | `string` | 星名，按排盘语言翻译                     |
| `Type`          | `string` | 星耀类型，见下表                       |
| `Scope`         | `string` | 作用范围：本命星为 `"origin"`，流耀为对应运限层级 |
| `Brightness`    | `string` | 亮度译名；没有亮度表的星耀为空串               |
| `BrightnessKey` | `string` | 亮度标识                           |
| `Mutagen`       | `string` | 生年四化译名；未被生年干化的星为空串             |
| `MutagenKey`    | `string` | 四化标识                           |

### 星耀类型的八个取值 [#星耀类型的八个取值]

| 取值          | 含义   | 典型成员              |
| ----------- | ---- | ----------------- |
| `major`     | 十四主星 | 紫微、天府、七杀、破军       |
| `soft`      | 吉星   | 左辅、右弼、文昌、文曲、天魁、天钺 |
| `tough`     | 煞星   | 擎羊、陀罗、火星、铃星、地空、地劫 |
| `adjective` | 杂耀   | 三台、八座、天刑、天姚       |
| `flower`    | 桃花星  | 红鸾、天喜、咸池          |
| `helper`    | 解神   | 解神                |
| `lucun`     | 禄存   | 禄存                |
| `tianma`    | 天马   | 天马                |

禄存与天马各自独占一类，因为它们在传统分法里既非纯吉也非纯煞，判断时常单独拎出来。

<Callout type="info" title="空串而非 nil">
  Go 侧用空串表示「没有」——`Brightness` 为空串即该星没有亮度表，
  `Mutagen` 为空串即未被生年干化。判空写 `if star.MutagenKey != ""`。
</Callout>

***

## WithBrightness [#withbrightness]

**用途**　判断这颗星是否处于给定亮度之一。

**斗数含义**　亮度（庙旺得利平不陷）描述星耀在该宫位的强弱。
同一颗星在十二宫各有定值，庙旺则力量充分发挥，落陷则受制。

**签名**

```go
func (s *Star) WithBrightness(brightnessKeys ...string) bool
```

**参数**

| 参数               | 类型          | 必填 | 默认 | 说明           |
| ---------------- | ----------- | -- | -- | ------------ |
| `brightnessKeys` | `...string` | 是  | —  | 亮度标识，命中任一即为真 |

**返回值**　`bool`。该星无亮度时恒为假。

**示例**

```go
ziwei, _ := chart.Star(iztro.StarZiweiMaj)

fmt.Println(ziwei.WithBrightness(iztro.BrightnessMiao))
fmt.Println(ziwei.WithBrightness(iztro.BrightnessWang, iztro.BrightnessDe))
```

**输出**

```text
true
false
```

**边界与陷阱**

<Callout type="warn">
  语义是「命中任一」而非「全部命中」——一颗星只有一个亮度，
  传多个只表示「是其中之一即可」。
</Callout>

***

## WithMutagen [#withmutagen]

**用途**　判断这颗星是否带指定的生年四化。

**斗数含义**　生年四化由出生年干决定，一年固定四颗星分别化禄、权、科、忌。
这个标记跟着星走，无论那颗星落在哪一宫。

**签名**

```go
func (s *Star) WithMutagen(mutagenKeys ...string) bool
```

**参数**

| 参数            | 类型          | 必填 | 默认 | 说明           |
| ------------- | ----------- | -- | -- | ------------ |
| `mutagenKeys` | `...string` | 是  | —  | 四化标识，命中任一即为真 |

**返回值**　`bool`。该星未被生年干化时恒为假。

**示例**

```go
ziwei, _ := chart.Star(iztro.StarZiweiMaj)
taiyang, _ := chart.Star(iztro.StarTaiyangMaj)

fmt.Println("紫微化禄:", ziwei.WithMutagen(iztro.MutagenLu))
fmt.Println("太阳化禄:", taiyang.WithMutagen(iztro.MutagenLu))
```

**输出**

```text
紫微化禄: false
太阳化禄: true
```

这张盘生年干为庚，庚干太阳化禄，因此标记落在太阳而非紫微。

**边界与陷阱**

<Callout type="info" title="生年四化与飞星四化不是一回事">
  `WithMutagen` 看的是**生年干**给这颗星打的标记，一张盘上只有四颗星带标记。
  宫干飞出的四化不在这里体现，用宫位的 [`FliesTo`](/zh/docs/go/palace#fliesto--fliesoneofto--notflyto) 一族。
</Callout>

***

## Palace / OppositePalace / SurroundedPalaces [#palace--oppositepalace--surroundedpalaces]

**用途**　从星回溯到它所在的宫、该宫的对宫与三方四正。

**签名**

```go
func (s *Star) Palace() *Palace
func (s *Star) OppositePalace() *Palace
func (s *Star) SurroundedPalaces() *SurroundedPalaces
```

**返回值**　脱离星盘单独构造的星耀返回 `nil`；由星盘查询得到的星耀必然非空。

**示例**

```go
ziwei, _ := chart.Star(iztro.StarZiweiMaj)

fmt.Println(ziwei.Palace().Name)
fmt.Println(ziwei.OppositePalace().Name)
fmt.Println("同宫或三方见天相:",
    ziwei.SurroundedPalaces().Have(iztro.StarTianxiangMaj))
```

**输出**

```text
命宫
迁移
同宫或三方见天相: true
```

**边界与陷阱**

<Callout type="info">
  `chart.Star()` 已经把所在宫作为第二个返回值给出，
  通常不必再调 `ziwei.Palace()`。
</Callout>