Skip to main content

yang_base/definition/ui/
action.rs

1//! Action 展示语义:二次确认、可用性提示与构建期/请求级展示契约。
2
3use super::hints::{ActionInteraction, ActionPlacement, AvailabilityState};
4use schemars::JsonSchema;
5use serde::{Deserialize, Serialize};
6
7/// 危险或不可逆 Action 的二次确认文案。
8#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
9pub struct ActionConfirmation {
10    /// 确认框标题。
11    pub title: String,
12    /// 确认框正文。
13    pub message: String,
14}
15
16impl ActionConfirmation {
17    /// 创建二次确认文案。
18    pub fn new(title: impl Into<String>, message: impl Into<String>) -> Self {
19        Self {
20            title: title.into(),
21            message: message.into(),
22        }
23    }
24}
25
26/// Action 的展示可用性与用户可见原因。
27#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
28pub struct AvailabilityHint {
29    /// 隐藏或禁用提示。
30    pub state: AvailabilityState,
31    /// 用户可见原因;构建期拒绝空白和超长内容。
32    pub reason: String,
33}
34
35impl AvailabilityHint {
36    /// 创建禁用提示。
37    pub fn disabled(reason: impl Into<String>) -> Self {
38        Self {
39            state: AvailabilityState::Disabled,
40            reason: reason.into(),
41        }
42    }
43
44    /// 创建隐藏提示。
45    pub fn hidden(reason: impl Into<String>) -> Self {
46        Self {
47            state: AvailabilityState::Hidden,
48            reason: reason.into(),
49        }
50    }
51}
52
53/// View 构建期声明的 Action 展示语义。
54///
55/// [`Custom`](ActionInteraction::Custom) 必须同时声明稳定 `view_id`;其它交互禁止
56/// 携带 `view_id`,避免把它误用为物理文件路径。
57#[derive(Debug, Clone, PartialEq, Eq)]
58pub struct ActionPresentationSpec {
59    /// Action 展示位置。
60    pub placement: ActionPlacement,
61    /// Action 交互方式。
62    pub interaction: ActionInteraction,
63    /// 可选二次确认。
64    pub confirmation: Option<ActionConfirmation>,
65    /// 可选的非安全性可用提示。
66    pub availability: Option<AvailabilityHint>,
67    /// 前端白名单注册表中的稳定标识。
68    pub view_id: Option<String>,
69    /// 行上下文记录标识应写入的 Action 参数。
70    pub record_parameter: Option<String>,
71}
72
73impl ActionPresentationSpec {
74    /// 创建显式展示声明。
75    pub fn new(placement: ActionPlacement, interaction: ActionInteraction) -> Self {
76        Self {
77            placement,
78            interaction,
79            confirmation: None,
80            availability: None,
81            view_id: None,
82            record_parameter: None,
83        }
84    }
85
86    /// 设置二次确认文案。
87    #[must_use]
88    pub fn confirmation(mut self, confirmation: ActionConfirmation) -> Self {
89        self.confirmation = Some(confirmation);
90        self
91    }
92
93    /// 设置展示可用性提示。
94    #[must_use]
95    pub fn availability(mut self, availability: AvailabilityHint) -> Self {
96        self.availability = Some(availability);
97        self
98    }
99
100    /// 设置自定义 View 的稳定白名单标识。
101    #[must_use]
102    pub fn view_id(mut self, view_id: impl Into<String>) -> Self {
103        self.view_id = Some(view_id.into());
104        self
105    }
106
107    /// 设置行上下文记录标识对应的 Action 参数。
108    #[must_use]
109    pub fn record_parameter(mut self, parameter: impl Into<String>) -> Self {
110        self.record_parameter = Some(parameter.into());
111        self
112    }
113}
114
115/// 请求级 Action 展示契约。
116#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)]
117pub struct ActionPresentationSchema {
118    /// 全局唯一 operation id。
119    pub operation_id: String,
120    /// 用户可见标题。
121    pub title: String,
122    /// Action 展示位置。
123    pub placement: ActionPlacement,
124    /// Action 交互方式。
125    pub interaction: ActionInteraction,
126    /// 可选二次确认。
127    pub confirmation: Option<ActionConfirmation>,
128    /// 可选的非安全性可用提示。
129    pub availability: Option<AvailabilityHint>,
130    /// 前端白名单注册表中的稳定标识;仅 custom 交互可用。
131    pub view_id: Option<String>,
132    /// 行上下文记录标识应写入的 Action 参数;仅 row 位置可用。
133    pub record_parameter: Option<String>,
134}