Skip to main content

yang_base/definition/ui/
hints.rs

1//! 可降级的前端提示枚举:控件、响应类别、展示位置、交互方式、可用状态与排序方向。
2
3use schemars::JsonSchema;
4use serde::{Deserialize, Serialize};
5
6/// 与存储类型解耦的前端控件提示。
7///
8/// 该值只表达建议展示方式,不改变字段验证、权限或数据库语义。消费者遇到新版本
9/// 未知值时必须降级为 [`Json`](Self::Json),而不是拒绝整个页面契约。
10#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, JsonSchema)]
11#[serde(rename_all = "snake_case")]
12#[non_exhaustive]
13pub enum WidgetHint {
14    /// 单行文本。
15    Text,
16    /// 多行文本。
17    Textarea,
18    /// 密码输入。
19    Password,
20    /// 邮箱输入。
21    Email,
22    /// URL 输入。
23    Url,
24    /// 颜色输入。
25    Color,
26    /// 富文本或编辑器输入。
27    Editor,
28    /// 整数输入。
29    Integer,
30    /// 定点小数输入。
31    Decimal,
32    /// 布尔开关。
33    Switch,
34    /// 固定枚举单选。
35    Radio,
36    /// 关系选项选择器。
37    RelationSelect,
38    /// 树关系选择器。
39    TreeSelect,
40    /// 日期时间输入。
41    DateTime,
42    /// 安全的通用 JSON/text fallback。
43    #[default]
44    #[serde(other)]
45    Json,
46}
47
48/// Action 成功响应的静态类别。
49///
50/// 该值决定前端的安全展示通道;它描述 Action 契约,不从某次运行时响应猜测。
51#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, JsonSchema)]
52#[serde(rename_all = "snake_case")]
53#[non_exhaustive]
54pub enum ActionResponseKind {
55    /// 普通 JSON 响应。
56    #[default]
57    Json,
58    /// 文件下载。
59    Download,
60    /// 浏览器内文件预览。
61    Preview,
62    /// HTTP 重定向。
63    Redirect,
64}
65
66/// Action 在通用业务 View 中的展示位置。
67///
68/// 未知值必须降级到工具栏,避免在没有行或批量选择上下文时错误传参。
69#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, JsonSchema)]
70#[serde(rename_all = "snake_case")]
71#[non_exhaustive]
72pub enum ActionPlacement {
73    /// 单行上下文操作。
74    Row,
75    /// 多选记录后的批量操作。
76    Bulk,
77    /// View 级工具栏操作,也是未知值的安全降级。
78    #[default]
79    #[serde(other)]
80    Toolbar,
81}
82
83/// Action 的声明式交互方式。
84///
85/// 该值不包含组件路径或动态代码。未知值降级为直接调用,由默认 Action 演示层
86/// 负责收集参数和展示响应。
87#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, JsonSchema)]
88#[serde(rename_all = "snake_case")]
89#[non_exhaustive]
90pub enum ActionInteraction {
91    /// 根据 Action 输入契约生成表单后调用。
92    Form,
93    /// 调用后下载文件。
94    Download,
95    /// 调用后在浏览器内预览文件。
96    Preview,
97    /// 调用后执行服务端声明的安全跳转。
98    Navigate,
99    /// 交给前端白名单注册的自定义 View。
100    Custom,
101    /// 直接调用 Action,也是未知值的安全降级。
102    #[default]
103    #[serde(other)]
104    Invoke,
105}
106
107/// 通用 View 对 Action 的非安全性可用状态提示。
108///
109/// 未声明表示正常可用。未知状态按 disabled 处理,避免前端在无法理解新状态时误触发
110/// 操作。该提示只改善界面体验,服务端仍必须独立执行授权和业务前置条件。
111#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, JsonSchema)]
112#[serde(rename_all = "snake_case")]
113#[non_exhaustive]
114pub enum AvailabilityState {
115    /// 从界面隐藏,但不能据此推断 Action 不可直接调用。
116    Hidden,
117    /// 显示为禁用,也是未知值的安全降级。
118    #[default]
119    #[serde(other)]
120    Disabled,
121}
122
123/// 通用表格排序方向。
124#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, JsonSchema)]
125#[serde(rename_all = "snake_case")]
126#[non_exhaustive]
127pub enum SortDirection {
128    /// 降序。
129    Desc,
130    /// 升序,也是未知值的兼容降级。
131    #[default]
132    #[serde(other)]
133    Asc,
134}