arkui-api-design

ArkUI API 设计技能

此技能为设计、审核和维护符合 OpenHarmony 应用 TypeScript/JavaScript 编码规范的 ArkUI 组件 API 提供全面指导。

核心设计原则

1. 遵循 OpenHarmony 编码规范

所有 API 定义和代码示例都必须符合 OpenHarmony 应用 TypeScript/JavaScript 编码指南。主要规范包括：

• 命名约定：属性和方法使用 camelCase，类型和接口使用 PascalCase
• 类型安全：为所有参数提供恰当的 TypeScript 类型定义
• 代码风格：使用 4 个空格缩进，保持格式一致
• 文档：为所有公共 API 编写完整的 JSDOC 注释

详细规范请参阅：references/OpenHarmony-Application-Typescript-JavaScript-coding-guide.md

2. 同步静态和动态接口

重要：添加或修改组件属性时，必须同时更新静态和动态接口文件：

静态 API（.static.d.ets）

• 位置：OpenHarmony/interface/sdk-js/api/arkui/component/<component>.static.d.ets
• 用途：供 ArkTS 静态类型系统使用的声明式 UI API
• 用法：在 @Builder 函数中声明组件
• JSDOC 标签：在 @since [version] 后添加 @static（例如：@since 26 static）
• 示例：

// File: text.static.d.ets
/**
 * Provides a text component.
 *
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 7 static
 */
declare class Text {
  /**
   * Text content.
   *
   * @type { string | Resource }
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7 static
   * @stagemodelonly
   */
  content: string | Resource;

  /**
   * Creates a text component.
   *
   * @param content - Text content.
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7 static
   * @stagemodelonly
   */
  constructor(content: string | Resource);
}

动态 API（.d.ts Attribute 接口）

• 位置：OpenHarmony/interface/sdk-js/api/@internal/component/ets/<component>.d.ts
• 用途：用于命令式属性设置的修饰器 API
• 用法：链式修改属性
• JSDOC 标签：在 @since [version] 后添加 dynamic（例如：@since 26 dynamic）
• 示例：

// File: text.d.ts (in @internal/component/ets/)
/**
 * Text Attribute interface.
 *
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 7 dynamic
 */
declare class TextAttribute extends CommonMethod<TextAttribute> {
  /**
   * Sets the text content.
   *
   * @param value - Text content to display.
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7 dynamic
   * @stagemodelonly
   */
  content(value: string | Resource): TextAttribute;
}

注意：arkui/ 目录中的 *Modifier.d.ts 文件仅定义 Modifier 类（用于 AttributeModifier 模式），不定义 Attribute 接口本身。

同步规则

场景	静态 API	动态 API
添加属性	添加到类/接口	添加到 Attribute 类
弃用属性	标记为 @deprecated	标记为 @deprecated
更改签名	更新类定义	更新 Attribute 方法
文件位置	arkui/component/*.static.d.ets	@internal/component/ets/*.d.ts
版本标签	@since X static	@since X dynamic
返回类型	链式调用使用 this	使用具体的 Attribute 类型

3. 为可配置属性支持 Resource 类型

重要：并非所有属性都需要支持 Resource 类型。只有当属性需要通过资源文件配置（主题、i18n 等）时，才添加 Resource 类型。

需要支持 Resource 类型的情况：

• ✅ 需要：颜色、字体、尺寸、字符串、图像——开发者可能通过资源文件配置主题或国际化的内容
• ❌ 不需要：状态标记、模式选择器、事件回调——这些仅用于运行时配置

类型简化规则： 重要：ResourceStr 仅用于新 API（API 13+）。请勿使用 ResourceStr 修改现有 API（API 12 及更早版本）。

使用 ResourceStr 的情况：

• ✅ 需要：新属性/方法（在 API 13 或更高版本中引入）
• ❌ 不需要：现有属性/方法（API 12 及更早版本）

// ❌ WRONG: Using ResourceStr for API 12 (existing property)
content(value: ResourceStr): TextAttribute  // API 12 - DO NOT MODIFY

// ✅ CORRECT: Using string | Resource for API 12 (maintaining backward compatibility)
content(value: string | Resource): TextAttribute  // API 12 - KEEP AS IS

// ✅ CORRECT: Using ResourceStr for NEW API 13 (new property)
fontSize(value: number | string | Length | ResourceStr): TextAttribute  // API 13 - NEW PROPERTY

// Benefits:
// - Maintains backward compatibility for existing APIs
// - Allows simplification for new APIs
// - Clear version boundary at API 13

应该支持 Resource 的属性示例：

// Theme-related - YES, support Resource (API 12: keep original type)
fontSize(value: number | string | Length | Resource): TextAttribute
// API 12 and earlier: Maintain string | Resource for compatibility

// Theme-related - YES, support Resource (API 13+: use ResourceStr)
fontSize(value: number | string | Length | ResourceStr): TextAttribute
// API 13 and later: Simplified type

// Usage examples (API 12 - old API, keep string | Resource):
Text().fontSize(16)                              // number
Text().fontSize('16vp')                          // string
Text().fontSize($r('app.float.font_size_large')) // Resource

// Usage examples (API 13+ - new API, use ResourceStr):
Text().fontSize(16)                               // number
Text().fontSize('16vp')                          // string
Text().fontSize($r('app.float.font_size_large')) // Resource (ResourceStr covers this too)

不应该支持 Resource 的属性示例：

// State flags - NO, these are runtime-only
stateEffect(value: boolean): ButtonAttribute
enabled(value: boolean): CommonMethod

// Event callbacks - NO, these are runtime-only
onClick(callback: () => void): CommonMethod

支持 ResourceStr 的优势（仅适用于新 API）：

• 支持通过资源文件集中管理主题
• 支持使用特定于地区设置的资源进行国际化
• 无需更改代码即可动态切换主题
• 类型简化：使用 ResourceStr 替代 string | Resource
• 向后兼容：保留 API 12 及更早版本的现有 API 签名

4. 明确说明 undefined/null 的处理行为

JSDOC 注释必须明确说明如何处理 undefined 和 null 值：

/**
 * Sets font size of text.
 * @param value Font size value. If undefined, restores to default size (16fp).
 *              If null, removes the font size setting and uses inherited value.
 * @throws {Error} Throws error if value is negative.
 * @since 10
 */
fontSize(value: number | string | Length | Resource | undefined | null): TextAttribute;

常见模式：

• undefined → 恢复默认值
• null → 移除设置，使用继承值
• 无效值 → 抛出带有清晰说明的错误

5. 使用 vp 作为默认长度单位

长度测量始终使用 vp（虚拟像素）作为默认单位：

// Good: Default to vp
width(value: number | string): ButtonAttribute  // 100 means 100vp

// Good: Explicit vp
width(value: Length): ButtonAttribute  // Length.type defaults to vp

// Avoid: Require px without good reason
width(value: number): ButtonAttribute  // 100px - avoid unless necessary

6. 在 JSDOC 中说明约束

JSDOC 注释必须包含规格限制和约束：

/**
 * Sets border radius of component.
 * @param value Border radius value. Valid range: 0-1000vp.
 *              Values exceeding 1000vp will be clamped to 1000vp.
 *              Negative values are treated as 0.
 * @unit vp
 * @since 10
 */
borderRadius(value: number | string | Length): CommonMethod;

必需的文档内容：

• 有效范围（最小值/最大值）
• 特殊值处理方式（负数、零等）
• 测量单位
• 限幅行为（如适用）

7. 考虑对组件的跨组件影响

添加通用属性时，评估其对所有组件的影响：

添加通用属性之前：

1. 检查该属性是否适用于大多数组件（布局、样式、事件）
2. 为不同组件类型定义一致的行为
3. 记录组件特有的例外情况（如有）
4. 考虑向后兼容性

通用属性示例：

• 布局：width()、height()、padding()、margin()
• 样式：opacity()、visibility()、borderRadius()
• 事件：onClick()、onTouch()

8. 在 JSDOC 中使用正确术语

重要：“Called when”这一短语只能用于事件回调函数和由框架调用的生命周期方法。不得用于属性设置器、配置方法或属性修饰符。

正确使用 “Called when”

✅ 正确：事件回调和生命周期方法

/**
 * Callback invoked when the paste button is clicked.
 *
 * @param callback - Callback function for the click event.
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 10 dynamic
 */
onClick(callback: Callback<ClickEvent>): PasteButtonAttribute;

/**
 * Callback invoked when the playback progress changes.
 *
 * @param callback - Callback function with playback info.
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 7 dynamic
 */
onProgress(callback: Callback<PlaybackInfo>): VideoAttribute;

/**
 * Callback invoked when scrolling begins each frame.
 *
 * @param callback - Callback function for scroll frame begin event.
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 9 dynamic
 */
onScrollFrameBegin(callback: (offset: number, state: ScrollState) => ScrollOffset): ListAttribute;

/**
 * Callback invoked when the water flow reaches the end.
 *
 * @param callback - Callback function for reach end event.
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 9 dynamic
 */
onReachEnd(callback: () => void): WaterFlowAttribute;

❌ 错误：属性设置器和配置方法

// ❌ WRONG: "Called when" used for property setter
/**
 * Called when the font size is set.
 */
fontSize(value: number | string | Resource): TextAttribute;

// ✅ CORRECT: Use action verbs for property setters
/**
 * Sets the font size for the text component.
 *
 * @param value - Font size in fp. Valid range: 0-1000fp.
 * @unit fp
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 7 dynamic
 */
fontSize(value: number | string | Length | Resource): TextAttribute;

// ❌ WRONG: "Called when" used for configuration method
/**
 * Called when the border color is set.
 */
stroke(value: ResourceColor): ShapeAttribute;

// ✅ CORRECT: Use action verbs for configuration methods
/**
 * Sets the stroke (border) color of the shape.
 *
 * @param value - Stroke color to apply.
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 9 dynamic
 */
stroke(value: ResourceColor): ShapeAttribute;

// ❌ WRONG: "Called when" used for layout property
/**
 * Called when the vertical alignment is set.
 */
alignItems(value: AlignItems): RowAttribute;

// ✅ CORRECT: Use action verbs for layout properties
/**
 * Sets the vertical alignment of child components.
 *
 * @param value - Alignment mode for child components.
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 7 dynamic
 */
alignItems(value: AlignItems): RowAttribute;

JSDOC 措辞决策树

Is this an event callback or lifecycle method?
├─ Yes → Use "Called when" or "Callback invoked when"
│         Examples: onClick, onScroll, onAppear, onDisAppear
│
└─ No → Use action verbs (Sets, Specifies, Configures, Enables/Disables)
         Examples: fontSize(), fontWeight(), padding(), stateEffect()

标准措辞模式

API 类型	正确措辞	示例
属性设置器	“设置 [属性]。”/“指定 [属性]。”	设置字体大小。、指定文本颜色。
配置方法	“配置 [功能]。”/“启用/禁用 [功能]。”	启用状态效果。、配置滚动行为。
事件回调	“在 [事件] 时调用。”/“在 [事件] 时调用回调。”	在点击时调用。、在滚动位置变化时调用。
生命周期方法	“在 [生命周期事件] 时调用。”	在组件出现时调用。、在组件即将消失时调用。

应避免的常见错误

1. “在设置 [属性] 时调用” - 这是最常见的错误模式

   • ❌ 在设置字体粗细时调用。
   • ✅ 设置文本的字体粗细。

2. 对非回调方法使用“在 [操作] 时调用” - 会混淆属性设置器与回调

   • ❌ 在绘制多边形时调用。（用于属性设置器）
   • ✅ 设置多边形的绘图选项。

3. 主动配置使用被动语态 - 设置器方法应使用主动动词

   • ❌ 设置边框颜色时……
   • ✅ 设置组件的边框颜色。

正确修正后的 JSDOC 示例

// Text Properties
/**
 * Sets the font style for the text component.
 *
 * @param value - Font style to apply. Default is FontStyle.Normal.
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 7 dynamic
 */
fontStyle(value: FontStyle): TextAttribute;

/**
 * Sets the font weight (text thickness).
 *
 * @param value - Font weight value. If too large, text may be clipped.
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 7 dynamic
 */
fontWeight(value: number | FontWeight | ResourceStr): TextAttribute;

/**
 * Sets the horizontal text alignment.
 *
 * @param value - Text alignment mode.
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 7 dynamic
 */
textAlign(value: TextAlign): TextAttribute;

// Shape Properties
/**
 * Sets the fill color of the shape.
 *
 * @param value - Fill color to apply.
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 9 dynamic
 */
fill(value: ResourceColor): ShapeAttribute;

/**
 * Sets the stroke (border) width.
 *
 * @param value - Stroke width in vp. Valid range: 0-1000vp.
 * @unit vp
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 9 dynamic
 */
strokeWidth(value: Length): ShapeAttribute;

// Layout Properties
/**
 * Sets the horizontal alignment of child components.
 *
 * @param value - Horizontal alignment mode.
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 7 dynamic
 */
justifyContent(value: MainAxisAlignment): CommonMethod;

/**
 * Sets the vertical alignment of child components.
 *
 * @param value - Vertical alignment mode.
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 7 dynamic
 */
alignItems(value: AlignItems): CommonMethod;

9. 遵守接口目录边界

进行 API 设计和编译验证时，仅处理 interface/ 目录中的文件：

允许修改：

• interface/sdk-js/api/arkui/component/*.static.d.ets - 静态 API 定义
• interface/sdk-js/api/@internal/component/ets/*.d.ts - 动态 API 定义（Attribute 类）
• interface/sdk-js/api/arkui/*Modifier.d.ts - Modifier 类定义（用于 AttributeModifier 模式）
• 类型定义文件（.d.ts、.static.d.ets）

请勿修改：

• ace_engine/ 中的框架实现代码
• 组件模式文件
• 布局或渲染实现

---

API 设计工作流

新组件属性的完整工作流

1. Design API
   ├─ Define property types and constraints
   ├─ Document undefined/null behavior
   └─ Check cross-component impact

2. Create Static API (.static.d.ets)
   ├─ Add property to component class
   ├─ Write complete JSDOC
   └─ Include @since, @syscap tags

3. Create Dynamic API (@internal/component/ets/*.d.ts)
   ├─ Add method to Attribute class
   ├─ Match signature with static API
   └─ Synchronize JSDOC documentation

4. Verify Type Safety
   ├─ Check TypeScript compilation
   ├─ Validate type definitions
   └─ Ensure signature consistency

5. Build SDK
   ├─ Run SDK build command
   └─ Monitor compilation errors

6. Verify SDK Output
   ├─ Check generated API files
   ├─ Verify new APIs are exported
   └─ Test API availability

新增组件 API

1. 设计 API 接口，使用恰当的 TypeScript 类型
2. 创建静态 API（component/*.static.d.ets）
   • 定义带有属性的组件类
   • 添加构造函数和方法
   • 编写完整的 JSDOC 注释
3. 创建动态 API（@internal/component/ets/*.d.ts）
   • 定义 Attribute 类方法
   • 添加所有属性方法
   • 与静态 API 签名保持同步
4. 添加 JSDOC 注释，包括：
   • 参数说明
   • undefined/null 处理方式
   • 值约束和范围
   • 默认值
   • @since 版本
   • @syscap 能力
   • @throws 文档（如适用）
5. 对支持主题的属性，支持 Resource 类型
6. 指定单位（长度默认使用 vp）
7. 如果添加通用属性，验证对其他组件的影响
8. 构建 SDK 以验证编译结果

API 审查

使用以下清单进行验证：

• 静态 API（.static.d.ets）存在且完整
• 动态 API（@internal/component/ets/*.d.ts）存在且已同步
• 静态 API 和动态 API 的参数类型一致
• 版本标签正确（@since X static 与 @since X dynamic）
• 返回类型约定正确（静态 API 使用 this，动态 API 使用具体类型）
• 符合编码标准
• 在适当情况下支持 Resource 类型
• JSDOC 文档完整
• 约束说明完整
• 跨组件一致性
• 包含 @since 和 @syscap 标签

API 弃用

重要：弃用 API 时，必须将静态 API 属性/方法和对应的动态 API 方法都标记为 @deprecated。

1. 将静态 API 和动态 API 都标记为 @deprecated
2. 在 JSDOC 中提供迁移路径
3. 指定移除版本（@obsoleted）
4. 更新文档和示例

同步要求：

• 如果弃用静态 API 中的属性 → 必须在动态 API 中弃用该属性
• 如果弃用静态 API 中的方法 → 必须在动态 API 中弃用该方法
• 两者必须具有匹配的 @deprecated、@obsoleted、@see 和 @migration 标签

---

SDK 构建和验证

构建 SDK

完成 API 设计变更后，构建 SDK 以验证编译结果并生成输出：

# From OpenHarmony root directory
./build.sh --export-para PYCACHE_ENABLE:true --product-name ohos-sdk --ccache

构建参数：

• --export-para PYCACHE_ENABLE:true - 启用 Python 缓存以加快构建
• --product-name ohos-sdk - 构建 SDK 目标
• --ccache - 使用编译器缓存以进行增量构建

构建输出位置：

out/ohos-sdk/
├── interfaces/
│   └── sdk-js/
│       └── api/
│           └── arkui/
│               ├── component/           # Generated .static.d.ets files
│               │   ├── button.static.d.ets
│               │   ├── text.static.d.ets
│               │   └── ...
│               ├── ButtonModifier.d.ts  # Generated .d.ts files
│               ├── TextModifier.d.ts
│               └── ...

验证步骤

SDK 构建成功完成后：

1. 验证静态 API

# Check if .static.d.ets file contains your changes
grep -n "yourNewProperty" out/ohos-sdk/interfaces/sdk-js/api/arkui/component/<yourcomponent>.static.d.ets

2. 验证动态 API

# Check if @internal/component/ets/*.d.ts file contains your changes
grep -n "yourNewMethod" out/ohos-sdk/interfaces/sdk-js/api/@internal/component/ets/<your_component>.d.ts

3. 验证清单

• 构建成功完成且无错误
• 静态 API 文件（.static.d.ets）包含新增/修改的属性
• 动态 API 文件（@internal/component/ets/*.d.ts）包含对应的方法
• JSDOC 注释存在且完整
• 静态 API 和动态 API 的类型签名一致
• 版本标签正确（@since X static 与 @since X dynamic）
• 接口文件中没有编译警告或错误

4. 常见构建问题

问题	症状	解决方案
类型不匹配	构建因类型错误而失败	检查静态 API 和动态 API 的签名是否一致
缺少导入	找不到类型	添加正确的导入语句
JSDOC 错误	文档警告	修正 JSDOC 语法，确保所有标签有效
同步错误	API 只存在于一个文件中	将 API 添加到静态和动态文件中

---

代码示例

示例 1：完整的静态 API + 动态 API

静态 API：button.static.d.ets

/**
 * Provides a button component.
 *
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 7
 */
declare class Button {
  /**
   * Button type.
   *
   * @type { ButtonType }
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7
   */
  type: ButtonType;

  /**
   * Button state.
   *
   * @type { ButtonState }
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7
   */
  stateEffect: boolean;

  /**
   * Creates a button component.
   *
   * @param label - Button label text.
   * @param options - Button options.
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7
   */
  constructor(label: string | Resource, options?: ButtonOptions);
}

动态 API：button.d.ts（位于 @internal/component/ets/ 中）

/**
 * Button Attribute class.
 *
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 7 dynamic
 */
declare class ButtonAttribute extends CommonMethod<ButtonAttribute> {
  /**
   * Sets the button type.
   *
   * @param value - Button type to set.
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7 dynamic
   */
  type(value: ButtonType): ButtonAttribute;

  /**
   * Enables or disables state effect.
   *
   * @param value - Whether to enable state effect. Default is true.
   *              If undefined, enables state effect.
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7 dynamic
   */
  stateEffect(value: boolean): ButtonAttribute;
}

示例 2：添加新属性

为 Button 添加 iconSize

静态 API 更新：

// File: button.static.d.ets
declare class Button {
  // Existing properties...
  /**
   * Icon size.
   *
   * @type { number | string }
   * @unit vp
   * @default 24vp
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 12
   */
  iconSize: number | string;
}

动态 API 更新：

// File: button.d.ts (in @internal/component/ets/)
declare class ButtonAttribute extends CommonMethod<ButtonAttribute> {
  // Existing methods...

  /**
   * Sets the icon size.
   *
   * @param value - Icon size in vp. Valid range: 0-100vp.
   *              If undefined, restores to default size (24vp).
   * @unit vp
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 12 dynamic
   */
  iconSize(value: number | string | Length | undefined): ButtonAttribute;
}

示例 3：API 弃用

弃用 setFontSize，改用 fontSize

静态 API：

declare class Text {
  /**
   * Font size.
   *
   * @type { number | string | Resource }
   * @unit fp
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7
   */
  fontSize: number | string | Resource;

  /**
   * Sets the font size.
   *
   * @param value - Font size value.
   * @deprecated since 10. Use fontSize property instead.
   * @see fontSize
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7
   * @obsoleted 10
   */
  setFontSize(value: number | string | Resource): void;
}

动态 API：

// File: text.d.ts (in @internal/component/ets/)
declare class TextAttribute extends CommonMethod<TextAttribute> {
  /**
   * Sets the font size.
   *
   * @param value - Font size in fp. Valid range: 0-1000fp.
   * @unit fp
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 10 dynamic
   */
  fontSize(value: number | string | Length | Resource | undefined | null): TextAttribute;

  /**
   * Sets the font size (deprecated method).
   *
   * @param value - Font size value.
   * @deprecated since 10. Use fontSize() instead.
   * @see fontSize
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7 dynamic
   * @obsoleted 10
   */
  setFontSize(value: number | string | Resource): TextAttribute;
}

---

常见陷阱

静态/动态 API 未同步

// ❌ Bad: Only static API defined
// File: text.static.d.ets
declare class Text {
  content: string | Resource;
}

// Missing: @internal/component/ets/text.d.ts has no content() method

// ✅ Good: Both APIs synchronized
// File: text.static.d.ets
declare class Text {
  content: string | Resource;
}

// File: text.d.ts (in @internal/component/ets/)
declare class TextAttribute extends CommonMethod<TextAttribute> {
  content(value: string | Resource): TextAttribute;
}

签名不一致

// ❌ Bad: Signatures don't match
// Static: .static.d.ets
iconSize: number;

// Dynamic: @internal/component/ets/*.d.ts
iconSize(value: number | string | Resource): ButtonAttribute; // Different types!

// ✅ Good: Consistent types
// Static: .static.d.ets
iconSize: number | string;

// Dynamic: @internal/component/ets/*.d.ts
iconSize(value: number | string): ButtonAttribute; // Matches

JSDOC 不完整

// ❌ Bad: Missing null/undefined handling, constraints
/**
 * Sets the width.
 */
width(value: number): CommonMethod;

// ✅ Good: Complete documentation
/**
 * Sets the component width.
 * @param value Width value in vp. Valid range: 0-10000vp.
 *              If undefined, restores default width.
 * @unit vp
 * @since 8
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 */
width(value: number | string | Length | undefined): CommonMethod;

忘记资源类型

// ⚠️ Less optimal: Only accepts number/string
fontSize(value: number | string): TextAttribute;

// ✅ Better: Supports resource theming
fontSize(value: number | string | Length | Resource): TextAttribute;

---

更多资源

编码规范

• references/OpenHarmony-Application-Typescript-JavaScript-coding-guide.md
  • OpenHarmony TypeScript/JavaScript 编码指南（官方完整版）
  • 包含命名约定、类型定义、代码格式和所有编码规范
  • 本技能中的所有设计原则均基于此文档

示例代码

• examples/interface-definition.ts - 完整的接口定义示例
• examples/modifier-implementation.ts - 修饰符方法实现示例
• examples/deprecation-pattern.ts - API 弃用与迁移示例
• examples/static-dynamic-sync.ts - 静态/动态 API 同步示例

知识库参考

• docs/sdk/Component_API_Knowledge_Base_CN.md - ArkUI 组件 API 知识库

  • 说明静态 API 与动态 API 的区别
  • 文件结构和组织方式
  • 组件 API 分类

• docs/sdk/ArkUI_SDK_API_Knowledge_Base.md - ArkUI SDK API 结构化分析文档

  • SDK API 与 ace_engine 实现的映射关系
  • 静态 API 与动态 API 对比
  • FrameNode/BuilderNode/Modifier 模式

---

快速参考

必要的 JSDOC 标签

/**
 * Brief description.
 * @param paramName Description including undefined/null behavior and constraints.
 * @unit vp | fp | px (for length values)
 * @throws {ErrorType} Description (when errors can occur)
 * @since version static (for Static API - use "static" after version)
 * @since version dynamic (for Dynamic API - use "dynamic" after version)
 * @syscap SystemCapability.ArkUI.ArkUI.Full (system capability)
 * @stagemodelonly (indicates this is a stage model only API)
 * @deprecated Use alternativeMethod() instead (for deprecated APIs)
 * @obsoleted version (when API was removed)
 */

重要标签规则：

• 静态 API（.static.d.ets）：使用 @since X static 格式（例如，@since 26 static）
• 动态 API（*Modifier.d.ts）：使用 @since X dynamic 格式（例如，@since 26 dynamic）
• 所有 API：添加 @stagemodelonly 标签，以表明仅适用于 Stage 模型

类型支持决策树

Does the parameter accept length values?
├─ Yes → Add Length and Resource types
└─ No → Is it theme-able (color, size, string)?
    ├─ Yes → Add Resource type
    └─ No → Use basic types (number | string | undefined | null)

默认值文档说明

// Document defaults in JSDOC:
"If undefined, restores to default [value] ([unit])."
"If null, removes setting and uses inherited value."

静态 API 与动态 API 快速参考

方面	静态 API（.static.d.ets）	动态 API（*.d.ts）
文件位置	arkui/component/	@internal/component/ets/
用法	Text({ content: 'Hello' })	Text().content('Hello')
类型	类声明	继承 CommonMethod 的类
模式	基于构造函数	方法链式调用
返回类型	不适用（属性）	具体的 Attribute 类型
版本标签	@since X static	@since X dynamic
两者都必须提供	✅ 是	✅ 是

静态/动态 API 同步检查清单

定稿任何 API 前，请确认：

已更新的文件

• 静态文件：interface/sdk-js/api/arkui/component/*.static.d.ets
• 动态文件：interface/sdk-js/api/@internal/component/ets/*.d.ts

签名一致

• 参数类型相同
• 可选参数一致
• 泛型类型一致

JSDOC 完整

• @param 描述一致
• @returns 描述一致（仅动态 API）
• 版本标签：@since XX static 与 @since XX dynamic
• @syscap 标签相同
• @unit 标签一致

返回类型约定

• 静态 API：属性（属性不标注返回类型）
• 动态 API：具体类型（例如，ButtonAttribute）

版本标签

• 静态 API：@since 26 static
• 动态 API：@since 26 dynamic

已验证编译

• 静态文件编译通过
• 动态文件编译通过
• 无类型错误
• 无 JSDOC 警告

---

应避免的常见错误

1. 只更新一个文件

❌ 错误：只更新静态文件

// Static: richEditor.static.d.ets
default lineSpacing(value: LengthMetrics | undefined): this;

// Dynamic: rich_editor.d.ts
// Method is missing! ✗

✅ 正确：两个文件都更新

// Static: richEditor.static.d.ets
default lineSpacing(value: LengthMetrics | undefined, options?: LineSpacingOptions): this;

// Dynamic: rich_editor.d.ts
lineSpacing(value: LengthMetrics | undefined, options?: LineSpacingOptions): RichEditorAttribute;

2. 参数类型不一致

❌ 错误：参数类型不同

// Static:
default lineSpacing(value: LengthMetrics): this;

// Dynamic:
lineSpacing(value: LengthMetrics | undefined): RichEditorAttribute;
// ✗ Parameter types don't match!

✅ 正确：参数类型相同

// Static:
default lineSpacing(value: LengthMetrics | undefined, options?: LineSpacingOptions): this;

// Dynamic:
lineSpacing(value: LengthMetrics | undefined, options?: LineSpacingOptions): RichEditorAttribute;
// ✓ Parameters match perfectly

3. 缺少版本标签

❌ 错误：通用版本标签

// Static: @since 26
// Dynamic: @since 26
// ✗ Missing static/dynamic specification

✅ 正确：使用正确的版本标签

// Static: @since 26 static
// Dynamic: @since 26 dynamic
// ✓ Clear distinction

4. 文件位置错误

❌ 错误：在错误的位置查找动态 API

// Looking in: arkui/ButtonModifier.d.ts
// This file only defines Modifier class, not Attribute interface!

✅ 正确：文件位置正确

// Dynamic API is in: @internal/component/ets/button.d.ts
// This file defines ButtonAttribute class with all methods