# 星耀对象 (/zh/docs/rust/star-object)
Star 的字段与亮度、四化判断，以及 StarRef 的回溯能力。
`Star` 是一颗落在某宫的星，带着它的类型、亮度与四化标记。
`chart.star(...)` 返回 `StarRef`，在 `Star` 之上多出回溯所在宫的能力。
```rust
let ziwei = chart.star(StarKey::ZiweiMaj).unwrap();
let _name = &ziwei.name; // 经 Deref 直接取字段
let _palace = ziwei.palace(); // 视图独有：回溯所在宫
```
本页示例统一用 `Language::ZhCN` 排盘，因此输出里的展示值都是中文。
`Star` 本身不实现 `Copy`，经 `Deref` 取字段时按引用借用（`&ziwei.name`）
或克隆，不能直接搬走。
## 字段 [#字段]
| 字段 | 类型 | 说明 |
| ------------ | -------------------- | ---------------------------- |
| `key` | `StarKey` | 星耀标识，与语言无关，判断时用它 |
| `name` | `String` | 星名，按排盘语言翻译 |
| `star_type` | `StarType` | 星耀类型，见下表 |
| `scope` | `Scope` | 作用范围：本命星为 `Origin`，流耀为对应运限层级 |
| `brightness` | `Option` | 亮度；没有亮度表的星耀为 `None` |
| `mutagen` | `Option` | 生年四化；未被生年干化的星为 `None` |
### StarType 的八个取值 [#startype-的八个取值]
| 取值 | 含义 | 典型成员 |
| ----------- | ---- | ----------------- |
| `Major` | 十四主星 | 紫微、天府、七杀、破军 |
| `Soft` | 吉星 | 左辅、右弼、文昌、文曲、天魁、天钺 |
| `Tough` | 煞星 | 擎羊、陀罗、火星、铃星、地空、地劫 |
| `Adjective` | 杂耀 | 三台、八座、天刑、天姚 |
| `Flower` | 桃花星 | 红鸾、天喜、咸池 |
| `Helper` | 解神 | 解神 |
| `Lucun` | 禄存 | 禄存 |
| `Tianma` | 天马 | 天马 |
禄存与天马各自独占一类，因为它们在传统分法里既非纯吉也非纯煞，判断时常单独拎出来。
只有十四主星与文昌、文曲、火星、铃星、擎羊、陀罗这二十颗有亮度表，
其余星耀本就没有亮度概念，`brightness` 为 `None`。
***
## with\_brightness [#with_brightness]
**用途** 判断这颗星是否处于给定亮度之一。
**斗数含义** 亮度（庙旺得利平不陷）描述星耀在该宫位的强弱。
同一颗星在十二宫各有定值，庙旺则力量充分发挥，落陷则受制。
**签名**
```rust
pub fn with_brightness(&self, brightness: &[Brightness]) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ------------ | --------------- | -- | -- | ------------ |
| `brightness` | `&[Brightness]` | 是 | — | 亮度列表，命中任一即为真 |
**返回值** `bool`。该星无亮度时恒为 `false`。
**示例**
```rust
let ziwei = chart.star(StarKey::ZiweiMaj).unwrap();
println!("{}", ziwei.with_brightness(&[Brightness::Miao]));
println!("{}", ziwei.with_brightness(&[Brightness::Wang, Brightness::De]));
```
**输出**
```text
true
false
```
**边界与陷阱**
语义是「命中任一」而非「全部命中」——一颗星只有一个亮度，要求全部命中在列表多于一项时永假。
***
## with\_mutagen [#with_mutagen]
**用途** 判断这颗星是否带指定的生年四化。
**斗数含义** 生年四化由出生年干决定，一年固定四颗星分别化禄、权、科、忌。
这个标记跟着星走，无论那颗星落在哪一宫。
**签名**
```rust
pub fn with_mutagen(&self, mutagens: &[Mutagen]) -> bool
```
**参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---------- | ------------ | -- | -- | ------------ |
| `mutagens` | `&[Mutagen]` | 是 | — | 四化列表，命中任一即为真 |
**返回值** `bool`。该星未被生年干化时恒为 `false`。
**示例**
```rust
let ziwei = chart.star(StarKey::ZiweiMaj).unwrap();
let taiyang = chart.star(StarKey::TaiyangMaj).unwrap();
println!("紫微化禄: {}", ziwei.with_mutagen(&[Mutagen::Lu]));
println!("太阳化禄: {}", taiyang.with_mutagen(&[Mutagen::Lu]));
```
**输出**
```text
紫微化禄: false
太阳化禄: true
```
这张盘生年干为庚，庚干太阳化禄，因此标记落在太阳而非紫微。
**边界与陷阱**
`with_mutagen` 看的是**生年干**给这颗星打的标记，一张盘上只有四颗星带标记。
宫干飞出的四化不在这里体现，用宫位的 [`flies_to`](/zh/docs/rust/palace#flies_to--flies_one_of_to--not_fly_to) 一族。
***
## palace / opposite\_palace / surrounded\_palaces [#palace--opposite_palace--surrounded_palaces]
**用途** 从星回溯到它所在的宫、该宫的对宫与三方四正。
**签名**
```rust
pub fn palace(&self) -> PalaceRef<'a>
pub fn opposite_palace(&self) -> PalaceRef<'a>
pub fn surrounded_palaces(&self) -> SurroundedPalaces<'a>
```
**返回值** 三者都必然存在，不返回 `Option`——`StarRef` 只能由星盘查询产生，天然持有归属关系。
**示例**
```rust
let zh = Language::ZhCN;
let ziwei = chart.star(StarKey::ZiweiMaj).unwrap();
println!("{}", translate_palace(ziwei.palace().name, zh));
println!("{}", translate_palace(ziwei.opposite_palace().name, zh));
println!("同宫或三方见天相: {}", ziwei.surrounded_palaces().have(&[StarKey::TianxiangMaj]));
```
**输出**
```text
命宫
迁移
同宫或三方见天相: true
```
**边界与陷阱**
一颗星在一张盘上只出现一次，因此 `chart.star(key)` 的结果唯一。
运限流耀不在本命盘的星耀列表里，要取它们用运限对象的
[`palace`](/zh/docs/rust/horoscope#palace) 配合层级参数。