cdp-material-sdk 0.0.5 → 0.0.9

package/docs/component-development/recipes//345/243/260/346/230/216props.md

@@ -0,0 +1,313 @@
+---
+type: recipe
+capability: props
+related:
+  - reference/Manifest字段参考.md
+  - reference/Traits能力模型.md
+  - reference/validateManifest校验规则.md
+  - recipes/使用Adapter适配组件API.md
+  - recipes/声明数据字段组件.md
+---
+# 声明 props
+
+`props` 是组件向**设计器、表达式、AI 工具**暴露的**可配置项契约**。它使用标准 JSON Schema——具体类型为 `ObjectSchema extends JSONSchema7`，要求 `type: 'object'`，`properties` 内每项是 `ExtendedJSONSchema7`（在标准 JSON Schema 之上加了少量 CDP 设计器扩展字段）。
+
+manifest 的 `props` **不是 React 组件 props 接口的镜像**：前者是面向设计器的声明、用 schema 表达；后者是组件运行时接收的参数、用 TS 类型表达。两者会重叠，但语义和职责不同。
+
+---
+
+## 适用场景
+
+- 组件有用户/设计器**可配置**的输入项（占位符、列配置、模式枚举、阈值）。
+- 组件需要让表达式或 AI 工具读取、推断、生成配置。
+- 组件需要把第三方 prop 通过设计器暴露给业务用户。
+
+---
+
+## 可以跳过的情况
+
+- 组件是纯展示，没有可配置项 → 整个 `props` 字段省略即可。
+- 字段已经由 trait 自动注入（如 `DATA_FIELD` 的 `value` / `readOnly` / `required` / `name` / `label` / `labelStrategy`）→ 不要重复声明。
+- 字段是组件**内部运行时状态** → 走 `state`。
+- 字段是**命令式调用** → 走 `actions`。
+- 字段是**事件**（含回调） → 走 `events` / `customEvents`。
+
+---
+
+## 作者职责
+
+1. 顶层结构是 `{ type: 'object', properties: { ... } }`，遵循 `ObjectSchema`。
+2. 每个字段给出合适的 `type` 和 **`title`**（设计器作为字段标签使用，`validateManifest()` 缺失会 warning）。
+3. 设计器需要选项的字段，用 `oneOf` 配 `{ const, title }`（更友好）或 `enum`（仅值列表）。
+4. 嵌套配置用 `type: 'object' + properties` 或 `type: 'array' + items`。
+5. 默认值写在 `default` 字段，**而不是**依赖 React 组件的参数默认值——后者设计器看不到。
+6. **不要重复声明 trait 自动注入的 props**，除非确有特化需求并能在 PR / 注释中说明原因。
+7. **不要把事件回调、内部状态、宿主注入的运行时数据写进 `props`**。
+
+---
+
+## 基础写法
+
+```ts
+props: {
+  type: 'object',
+  properties: {
+    placeholder: { type: 'string', title: '占位提示' },
+    maxLength: { type: 'number', title: '最大长度', default: 100 },
+    disabled: { type: 'boolean', title: '禁用' },
+  },
+},
+```
+
+---
+
+## title / description / default
+
+| 字段 | 用途 |
+|------|------|
+| `title` | 设计器中展示的字段标签；建议每个 prop 都写 |
+| `description` | 鼠标提示 / AI 上下文；复杂或易误用的字段建议写 |
+| `default` | 设计器为字段填入的默认值；写在这里而不是 React 组件的参数默认值上，设计器才能感知 |
+
+```ts
+search: {
+  type: 'array',
+  title: '搜索栏字段',
+  description: '在表格上方渲染搜索条件',
+  items: {
+    type: 'object',
+    properties: {
+      width: { type: 'number', title: '宽度(px)', default: 180 },
+    },
+  },
+},
+```
+
+---
+
+## 枚举：oneOf / enum
+
+需要给设计器下拉选项的字段，**用 `oneOf` 配 `{ const, title }`**——`const` 是值，`title` 是显示文本。比裸 `enum` 更友好，因为可以为每个值单独指定中文标签：
+
+```ts
+align: {
+  type: 'string',
+  title: '对齐',
+  oneOf: [
+    { const: 'left', title: '左对齐' },
+    { const: 'center', title: '居中' },
+    { const: 'right', title: '右对齐' },
+  ],
+},
+```
+
+只有值列表、不需要差异化标签时，用 `enum`：
+
+```ts
+size: {
+  type: 'string',
+  title: '尺寸',
+  enum: ['small', 'medium', 'large'],
+},
+```
+
+---
+
+## 嵌套 — 对象与数组
+
+**对象**：
+
+```ts
+sort: {
+  type: 'object',
+  title: '排序',
+  properties: {
+    enable: { type: 'boolean', title: '启用排序' },
+  },
+},
+```
+
+**数组（`items` 是对象）**：
+
+```ts
+columns: {
+  type: 'array',
+  title: '列配置',
+  items: {
+    type: 'object',
+    properties: {
+      title: { type: 'string', title: '列标题' },
+      dataIndex: { type: 'string', title: '字段名', format: 'dataField' },
+      width: { type: 'number', title: '列宽' },
+    },
+  },
+},
+```
+
+数组与对象可以多层嵌套（参见 Table 组件 `props.columns[*].filter.options[*]` 这类三层结构）。设计器会按嵌套结构折叠/展开。
+
+---
+
+## format — 设计器控件提示
+
+`format` 是 JSON Schema 标准字段，CDP 设计器消费它来选择更合适的控件。常见值：
+
+| `format` | 设计器表现 |
+|----------|------------|
+| `'dataField'` | 字段选择器（可选当前作用域内的数据字段） |
+| `'panelButton'` | 按钮选择器 |
+| `'color'` | 颜色选择器 |
+| `'icon'` | 图标选择器 |
+| `'expression'` | 表达式编辑器 |
+
+```ts
+dataIndex: { type: 'string', title: '字段名', format: 'dataField' },
+```
+
+未列出的 `format` 由设计器/物料各自约定，CDP 不强制。
+
+---
+
+## 与 trait 自动注入 props 的边界
+
+trait 会向 manifest 自动注入一组 props，作者**不要在 `props.properties` 里重复声明**——重复声明会**覆盖**引擎注入版本，丢失自动特化（典型是 `DATA_FIELD` 对 `value` 的 `valueSchema` 特化）。详见 [Traits 能力模型](../reference/Traits能力模型.md)。
+
+| trait | 自动注入的 props | 写进 `props.properties`？ |
+|-------|------------------|--------------------------|
+| `DATA_FIELD` | `value` / `readOnly` / `required` / `name` / `label` / `labelStrategy` | **否**（除非确有特化需求） |
+
+`props.properties` 只写**业务专属**字段（如 `placeholder` / `maxLength` / 枚举选项 / 嵌套配置）。
+
+---
+
+## 与 adapter.propMapping 的协作
+
+`props.properties` 的 key 是**面向设计器的 CDP 名**；如果 React 组件实际接收的 prop 名不同（如第三方组件使用 `selectedValue`），通过 `adapter.propMapping` 在引擎层映射，**`props.properties` 不需要跟着改名**：
+
+```ts
+props: {
+  type: 'object',
+  properties: {
+    value: { type: 'string', title: '值' },
+  },
+},
+adapter: {
+  propMapping: {
+    value: 'selectedValue',
+  },
+},
+```
+
+完整决策见 [使用 Adapter 适配组件 API · wrapper vs adapter 决策框架](./使用Adapter适配组件API.md#wrapper-vs-adapter-决策框架)。
+
+---
+
+## ExtendedJSONSchema7 扩展字段
+
+CDP 在标准 JSON Schema 之上加了少量 `x-` 字段（`ExtendedJSONSchema7`），用于设计器特定能力：
+
+| 字段 | 用途 |
+|------|------|
+| `'x-dynamic-enum'` | 动态枚举来源配置（运行时拉取选项） |
+| `'x-slot'` | 标记该字段对应一个插槽 |
+| `'x-editableSelectOptions'` | 可编辑下拉选项 |
+| `placeholder` | 设计器输入框的占位文本 |
+| `allowedTabs` | 多 tab 设计器面板中允许出现该字段的 tab 列表 |
+
+具体语义和触发条件由设计器维护，本文档不展开。
+
+---
+
+## 完整示例
+
+```ts
+import {
+  COMPONENT_CATEGORY,
+  COMPONENT_TRAIT,
+  INJECT_PATH_SLOT_PROPS,
+  type ComponentManifest,
+} from 'cdp-material-sdk/portable';
+
+export const acmeInputManifest = {
+  type: 'acme.Input',
+  traits: [COMPONENT_TRAIT.DATA_FIELD],
+  meta: {
+    title: '输入框',
+    category: COMPONENT_CATEGORY.DATA_ENTRY,
+    valueSchema: { type: 'string', default: '' },
+  },
+  engine: {
+    render: { injection: { rootPath: INJECT_PATH_SLOT_PROPS } },
+  },
+  // value / readOnly / required / name / label / labelStrategy 由 DATA_FIELD trait 自动注入，不在此声明
+  props: {
+    type: 'object',
+    properties: {
+      placeholder: { type: 'string', title: '占位提示' },
+      maxLength: { type: 'number', title: '最大长度' },
+      align: {
+        type: 'string',
+        title: '对齐',
+        oneOf: [
+          { const: 'left', title: '左对齐' },
+          { const: 'center', title: '居中' },
+          { const: 'right', title: '右对齐' },
+        ],
+      },
+    },
+  },
+} satisfies ComponentManifest;
+```
+
+---
+
+## 自检
+
+- [ ] 顶层是 `{ type: 'object', properties: { ... } }`。
+- [ ] 每个字段都有 `title`。
+- [ ] 枚举类字段用 `oneOf` 配 `{ const, title }` 或 `enum`。
+- [ ] 嵌套结构正确使用 `type: 'object' + properties` 或 `type: 'array' + items`。
+- [ ] 默认值写 `default`，不依赖 React 组件参数默认值。
+- [ ] **没有**重复声明 trait 自动注入的 props（除非确有特化需求并能说明）。
+- [ ] **没有**把事件回调或运行时状态写进 `props`。
+- [ ] `validateManifest()` 没有 error。
+
+---
+
+## 常见错误
+
+### 把所有 React props 都搬进 manifest
+
+manifest `props` 是**对外可配置项契约**，不是 React props 接口的镜像。运行时回调（`onChange`）、内部状态、宿主注入的运行时数据都不该出现在这里。
+
+### 重复声明 trait 自动注入的 props
+
+`DATA_FIELD` 已自动注入 `value` / `readOnly` / `required` / `name` / `label` / `labelStrategy`。再写一遍会**覆盖**引擎版本，丢失 `valueSchema` 特化。仅在确有特化需求（收窄类型、补更具体的 `title` / `description`）时显式覆盖，并在 PR / 注释中说明原因。
+
+### 默认值写在 React 组件而不是 `default`
+
+React 组件参数默认值设计器看不到，物料面板也无法预填。把面向设计器的默认值写在 `props.properties.X.default`。
+
+### 把 manifest props key 当成 React prop 名
+
+`props.properties` 的 key 是**面向设计器的 CDP 名**。第三方组件实际接收的 prop 名不同时，用 `adapter.propMapping` 在引擎层映射，不要为了贴合第三方而改 manifest key——manifest key 才是表达式、AI、配置 UI 看到的稳定名字。
+
+### 缺 `title`
+
+`validateManifest()` 会 warning。设计器没有 `title` 时会 fallback 到 key 名，体验差且不利于 i18n。
+
+### 用 `enum` 代替 `oneOf` 失去差异化标签
+
+`enum` 只有值列表，设计器只能直接显示值字符串。需要每个选项有中文标签时改用 `oneOf` 配 `{ const, title }`。
+
+---
+
+## 关联文档
+
+本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
+
+- 字段参考：[Manifest 字段参考](../reference/Manifest字段参考.md)
+- 模型参考：[Traits 能力模型](../reference/Traits能力模型.md)
+- 校验规则：[validateManifest 校验规则](../reference/validateManifest校验规则.md)
+- 任务 Recipe：[使用 Adapter 适配组件 API](./使用Adapter适配组件API.md)
+- 任务 Recipe：[声明数据字段组件](./声明数据字段组件.md)

package/docs/component-development/recipes//345/243/260/346/230/216/346/225/260/346/215/256/345/255/227/346/256/265/347/273/204/344/273/266.md

@@ -5,7 +5,9 @@ related:
   - reference/Traits能力模型.md
   - reference/Manifest字段参考.md
   - reference/validateManifest校验规则.md
+  - recipes/声明props.md
   - recipes/使用Adapter适配组件API.md
+  - reference/Events模型.md
 ---
 # 声明数据字段组件
 
@@ -33,9 +35,9 @@ related:
 
 1. 在 `traits` 中声明 `COMPONENT_TRAIT.DATA_FIELD`。
 2. 在 `meta.valueSchema` 中描述 value 类型。
-3. 组件接收 `value`。
-4. 值变化时调用 `onChange(nextValue)`。
-5. 如果组件在容器内使用，建议支持 `name` prop。
+3. 组件接收 `value`，值变化时调用 `onChange(nextValue)`。
+4. 如组件支持只读/必填/标签语义，分别接收并应用 `readOnly` / `required` / `label`；置于容器内时支持 `name`。
+5. 一般不需要自己声明 `value` / `readOnly` / `required` / `name` / `label` / `labelStrategy` props，也不需要重复声明 `getValue` / `setValue` / `getReadOnly` / `setReadOnly` / `toggleReadOnly` / `getRequired` / `setRequired` / `toggleRequired` / `triggerValueChange` actions、`value` / `readOnly` / `required` state 或 `valueChange` event——它们由引擎在 `DATA_FIELD` trait 上自动注入并按 `valueSchema` 特化。重复声明会**覆盖**引擎版本，会丢失自动特化；**仅在确有特化需求**（如定制 setValue 取值规则）时才建议显式覆盖。完整字段规格见 [Traits能力模型 · DATA_FIELD](../reference/Traits能力模型.md#data_field)。
 
 ---
 
@@ -48,16 +50,25 @@ import type { BaseUIProps } from 'cdp-material-sdk/portable';
 export interface AcmeInputProps extends BaseUIProps<HTMLInputElement> {
   value?: string;
   onChange?: (value: string) => void;
+  readOnly?: boolean;
+  required?: boolean;
+  name?: string;
+  label?: string;
+  placeholder?: string;
 }
 
 export const AcmeInput = forwardRef<HTMLInputElement, AcmeInputProps>((props, ref) => {
-  const { value = '', onChange, slotProps } = props;
+  const { value = '', onChange, readOnly, required, name, slotProps, placeholder } = props;
 
   return (
     <input
       {...slotProps?.root}
       ref={ref}
       value={value}
+      readOnly={readOnly}
+      required={required}
+      name={name}
+      placeholder={placeholder}
       onChange={(event) => onChange?.(event.target.value)}
     />
   );
@@ -95,23 +106,106 @@ export const acmeInputManifest = {
       placeholder: { type: 'string', title: '占位提示' },
     },
   },
+  // value / readOnly / required / name / label / labelStrategy props
+  // getValue / setValue / getReadOnly / setReadOnly / toggleReadOnly
+  // getRequired / setRequired / toggleRequired / triggerValueChange actions
+  // value / readOnly / required state 与 valueChange event
+  // 均由 DATA_FIELD trait 自动注入，默认不需重复声明；如需特化可显式覆盖
+} satisfies ComponentManifest;
+```
+
+---
+
+## 适配第三方组件的 props / events
+
+`DATA_FIELD` trait 默认按 CDP 约定注入：
+
+- `value` prop + `onChange(nextValue)` 回写。
+- `readOnly` / `required` / `name` / `label` props。
+- `valueChange` 事件（由 `onChange` / `setValue` 自动触发）。
+
+接入第三方组件库时，prop / 事件名 / payload 形状常常不一致（`selectedValue` / `onSelectedValueChange`、`disabled` 替 `readOnly`、`(event, value) => void` 而非 `(value) => void`）。**按层选工具**——事件层与 prop 改名首选 adapter，值变换 / 默认值 / 受控转换 / 结构层走 wrapper。完整决策见 [使用 Adapter 适配组件 API · wrapper vs adapter 决策框架](./使用Adapter适配组件API.md#wrapper-vs-adapter-决策框架)。
+
+### 事件层 — 用 adapter（推荐）
+
+`valueChange` 由 `DATA_FIELD` trait 自动声明，**不需要重复声明**，直接在 `adapter.events` 中映射 propName 与 payload：
+
+```ts
+adapter: {
   events: {
-    valueChange: { title: '值变化' },
+    // 第三方回调签名 (event, value) => void，CDP valueChange payload 是 { value }
+    valueChange: {
+      propName: 'onSelectedValueChange',
+      transform: (event, value) => ({ value }),
+    },
   },
-} satisfies ComponentManifest;
+},
+```
+
+`transform` 的返回类型受 `EngineEventProtocol['valueChange']` 约束，类型化对齐 CDP 协议；不需要在 wrapper 里再构造一份 payload。
+
+### Props 层 — 改名用 adapter，值变换用 wrapper
+
+仅改名（`value` → `selectedValue`、`readOnly` → `disabled`）：
+
+```ts
+adapter: {
+  propMapping: {
+    value: 'selectedValue',
+    readOnly: 'disabled',
+  },
+},
+```
+
+需要值变换 / 默认值 / 受控-非受控调谐时，回到 wrapper：
+
+```tsx
+import { forwardRef } from 'react';
+import { ThirdPartySelect } from 'some-ui-lib';
+import type { BaseUIProps } from 'cdp-material-sdk/portable';
+
+export interface AcmeSelectProps extends BaseUIProps<HTMLDivElement> {
+  value?: string;
+  onChange?: (value: string) => void;
+  readOnly?: boolean;
+}
+
+export const AcmeSelect = forwardRef<HTMLDivElement, AcmeSelectProps>((props, ref) => {
+  const { value = '', onChange, readOnly, slotProps } = props;
+  return (
+    <ThirdPartySelect
+      {...slotProps?.root}
+      ref={ref}
+      // 第三方组件不接受 undefined value，wrapper 补默认值
+      selectedValue={value}
+      onSelectedValueChange={onChange}
+      disabled={readOnly}
+    />
+  );
+});
 ```
 
+### 混合策略
+
+事件层用 adapter、props 值层用 wrapper 是常见组合。**同一适配点不要在两层都做**——`adapter.events.transform` 与 wrapper 内 `(value) => onChange(reshape(value))` 二选一，否则会叠加或冲突。
+
+完整规则、自检和常见错误见 [使用 Adapter 适配组件 API](./使用Adapter适配组件API.md)。
+
 ---
 
 ## 声明后会得到什么
 
+声明 `DATA_FIELD` 后，引擎会自动注入下列能力（完整字段列表见 [Traits能力模型 · DATA_FIELD](../reference/Traits能力模型.md#data_field)）：
+
 | 能力 | 说明 |
 |------|------|
-| 值注入 | 宿主向组件注入当前 `value` |
-| 值回写 | 组件调用 `onChange` 后，宿主更新值 |
+| 值注入与回写 | 宿主注入 `value`、`readOnly`、`required`、`name`、`label`、`labelStrategy`；`onChange` 回写值 |
+| 标准 actions | `getValue` / `setValue` / `getReadOnly` / `setReadOnly` / `toggleReadOnly` / `getRequired` / `setRequired` / `toggleRequired` / `triggerValueChange` |
+| 标准 state | `value`（schema 由 `valueSchema` 透传）、`readOnly`、`required` |
+| 标准 event | `valueChange` |
+| valueSchema 特化 | `setValue.params.value`、`setValue.returns.{newValue,oldValue}`、`getValue.returns`、`state.value.schema` 自动按 `meta.valueSchema` 特化 |
 | 类型识别 | 设计器、表达式和 AI 工具可读取 `meta.valueSchema` |
-| 容器协同 | 在数据容器内，字段可按 `name` 写入容器 value |
-| 自动状态补充 | 宿主可基于数据能力补充标准 value 状态 |
+| 容器协同 | 在数据容器内，字段按 `name` 写入容器 value |
 
 ---
 
@@ -119,8 +213,9 @@ export const acmeInputManifest = {
 
 - [ ] `traits` 包含 `COMPONENT_TRAIT.DATA_FIELD`。
 - [ ] `meta.valueSchema` 描述了 value 类型。
-- [ ] 组件接收 `value`。
-- [ ] 值变化时调用 `onChange(nextValue)`。
+- [ ] 组件接收 `value`，值变化时调用 `onChange(nextValue)`。
+- [ ] 组件按需接收并应用 `readOnly` / `required` / `name` / `label` / `labelStrategy`（不必全部支持，但接收的 prop 必须真正生效）。
+- [ ] manifest 中没有不必要地重复声明 DATA_FIELD 自动注入的 props / actions / state / events；确有覆盖的，能明确说出特化原因。
 - [ ] `validateManifest()` 没有 error。
 
 ---
@@ -135,6 +230,14 @@ export const acmeInputManifest = {
 
 如果第三方组件使用 `selectedValue`、`onSelectedValueChange` 等命名，需要在 wrapper 内转换，或阅读 [使用 Adapter 适配组件 API](./使用Adapter适配组件API.md)。
 
+### 不必要地重复声明自动注入字段
+
+在自己的 manifest 里再写一遍 `value` prop、`getValue` / `setValue` action、`valueChange` event 等，会**覆盖**引擎注入的版本，并**丢失 `valueSchema` 自动特化**。默认只写**业务专属**的 props（如 `placeholder`）和事件；仅在**确有特化需求**时才显式覆盖自动注入的字段，并在代码/PR 中说明原因。
+
+### 接收了 `readOnly` / `required` 却没有真正生效
+
+引擎会注入 `readOnly` / `required` 并在 state 中持续更新；如果组件渲染时忽略这两个 prop，事件编排里 `setReadOnly` / `toggleRequired` 等 action 看起来生效（state 变了）但 UI 不变，会让使用者困惑。要么接收并应用，要么不接收（说明组件不支持该语义）。
+
 ---
 
 ## 关联文档

package/docs/component-development/recipes//345/243/260/346/230/216/346/225/260/346/215/256/345/256/271/345/231/250/347/273/204/344/273/266.md

@@ -35,6 +35,7 @@ related:
 2. 在 `meta.valueSchema` 中描述容器 value 结构。
 3. 在子组件渲染区域用 `DataScope` 建立数据作用域，由它负责字段路径解析与记录注入。
 4. 如需读写容器数据，使用 `cdp-material-sdk/host-react` 中的 `useDataContainer` / `useDataContainerApi`。
+5. 如需聚合子字段状态（hidden / readOnly / required / label），使用 `cdp-material-sdk/host-react` 的 `useFieldRegistry`，把它返回的 `registerField` / `unregisterField` 透传给 `DataScope`。
 
 `DataScope` 由 SDK 统一提供，作者不需要传 `componentId`，引擎会自动完成运行时上下文装配。
 
@@ -97,8 +98,11 @@ export const acmeFormManifest = {
 
 ```tsx
 import { useCallback } from 'react';
-import { DataScope, useDataContainerApi } from 'cdp-material-sdk/host-react';
-import { useFieldRegistry } from './useFieldRegistry';
+import {
+  DataScope,
+  useDataContainerApi,
+  useFieldRegistry,
+} from 'cdp-material-sdk/host-react';
 
 export function AcmeForm({ children }) {
   const { getContainerData } = useDataContainerApi<Record<string, unknown>>();
@@ -109,7 +113,8 @@ export function AcmeForm({ children }) {
     [getContainerData],
   );
 
-  // useFieldRegistry 内部用 ref 维护字段表，register/unregister 引用稳定
+  // useFieldRegistry 内部用 ref 维护字段表，register/unregister 引用稳定，
+  // 还可通过 getAllFieldStates() 拿到当前所有字段状态用于整体校验。
   const { registerField, unregisterField } = useFieldRegistry();
 
   return (
@@ -127,7 +132,8 @@ export function AcmeForm({ children }) {
 要点：
 
 - `getRecord` 推荐用 `useCallback` 包，避免每次 render 给 `DataScope` 传新函数引用。
-- `registerField` / `unregisterField` 需保证引用稳定，避免子字段重复注册。
+- `registerField` / `unregisterField` 需保证引用稳定，避免子字段重复注册——直接用 SDK 的 `useFieldRegistry()` 即可，它内部用 ref + `useCallback` 已经保证稳定。
+- 需要在容器内做整体校验（如 Form 提交前检查所有必填字段）时，调 `getAllFieldStates()` 拿到字段状态快照即可。
 - 不需要也不要传 `componentId`。
 
 ### 示例：Table 这类数组型容器

package/docs/component-development/recipes//351/205/215/347/275/256Loading/347/255/226/347/225/245.md

@@ -147,6 +147,102 @@ actions: {
 
 ---
 
+## 自实现 loading 的 hook
+
+`none` 策略下组件得自己维护 loading state。SDK 在 `cdp-material-sdk/portable` 提供两个**纯 React、无宿主耦合**的便利 hook，避免每家组件重复实现引用计数与 dual-loading 合并逻辑。
+
+### useConcurrentLoading：并发动作 loading
+
+适合按钮上同时挂多个异步动作、或同一组件可能并发触发多次请求的场景。返回的 `startLoading` / `stopLoading` 是**引用计数式**的——后到的 stop 不会误清先到的 start。
+
+```tsx
+import { useConcurrentLoading } from 'cdp-material-sdk/portable';
+
+export function AcmePanel() {
+  const { isLoading, loadingText, startLoading, stopLoading } = useConcurrentLoading();
+
+  const handleSave = async () => {
+    startLoading('保存中…');
+    try {
+      await saveToServer();
+    } finally {
+      stopLoading();
+    }
+  };
+
+  return (
+    <button disabled={isLoading} onClick={handleSave}>
+      {isLoading ? loadingText ?? '处理中…' : '保存'}
+    </button>
+  );
+}
+```
+
+返回值要点：
+
+- `isLoading` 是触发重渲染的状态值，可直接驱动 UI。
+- `getLoading()` 是 ref 读取，适合放进 `useCallback`、事件处理器中按需读取，无需进依赖列表。
+- `loadingText` 由最近一次 `startLoading(text)` 设置；不传 `text` 则保持上次值。
+
+### useDualLoading：动作 loading 与数据 loading 分离
+
+适合 Table、查询面板这类**同时存在「按钮触发的动作」与「后台数据请求」**的组件。两类 loading 单独建模，但对外仍暴露统一的 `isLoading`。
+
+```tsx
+import { useEffect } from 'react';
+import { useDualLoading } from 'cdp-material-sdk/portable';
+
+export function AcmeTable({ query }) {
+  const {
+    actionLoading,         // 动作触发的 loading（引用计数）
+    startActionLoading,
+    stopActionLoading,
+    dataLoading,           // 数据请求 loading（布尔）
+    setDataLoading,
+    isLoading,             // 二者的 OR
+    isLoadingRef,          // 引用稳定的最新值
+  } = useDualLoading();
+
+  // 数据请求：标记 dataLoading
+  useEffect(() => {
+    let cancelled = false;
+    setDataLoading(true);
+    fetchRows(query).finally(() => {
+      if (!cancelled) setDataLoading(false);
+    });
+    return () => { cancelled = true; };
+  }, [query, setDataLoading]);
+
+  // 行内动作：标记 actionLoading
+  const handleRowDelete = async (id: string) => {
+    startActionLoading('删除中…');
+    try {
+      await deleteRow(id);
+    } finally {
+      stopActionLoading();
+    }
+  };
+
+  return <TableUi loading={isLoading} onDelete={handleRowDelete} />;
+}
+```
+
+要点：
+
+- 用 `dataLoading` 表达「后台拉数据」，用 `actionLoading` 表达「用户动作触发的并发任务」，二者互不污染。
+- 对外通过 `isLoading` 对接 UI 即可，不必在外层组合两个布尔。
+- `isLoadingRef.current` 提供引用稳定的最新值，方便在事件回调里判断「当前是否仍处于 loading」而不必把状态加进依赖列表。
+
+### 与 manifest loading 策略的搭配
+
+| 场景 | manifest 策略 | hook |
+|------|---------------|------|
+| 完全交给宿主 | `native` 或 `wrapper` | 不需要 |
+| 宿主只接管视觉、组件内部仍想细分 loading | `wrapper` + 这两个 hook | `useConcurrentLoading` 或 `useDualLoading`，组件内部用 hook 状态驱动局部 UI，宿主负责整体遮罩 |
+| 完全自管 | `none` + 自定义 `setLoading` / `getLoading` actions | 推荐 `useConcurrentLoading`；用 hook 的 `getLoading` 实现 action 的 `getLoading`，用 `startLoading` / `stopLoading` 实现 action 的 `setLoading` |
+
+---
+
 ## 选择表
 
 | 组件情况 | 推荐策略 |

package/docs/component-development/reference/Manifest/345/255/227/346/256/265/345/217/202/350/200/203.md

@@ -22,7 +22,7 @@ related:
 | `alias` | `string[]` | 否 | 历史别名或兼容名 |
 | `meta` | `object` | 是 | 基本信息 |
 | `traits` | `ComponentTrait[]` | 否 | 能力声明 |
-| `props` | `ObjectSchema` | 否 | 可配置 props 的 JSON Schema |
+| `props` | `ObjectSchema` | 否 | 可配置 props 的 JSON Schema，详见 [声明 props](../recipes/声明props.md) |
 | `events` | `EventSpec[]` | 否 | 标准事件声明 |
 | `customEvents` | `Record<string, CustomEventSpec>` | 否 | 自定义事件声明 |
 | `actions` | `Record<string, ActionSpec>` | 否 | 组件动作声明 |
@@ -245,6 +245,7 @@ export const manifest = {
 本文档只保留本层级职责内容：Recipe 提供任务步骤，Reference 提供稳定模型和规则，validateManifest 文档提供校验级别事实源。
 
 - 关联文档：[03-开发最小可运行组件](../getting-started/03-开发最小可运行组件.md)
+- 任务 Recipe：[声明 props](../recipes/声明props.md)
 - 任务 Recipe：[声明布局容器组件](../recipes/声明布局容器组件.md)
 - 任务 Recipe：[配置设计器元信息](../recipes/配置设计器元信息.md)
 - 校验规则：[validateManifest校验规则](./validateManifest校验规则.md)

package/docs/component-development/reference/SDK/345/257/274/345/205/245/350/276/271/347/225/214.md

@@ -31,6 +31,7 @@ related:
 - `validateManifest()`
 - `diagnoseMissingActionImpls()`
 - `diagnoseMissingStateKeys()`
+- `useConcurrentLoading` / `useDualLoading`（组件自实现 loading 时的开箱即用 hook）
 
 示例：
 
@@ -53,10 +54,10 @@ import {
 
 可用于：
 
-- `DataScope`
-- `useDataContainer`
-- `useDataContainerApi`
-- `PageContext`
+- `DataScope` / `DataScopeContext` / 类型 `FieldState` / `LazyScope` / `PathResolver`
+- `useDataContainer` / `useDataContainerApi`
+- `useFieldRegistry`（与 `DataScope` 配套，给数据容器组件聚合子字段状态）
+- `PageContext` / `DataContainerRuntimeContext`
 
 如果不能确认共享 runtime，请不要使用该入口。