x-iztro
x-iztroRustPythonGo

星盘对象

Astrolabe 的字段、定位方法与三方四正判断。

Astrolabe 是排盘的产物，也是一切查询的入口。它持有十二宫的全部数据， 以及四柱、命主身主、五行局这些盘级信息。

let chart = by_solar("2000-8-16", 2, Gender::Female, true, Language::ZhCN, Config::default())?;

本页示例统一用 Language::ZhCN 排盘，因此输出里的展示值都是中文。 换成别的语言只改这些展示串，*_key 标识与所有判断方法的结果不变。

字段

palace

用途　按索引、宫名、身宫或来因宫取一宫。

斗数含义　十二宫是斗数的骨架。命宫定下后，其余十一宫按固定顺序逆时针排开。 「身宫」是十二宫之一同时被标记的那一宫，代表后天着力处； 「来因宫」是宫干与生年干相同的那一宫，代表事情的起因。

签名

pub fn palace(&self, target: impl Into<PalaceTarget>) -> Option<PalaceRef<'_>>

参数

参数类型必填默认说明
targetimpl Into<PalaceTarget>是—四种写法见下表

PalaceTarget 的四个变体都有 From 实现，调用时直接写值即可：

写法例子含义
索引chart.palace(0)宫位索引 0–11，0 为寅宫
宫名chart.palace(Palace::Soul)十二宫名之一
身宫chart.palace(PalaceTarget::Body)带身宫标记的那一宫
来因宫chart.palace(PalaceTarget::Original)宫干与生年干相同的那一宫

返回值　Option<PalaceRef<'_>>。索引越界返回 None；宫名、身宫、来因宫三种写法在任何一张盘上都能定位到，不会是 None。

示例

let zh = Language::ZhCN;

let soul = chart.palace(Palace::Soul).unwrap();
println!("{} {}{}", translate_palace(soul.name, zh),
    translate_heavenly_stem(soul.heavenly_stem, zh),
    translate_earthly_branch(soul.earthly_branch, zh));

let body = chart.palace(PalaceTarget::Body).unwrap();
println!("身宫落在 {}", translate_palace(body.name, zh));

let original = chart.palace(PalaceTarget::Original).unwrap();
println!("来因宫是 {}", translate_palace(original.name, zh));

println!("寅宫是 {}", translate_palace(chart.palace(0).unwrap().name, zh));

PalaceData::name 的类型是 Palace 枚举而非字符串，不能直接用 {} 打印—— 枚举是语言无关标识，展示时经 translate_palace 转成当前语言的文本。 heavenly_stem、earthly_branch、five_elements_class 等字段同理。

输出

命宫 壬午
身宫落在 官禄
来因宫是 夫妻
寅宫是 财帛

边界与陷阱

star

用途　按标识找到一颗星，得到能回溯所在宫的视图。

签名

pub fn star(&self, key: StarKey) -> Option<StarRef<'_>>

参数

参数类型必填默认说明
keyStarKey是—星耀标识，如 StarKey::ZiweiMaj

返回值　Option<StarRef<'_>>。该星不在这张盘上时返回 None。

示例

let zh = Language::ZhCN;
let ziwei = chart.star(StarKey::ZiweiMaj).unwrap();

println!("{} 在 {}", ziwei.name, translate_palace(ziwei.palace().name, zh));
println!("对宫是 {}", translate_palace(ziwei.opposite_palace().name, zh));
println!("亮度 {:?} 四化 {:?}", ziwei.brightness, ziwei.mutagen);

Star::name 是 String（排盘时已按语言翻译好），可以直接打印； 宫名 PalaceData::name 是枚举，要经 translate_palace。

输出

紫微 在 命宫
对宫是 迁移
亮度 Some(Miao) 四化 None

边界与陷阱

只在主星、辅星、杂耀三组里查找。长生十二神、博士十二神、岁前与将前十二神 是每宫一个的标记而非星耀列表，用 palace.changsheng12 一类字段直接取。

surrounded_palaces

用途　取目标宫的三方四正。

斗数含义　三方四正是斗数最常用的取象范围：本宫、对宫（本宫 +6）、 官禄位（本宫 +4）、财帛位（本宫 +8）。四个宫合起来看，而不只看本宫， 是因为对宫与三合宫的星耀同样作用于本宫的事。

签名

pub fn surrounded_palaces(&self, target: impl Into<PalaceTarget>) -> Option<SurroundedPalaces<'_>>

参数　同 palace，四种定位写法都支持。

返回值　Option<SurroundedPalaces<'_>>，含 target / opposite / wealth / career 四个 &PalaceData（不是 PalaceRef，字段可直接读，但没有对宫、飞星那些需要星盘上下文的方法）。 判断方法见三方四正。

示例

let zh = Language::ZhCN;
let sp = chart.surrounded_palaces(Palace::Soul).unwrap();

println!("{} / {} / {} / {}",
    translate_palace(sp.target.name, zh), translate_palace(sp.opposite.name, zh),
    translate_palace(sp.wealth.name, zh), translate_palace(sp.career.name, zh));
println!("三方四正见紫微: {}", sp.have(&[StarKey::ZiweiMaj]));

输出

命宫 / 迁移 / 财帛 / 官禄
三方四正见紫微: true

is_surrounded / is_surrounded_one_of / not_surrounded

用途　直接在星盘上判断某宫的三方四正里有没有指定星耀，省去先取三方四正的一步。

签名

pub fn is_surrounded(&self, target: impl Into<PalaceTarget>, stars: &[StarKey]) -> bool
pub fn is_surrounded_one_of(&self, target: impl Into<PalaceTarget>, stars: &[StarKey]) -> bool
pub fn not_surrounded(&self, target: impl Into<PalaceTarget>, stars: &[StarKey]) -> bool

参数

参数类型必填默认说明
targetimpl Into<PalaceTarget>是—定位方式同 palace
stars&[StarKey]是—星耀标识列表

返回值

方法语义
is_surrounded列表中每一颗都在三方四正里
is_surrounded_one_of列表中至少一颗在三方四正里
not_surrounded列表中一颗都不在三方四正里

示例

use x_iztro::StarKey::*;

println!("{}", chart.is_surrounded(Palace::Soul, &[ZiweiMaj, TianxiangMaj]));
println!("{}", chart.is_surrounded_one_of(Palace::Soul, &[QishaMaj, PojunMaj]));
println!("{}", chart.not_surrounded(Palace::Soul, &[HuoxingMin]));

输出

true
false
true

命宫只坐紫微，天相在三方之一的财帛宫，因此第一行为 true； 七杀与破军都不在这四宫内，第二行为 false。

边界与陷阱

空列表的返回值

stars 传空切片时，is_surrounded 与 not_surrounded 返回 true （「所有元素都满足」与「没有元素不满足」对空集都成立）， is_surrounded_one_of 返回 false。调用前先确认列表非空。

horoscope / horoscope_now

用途　以本盘为起点计算目标日期的运限。

签名

pub fn horoscope(&self, target_date: &str, target_time_index: u8) -> Result<HoroscopeRef<'_>, IztroError>
pub fn horoscope_now(&self) -> Result<HoroscopeRef<'_>, IztroError>

参数

参数类型必填默认说明
target_date&str是—目标公历日期，格式 YYYY-M-D
target_time_indexu8是—目标时辰索引 0–12，决定流时

horoscope_now 取本地时钟的当前日期与当前时辰，无参数。

返回值　HoroscopeRef<'_>——持有本盘的运限视图，六个层级的宫位查询不必再传星盘。 详见运限对象。

示例

let zh = Language::ZhCN;
let h = chart.horoscope("2025-6-1", 0)?;

println!("大限 {}{}",
    translate_heavenly_stem(h.decadal.heavenly_stem, zh),
    translate_earthly_branch(h.decadal.earthly_branch, zh));
println!("流年 {}{}",
    translate_heavenly_stem(h.yearly.heavenly_stem, zh),
    translate_earthly_branch(h.yearly.earthly_branch, zh));

decadal / monthly / daily / hourly 是 HoroscopeItem，干支直接读； yearly 与 age 各自多带一项自己的数据（通用字段收在 base 里）， 但两者都实现了 Deref，h.yearly.heavenly_stem 同样直接可读。

输出

大限 庚辰
流年 乙巳

to_dto

用途　把星盘转成与 JS iztro 字段契约一致的序列化结构。

签名

pub fn to_dto(&self) -> AstrolabeDto

返回值　x_iztro::dto::AstrolabeDto——camelCase 键、值按排盘语言翻译， 另带 *Key 语言无关标识与排盘上下文（genderKey / timeIndex / fixLeap / language / config）。 字段清单见数据结构。

示例

let dto = chart.to_dto();
let json = serde_json::to_string(&dto)?;
let v: serde_json::Value = serde_json::from_str(&json)?;

println!("{} {}", v["solarDate"], v["palaces"][4]["nameKey"]);
println!("{}", v["config"]["yearDivide"]);

输出

"2000-8-16" "soulPalace"
"normal"

边界与陷阱

DTO 是给跨语言绑定与前端用的。Rust 侧做分析请直接用 Astrolabe—— 它有全部查询方法，DTO 只有数据。想一步拿到 JSON 字符串用 by_solar_json。

Config 的 overrides（自定义四化与亮度表）不进 DTO：它是排盘输入而非结果， 回显会破坏与 JS iztro 的字段契约。

排盘入口

by_solar、by_lunar、rearranged 与 JSON 便捷版本。

宫位对象

PalaceData 的字段，以及星耀判断、空宫判断与飞星族的全部方法。

本页目录

字段palacestarsurrounded_palacesis_surrounded / is_surrounded_one_of / not_surroundedhoroscope / horoscope_nowto_dto