Back to Details

arkui-api-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ArkUI API Design Skill

ArkUI API设计技能

This skill provides comprehensive guidance for designing, reviewing, and maintaining ArkUI component APIs that follow OpenHarmony Application TypeScript/JavaScript coding guidelines.
本技能为遵循OpenHarmony应用TypeScript/JavaScript编码规范的ArkUI组件API设计、审核与维护提供全面指导。

Core Design Principles

核心设计原则

1. Follow OpenHarmony Coding Standards

1. 遵循OpenHarmony编码标准

All API definitions and code examples must comply with the OpenHarmony Application TypeScript/JavaScript Coding Guide. Key standards include:
  • Naming conventions: Use camelCase for properties and methods, PascalCase for types/interfaces
  • Type safety: Provide proper TypeScript type definitions for all parameters
  • Code style: Follow 4-space indentation, consistent formatting
  • Documentation: Comprehensive JSDOC comments for all public APIs
For detailed standards, refer to: 
references/OpenHarmony-Application-Typescript-JavaScript-coding-guide.md
所有API定义和代码示例必须符合《OpenHarmony应用TypeScript/JavaScript编码指南》。核心标准包括：
  • 命名规范：属性和方法使用小驼峰（camelCase），类型/接口使用大驼峰（PascalCase）
  • 类型安全：为所有参数提供正确的TypeScript类型定义
  • 代码风格：遵循4空格缩进，保持格式一致
  • 文档要求：所有公开API需配备完整的JSDOC注释
详细规范请参考：
references/OpenHarmony-Application-Typescript-JavaScript-coding-guide.md

2. Synchronize Static and Dynamic Interfaces

2. 同步静态与动态接口

CRITICAL: When adding or modifying component properties, you must update both static and dynamic interface files:
关键要求：添加或修改组件属性时，必须同时更新静态和动态两种接口文件：

Static API (
.static.d.ets
)

静态API（
.static.d.ets
）

  • Location: 
    OpenHarmony/interface/sdk-js/api/arkui/component/<component>.static.d.ets
  • Purpose: Declarative UI API for ArkTS static type system
  • Usage: Component declaration in 
    @Builder
    functions
  • JSDOC Tags: Add 
    @static
    after 
    @since [version]
    (e.g., 
    @since 26 static
    )
  • Example:
typescript
// 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);
}
  • 存放路径：
    OpenHarmony/interface/sdk-js/api/arkui/component/<component>.static.d.ets
  • 用途：为ArkTS静态类型系统提供声明式UI API
  • 使用场景：
    @Builder
    函数中的组件声明
  • JSDOC标签：在
    @since [版本]
    后添加
    @static
    （例如：
    @since 26 static
    ）
  • 示例：
typescript
// File: text.static.d.ets
/**
 * 提供文本组件。
 *
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 7 static
 */
declare class Text {
  /**
   * 文本内容。
   *
   * @type { string | Resource }
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7 static
   * @stagemodelonly
   */
  content: string | Resource;

  /**
   * 创建文本组件。
   *
   * @param content - 文本内容。
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7 static
   * @stagemodelonly
   */
  constructor(content: string | Resource);
}

Dynamic API (
.d.ts
Attribute Interface)

动态API（
.d.ts
属性接口）

  • Location: 
    OpenHarmony/interface/sdk-js/api/@internal/component/ets/<component>.d.ts
  • Purpose: Imperative modifier API for command-style property setting
  • Usage: Chained property modification
  • JSDOC Tags: Add 
    dynamic
    after 
    @since [version]
    (e.g., 
    @since 26 dynamic
    )
  • Example:
typescript
// 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;
}
Note: The 
*Modifier.d.ts
files in 
arkui/
directory only define the Modifier class (for 
AttributeModifier
pattern), not the Attribute interface itself.
  • 存放路径：
    OpenHarmony/interface/sdk-js/api/@internal/component/ets/<component>.d.ts
  • 用途：为命令式属性设置提供链式调用的Modifier API
  • 使用场景：链式修改组件属性
  • JSDOC标签：在
    @since [版本]
    后添加
    dynamic
    （例如：
    @since 26 dynamic
    ）
  • 示例：
typescript
// File: text.d.ts (in @internal/component/ets/)
/**
 * 文本属性接口。
 *
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 7 dynamic
 */
declare class TextAttribute extends CommonMethod<TextAttribute> {
  /**
   * 设置文本内容。
   *
   * @param value - 要显示的文本内容。
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7 dynamic
   * @stagemodelonly
   */
  content(value: string | Resource): TextAttribute;
}
注意：
arkui/
目录下的
*Modifier.d.ts
文件仅定义Modifier类（用于AttributeModifier模式），而非属性接口本身。

Synchronization Rules

同步规则

ScenarioStatic APIDynamic API
Add propertyAdd to class/interfaceAdd to Attribute class
Deprecate propertyMark as 
@deprecated
Mark as 
@deprecated
Change signatureUpdate class definitionUpdate Attribute method
File location
arkui/component/*.static.d.ets
@internal/component/ets/*.d.ts
Version tag
@since X static
@since X dynamic
Return typeUse 
this
for chainable		Use concrete Attribute type
场景静态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. Support Resource Type for Configurable Properties

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

IMPORTANT: Not all properties need Resource type support. Only add Resource type when the property is intended to be configured through resource files (theming, i18n, etc.).
When to support Resource type:
  • ✅ YES: Colors, fonts, sizes, strings, images - anything developers might configure through resource files for theming or internationalization
  • ❌ NO: State flags, mode selectors, event callbacks - these are runtime-only configurations
Type Simplification Rule: CRITICAL: Only use 
ResourceStr
for NEW APIs (API 13+). Do NOT use 
ResourceStr
to modify existing APIs (API 12 and earlier).
When to use ResourceStr:
  • ✅ YES: For NEW properties/methods (introduced in API 13 or later)
  • ❌ NO: For existing properties/methods (API 12 and earlier)
typescript
// ❌ 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
Examples of properties that SHOULD support Resource:
typescript
// 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)
Examples of properties that SHOULD NOT support Resource:
typescript
// 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
Benefits of ResourceStr support (for NEW APIs only):
  • Enables centralized theme management through resource files
  • Supports internationalization with locale-specific resources
  • Allows dynamic theming without code changes
  • Type simplification: Use 
    ResourceStr
    instead of 
    string | Resource
  • Backward compatibility: Preserve existing API signatures for API 12 and earlier
重要提示：并非所有属性都需要支持Resource类型。仅当属性需要通过资源文件配置（主题、国际化等）时，才添加Resource类型支持。
需要支持Resource类型的场景：
  • ✅ 是：颜色、字体、尺寸、字符串、图片等开发者可能通过资源文件进行主题配置或国际化的属性
  • ❌ 否：状态标志、模式选择器、事件回调等仅运行时配置的属性
类型简化规则： 关键要求：仅在**新增API（API 13及以上）**中使用
ResourceStr
。请勿使用
ResourceStr
修改现有API（API 12及更早版本）。
使用ResourceStr的场景：
  • ✅ 是：新增的属性/方法（API 13或更高版本引入）
  • ❌ 否：现有属性/方法（API 12及更早版本）
typescript
// ❌ 错误：为API 12（现有属性）使用ResourceStr
content(value: ResourceStr): TextAttribute  // API 12 - 请勿修改

// ✅ 正确：为API 12使用string | Resource（保持向后兼容）
content(value: string | Resource): TextAttribute  // API 12 - 保持原样

// ✅ 正确：为新增API 13使用ResourceStr（新增属性）
fontSize(value: number | string | Length | ResourceStr): TextAttribute  // API 13 - 新增属性

// 优势：
// - 为现有API保持向后兼容性
// - 为新增API简化类型定义
// - 在API 13处明确版本边界
应支持Resource类型的属性示例：
typescript
// 主题相关 - 是，支持Resource（API 12：保留原有类型）
fontSize(value: number | string | Length | Resource): TextAttribute
// API 12及更早版本：保持string | Resource以兼容旧代码

// 主题相关 - 是，支持Resource（API 13+：使用ResourceStr）
fontSize(value: number | string | Length | ResourceStr): TextAttribute
// API 13及更高版本：简化类型

// 使用示例（API 12 - 旧API，保持string | Resource）：
Text().fontSize(16)                              // 数字类型
Text().fontSize('16vp')                          // 字符串类型
Text().fontSize($r('app.float.font_size_large')) // Resource类型

// 使用示例（API 13+ - 新API，使用ResourceStr）：
Text().fontSize(16)                               // 数字类型
Text().fontSize('16vp')                          // 字符串类型
Text().fontSize($r('app.float.font_size_large')) // Resource类型（ResourceStr已覆盖）
不应支持Resource类型的属性示例：
typescript
// 状态标志 - 否，这些仅为运行时配置
stateEffect(value: boolean): ButtonAttribute
enabled(value: boolean): CommonMethod

// 事件回调 - 否，这些仅为运行时配置
onClick(callback: () => void): CommonMethod
为新增API支持ResourceStr的优势：
  • 支持通过资源文件集中管理主题
  • 支持基于区域设置的国际化资源
  • 无需修改代码即可实现动态主题切换
  • 类型简化：使用
    ResourceStr
    替代
    string | Resource
  • 向后兼容：保留API 12及更早版本的原有API签名

4. Document undefined/null Behavior

4. 文档化undefined/null行为

JSDOC comments must explicitly specify how 
undefined
and 
null
values are handled:
typescript
/**
 * 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;
Common patterns:
  • undefined
    → Restore default value
  • null
    → Remove setting, use inherited value
  • Invalid values → Throw error with clear message
JSDOC注释必须明确说明
undefined
和
null
值的处理方式：
typescript
/**
 * 设置文本字体大小。
 * @param value 字体大小值。若为undefined，恢复默认大小（16fp）。
 *              若为null，移除字体大小设置，使用继承值。
 * @throws {Error} 若值为负数则抛出错误。
 * @since 10
 */
fontSize(value: number | string | Length | Resource | undefined | null): TextAttribute;
常见处理模式：
  • undefined
    → 恢复默认值
  • null
    → 移除设置，使用继承值
  • 无效值 → 抛出带明确信息的错误

5. Use vp as Default Length Unit

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

Always use 
vp
(virtual pixels) as default unit for length measurements:
typescript
// 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
始终使用
vp
（虚拟像素）作为长度测量的默认单位：
typescript
// 推荐：默认使用vp
width(value: number | string): ButtonAttribute  // 100表示100vp

// 推荐：明确使用vp
width(value: Length): ButtonAttribute  // Length.type默认值为vp

// 避免：无特殊理由要求使用px
width(value: number): ButtonAttribute  // 100px - 非必要请勿使用

6. Specify Constraints in JSDOC

6. 在JSDOC中指定约束条件

JSDOC comments must include specification limits and constraints:
typescript
/**
 * 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;
Required documentation:
  • Valid ranges (min/max values)
  • Special value handling (negative, zero, etc.)
  • Unit of measurement
  • Clamping behavior (if applicable)
JSDOC注释必须包含规格限制和约束条件：
typescript
/**
 * 设置组件的边框圆角。
 * @param value 边框圆角值。有效范围：0-1000vp。
 *              超过1000vp的值将被限制为1000vp。
 *              负值将被视为0。
 * @unit vp
 * @since 10
 */
borderRadius(value: number | string | Length): CommonMethod;
必填文档内容：
  • 有效范围（最小值/最大值）
  • 特殊值处理（负数、零等）
  • 测量单位
  • 限制行为（若有）

7. Consider Cross-Component Impact

7. 考虑跨组件影响

When adding common properties, evaluate impact on all components:
Before adding common property:
  1. Check if property applies to most components (layout, style, event)
  2. Define consistent behavior across component types
  3. Document component-specific exceptions (if any)
  4. Consider backward compatibility
Example common properties:
  • Layout: 
    width()
    , 
    height()
    , 
    padding()
    , 
    margin()
  • Style: 
    opacity()
    , 
    visibility()
    , 
    borderRadius()
  • Event: 
    onClick()
    , 
    onTouch()
添加通用属性时，需评估对所有组件的影响：
添加通用属性前的检查：
  1. 检查该属性是否适用于大多数组件（布局、样式、事件）
  2. 定义跨组件类型的一致行为
  3. 记录组件特定的例外情况（若有）
  4. 考虑向后兼容性
通用属性示例：
  • 布局：
    width()
    、
    height()
    、
    padding()
    、
    margin()
  • 样式：
    opacity()
    、
    visibility()
    、
    borderRadius()
  • 事件：
    onClick()
    、
    onTouch()

8. Respect Interface Directory Boundaries

8. 遵守接口目录边界

During API design and compilation verification, work only with files within 
interface/
directory:
Allowed modifications:
  • interface/sdk-js/api/arkui/component/*.static.d.ets
    - Static API definitions
  • interface/sdk-js/api/@internal/component/ets/*.d.ts
    - Dynamic API definitions (Attribute classes)
  • interface/sdk-js/api/arkui/*Modifier.d.ts
    - Modifier class definitions (for AttributeModifier pattern)
  • Type definition files (*.d.ts, *.static.d.ets)
Do NOT modify:
  • Framework implementation code in 
    ace_engine/
  • Component pattern files
  • Layout or render implementations
在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 Design Workflow

API设计工作流程

Complete Workflow for New Component Properties

新增组件属性的完整流程

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
1. 设计API
   ├─ 定义属性类型和约束条件
   ├─ 文档化undefined/null行为
   └─ 检查跨组件影响

2. 创建静态API（.static.d.ets）
   ├─ 向组件类添加属性
   ├─ 编写完整的JSDOC
   └─ 包含@since、@syscap标签

3. 创建动态API（@internal/component/ets/*.d.ts）
   ├─ 向Attribute类添加方法
   ├─ 匹配静态API的签名
   └─ 同步JSDOC文档

4. 验证类型安全
   ├─ 检查TypeScript编译情况
   ├─ 验证类型定义
   └─ 确保签名一致性

5. 构建SDK
   ├─ 运行SDK构建命令
   └─ 监控编译错误

6. 验证SDK输出
   ├─ 检查生成的API文件
   ├─ 验证新增API已导出
   └─ 测试API可用性

For New Component APIs

新增组件API的流程

  1. Design API interface with proper TypeScript types
  2. Create Static API (
    component/*.static.d.ets
    )
    • Define component class with properties
    • Add constructor and methods
    • Write complete JSDOC comments
  3. Create Dynamic API (
    @internal/component/ets/*.d.ts
    )
    • Define Attribute class methods
    • Add all property methods
    • Sync with static API signatures
  4. Add JSDOC comments including:
    • Parameter descriptions
    • undefined/null handling
    • Value constraints and ranges
    • Default values
    • @since version
    • @syscap capability
    • @throws documentation (if applicable)
  5. Support Resource type for theme-able properties
  6. Specify units (default to vp for lengths)
  7. Verify cross-component impact if adding common property
  8. Build SDK to verify compilation
  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以验证编译情况

For API Reviews

API审核流程

Use the following checklist to verify:
  • Static API (
    .static.d.ets
    ) exists and is complete
  • Dynamic API (
    @internal/component/ets/*.d.ts
    ) exists and is synchronized
  • Parameter types match between static and dynamic
  • Version tags correct (
    @since X static
    vs 
    @since X dynamic
    )
  • Return type convention correct (
    this
    in static, concrete type in dynamic)
  • Compliance with coding standards
  • Resource type support where appropriate
  • Complete JSDOC documentation
  • Constraint specifications
  • Cross-component consistency
  • @since and @syscap tags present
使用以下检查清单进行验证：
  • 静态API（
    .static.d.ets
    ）已存在且完整
  • 动态API（
    @internal/component/ets/*.d.ts
    ）已存在且与静态API同步
  • 静态与动态API的参数类型匹配
  • 版本标签正确（
    @since X static
    vs 
    @since X dynamic
    ）
  • 返回类型符合规范（静态API使用
    this
    ，动态API使用具体类型）
  • 符合编码标准
  • 必要时已支持Resource类型
  • JSDOC文档完整
  • 约束条件已明确
  • 跨组件行为一致
  • @since和@syscap标签已添加

For API Deprecation

API废弃流程

CRITICAL: When deprecating an API, you MUST mark BOTH the static API property/method AND the corresponding dynamic API method as 
@deprecated
.
  1. Mark both static and dynamic APIs as 
    @deprecated
  2. Provide migration path in JSDOC
  3. Specify removal version (@obsoleted)
  4. Update documentation and examples
Synchronization Requirement:
  • If you deprecate a property in static API → MUST deprecate in dynamic API
  • If you deprecate a method in static API → MUST deprecate in dynamic API
  • Both must have matching @deprecated, @obsoleted, @see, and @migration tags
关键要求：废弃API时，必须同时将静态API的属性/方法和对应的动态API方法标记为
@deprecated
。
  1. 将静态和动态API均标记为
    @deprecated
  2. 在JSDOC中提供迁移路径
  3. 指定移除版本（@obsoleted）
  4. 更新文档和示例
同步要求：
  • 若废弃静态API中的属性 → 必须同时废弃动态API中的对应方法
  • 若废弃静态API中的方法 → 必须同时废弃动态API中的对应方法
  • 两者必须包含匹配的@deprecated、@obsoleted、@see和@migration标签

SDK Build and Verification

SDK构建与验证

Building the SDK

构建SDK

After completing API design changes, build the SDK to verify compilation and generate output:
bash
undefined
完成API设计变更后，构建SDK以验证编译情况并生成输出：
bash
undefined

From OpenHarmony root directory

从OpenHarmony根目录执行

./build.sh --export-para PYCACHE_ENABLE:true --product-name ohos-sdk --ccache

**Build Parameters:**
- `--export-para PYCACHE_ENABLE:true` - Enable Python cache for faster builds
- `--product-name ohos-sdk` - Build SDK target
- `--ccache` - Use compiler cache for incremental builds

**Build Output Location:**
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 │ └── ...
undefined
./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/ # 生成的.static.d.ets文件 │ │ ├── button.static.d.ets │ │ ├── text.static.d.ets │ │ └── ... │ ├── ButtonModifier.d.ts # 生成的.d.ts文件 │ ├── TextModifier.d.ts │ └── ...
undefined

Verification Steps

验证步骤

After SDK build completes successfully:
SDK构建成功后，执行以下验证：

1. Verify Static API

1. 验证静态API

bash
undefined
bash
undefined

Check if .static.d.ets file contains your changes

检查.static.d.ets文件是否包含你的变更

grep -n "yourNewProperty" out/ohos-sdk/interfaces/sdk-js/api/arkui/component/<yourcomponent>.static.d.ets
undefined
grep -n "yourNewProperty" out/ohos-sdk/interfaces/sdk-js/api/arkui/component/<yourcomponent>.static.d.ets
undefined

2. Verify Dynamic API

2. 验证动态API

bash
undefined
bash
undefined

Check if @internal/component/ets/*.d.ts file contains your changes

检查@internal/component/ets/*.d.ts文件是否包含你的变更

grep -n "yourNewMethod" out/ohos-sdk/interfaces/sdk-js/api/@internal/component/ets/<your_component>.d.ts
undefined
grep -n "yourNewMethod" out/ohos-sdk/interfaces/sdk-js/api/@internal/component/ets/<your_component>.d.ts
undefined

3. Verification Checklist

3. 验证检查清单

  • Build completes without errors
  • Static API file (
    .static.d.ets
    ) contains new/modified properties
  • Dynamic API file (
    @internal/component/ets/*.d.ts
    ) contains corresponding methods
  • JSDOC comments are present and complete
  • Type signatures match between static and dynamic APIs
  • Version tags correct (
    @since X static
    vs 
    @since X dynamic
    )
  • No compilation warnings or errors in interface files
  • 构建过程无错误
  • 静态API文件（
    .static.d.ets
    ）包含新增/修改的属性
  • 动态API文件（
    @internal/component/ets/*.d.ts
    ）包含对应的方法
  • JSDOC注释存在且完整
  • 静态与动态API的类型签名匹配
  • 版本标签正确（
    @since X static
    vs 
    @since X dynamic
    ）
  • 接口文件无编译警告或错误

4. Common Build Issues

4. 常见构建问题

IssueSymptomSolution
Type mismatchBuild fails with type errorCheck signatures match between static/dynamic APIs
Missing importCannot find typeAdd proper import statements
JSDOC errorDocumentation warningFix JSDOC syntax, ensure all tags are valid
Sync errorAPI exists in one file onlyAdd to both static and dynamic files
问题症状解决方案
类型不匹配构建因类型错误失败检查静态/动态API的签名是否匹配
缺少导入找不到类型添加正确的导入语句
JSDOC错误文档警告修复JSDOC语法，确保所有标签有效
同步错误API仅存在于一个文件中在静态和动态文件中均添加该API

Code Examples

代码示例

Example 1: Complete Static + Dynamic API

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

Static API: 
button.static.d.ets

静态API: 
button.static.d.ets

typescript
/**
 * 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);
}
typescript
/**
 * 提供按钮组件。
 *
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 7
 */
declare class Button {
  /**
   * 按钮类型。
   *
   * @type { ButtonType }
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7
   */
  type: ButtonType;

  /**
   * 按钮状态效果。
   *
   * @type { ButtonState }
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7
   */
  stateEffect: boolean;

  /**
   * 创建按钮组件。
   *
   * @param label - 按钮标签文本。
   * @param options - 按钮选项。
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7
   */
  constructor(label: string | Resource, options?: ButtonOptions);
}

Dynamic API: 
button.d.ts
(in 
@internal/component/ets/
)

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

typescript
/**
 * 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;
}
typescript
/**
 * 按钮Attribute类。
 *
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @since 7 dynamic
 */
declare class ButtonAttribute extends CommonMethod<ButtonAttribute> {
  /**
   * 设置按钮类型。
   *
   * @param value - 要设置的按钮类型。
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7 dynamic
   */
  type(value: ButtonType): ButtonAttribute;

  /**
   * 启用或禁用状态效果。
   *
   * @param value - 是否启用状态效果。默认值为true。
   *              若为undefined，启用状态效果。
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7 dynamic
   */
  stateEffect(value: boolean): ButtonAttribute;
}

Example 2: Adding a New Property

示例2：添加新属性

Adding 
iconSize
to Button

为Button添加
iconSize
属性

Static API Update:
typescript
// 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;
}
Dynamic API Update:
typescript
// 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;
}
静态API更新：
typescript
// File: button.static.d.ets
declare class Button {
  // 现有属性...
  /**
   * 图标尺寸。
   *
   * @type { number | string }
   * @unit vp
   * @default 24vp
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 12
   */
  iconSize: number | string;
}
动态API更新：
typescript
// File: button.d.ts (in @internal/component/ets/)
declare class ButtonAttribute extends CommonMethod<ButtonAttribute> {
  // 现有方法...

  /**
   * 设置图标尺寸。
   *
   * @param value - 图标尺寸（单位：vp）。有效范围：0-100vp。
   *              若为undefined，恢复默认尺寸（24vp）。
   * @unit vp
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 12 dynamic
   */
  iconSize(value: number | string | Length | undefined): ButtonAttribute;
}

Example 3: API Deprecation

示例3：API废弃

Deprecating 
setFontSize
in favor of 
fontSize

废弃
setFontSize
，改用
fontSize

Static API:
typescript
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;
}
Dynamic API:
typescript
// 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：
typescript
declare class Text {
  /**
   * 字体大小。
   *
   * @type { number | string | Resource }
   * @unit fp
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7
   */
  fontSize: number | string | Resource;

  /**
   * 设置字体大小。
   *
   * @param value - 字体大小值。
   * @deprecated since 10. 请使用fontSize属性替代。
   * @see fontSize
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7
   * @obsoleted 10
   */
  setFontSize(value: number | string | Resource): void;
}
动态API：
typescript
// File: text.d.ts (in @internal/component/ets/)
declare class TextAttribute extends CommonMethod<TextAttribute> {
  /**
   * 设置字体大小。
   *
   * @param value - 字体大小（单位：fp）。有效范围：0-1000fp。
   * @unit fp
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 10 dynamic
   */
  fontSize(value: number | string | Length | Resource | undefined | null): TextAttribute;

  /**
   * 设置字体大小（已废弃方法）。
   *
   * @param value - 字体大小值。
   * @deprecated since 10. 请使用fontSize()替代。
   * @see fontSize
   * @syscap SystemCapability.ArkUI.ArkUI.Full
   * @since 7 dynamic
   * @obsoleted 10
   */
  setFontSize(value: number | string | Resource): TextAttribute;
}

Common Pitfalls

常见陷阱

Missing Static/Dynamic Synchronization

缺少静态/动态接口同步

typescript
// ❌ 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;
}
typescript
// ❌ 错误：仅定义了静态API
// File: text.static.d.ets
declare class Text {
  content: string | Resource;
}

// 缺失：@internal/component/ets/text.d.ts中没有content()方法

// ✅ 正确：两个API均已同步
// 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;
}

Inconsistent Signatures

签名不一致

typescript
// ❌ 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
typescript
// ❌ 错误：签名不匹配
// 静态API: .static.d.ets
iconSize: number;

// 动态API: @internal/component/ets/*.d.ts
iconSize(value: number | string | Resource): ButtonAttribute; // 类型不同！

// ✅ 正确：类型一致
// 静态API: .static.d.ets
iconSize: number | string;

// 动态API: @internal/component/ets/*.d.ts
iconSize(value: number | string): ButtonAttribute; // 匹配

Incomplete JSDOC

JSDOC不完整

typescript
// ❌ 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;
typescript
// ❌ 错误：缺少null/undefined处理和约束条件
/**
 * 设置宽度。
 */
width(value: number): CommonMethod;

// ✅ 正确：文档完整
/**
 * 设置组件宽度。
 * @param value 宽度值（单位：vp）。有效范围：0-10000vp。
 *              若为undefined，恢复默认宽度。
 * @unit vp
 * @since 8
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 */
width(value: number | string | Length | undefined): CommonMethod;

Forgetting Resource Type

忘记支持Resource类型

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

// ✅ Better: Supports resource theming
fontSize(value: number | string | Length | Resource): TextAttribute;
typescript
// ⚠️ 不够优化：仅支持number/string
fontSize(value: number | string): TextAttribute;

// ✅ 更佳：支持资源主题化
fontSize(value: number | string | Length | Resource): TextAttribute;

Additional Resources

附加资源

Coding Standards

编码标准

  • references/OpenHarmony-Application-Typescript-JavaScript-coding-guide.md
    • OpenHarmony TypeScript/JavaScript Coding Guide (official complete version)
    • Contains naming conventions, type definitions, code formatting, and all coding standards
    • All design principles in this skill are based on this document
  • references/OpenHarmony-Application-Typescript-JavaScript-coding-guide.md
    • OpenHarmony TypeScript/JavaScript编码指南（官方完整版本）
    • 包含命名规范、类型定义、代码格式化及所有编码标准
    • 本技能中的所有设计原则均基于此文档

Example Code

示例代码

  • examples/interface-definition.ts
     - Complete interface definition example
  • examples/modifier-implementation.ts
     - Modifier method implementation example
  • examples/deprecation-pattern.ts
     - API deprecation with migration example
  • examples/static-dynamic-sync.ts
     - Static/Dynamic API synchronization example
  • examples/interface-definition.ts
     - 完整的接口定义示例
  • examples/modifier-implementation.ts
     - Modifier方法实现示例
  • examples/deprecation-pattern.ts
     - API废弃及迁移示例
  • examples/static-dynamic-sync.ts
     - 静态/动态API同步示例

Knowledge Base References

知识库参考

  • docs/sdk/Component_API_Knowledge_Base_CN.md
     - ArkUI 组件 API 知识库
    • Explains difference between static and dynamic APIs
    • File structure and organization
    • Component API classification
  • docs/sdk/ArkUI_SDK_API_Knowledge_Base.md
     - ArkUI SDK API 结构化分析文档
    • SDK API vs ace_engine implementation mapping
    • Static API vs Dynamic API comparison
    • FrameNode/BuilderNode/Modifier patterns
  • docs/sdk/Component_API_Knowledge_Base_CN.md
     - ArkUI 组件 API 知识库
    • 解释静态与动态API的区别
    • 文件结构与组织方式
    • 组件API分类
  • docs/sdk/ArkUI_SDK_API_Knowledge_Base.md
     - ArkUI SDK API 结构化分析文档
    • SDK API与ace_engine实现的映射关系
    • 静态API与动态API的对比
    • FrameNode/BuilderNode/Modifier模式

Quick Reference

快速参考

Essential JSDOC Tags

必备JSDOC标签

typescript
/**
 * 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)
 */
Important Tag Rules:
  • Static API (
    .static.d.ets
    )    : Use 
    @since X static
    format (e.g., 
    @since 26 static
    )
  • Dynamic API (
    *Modifier.d.ts
    )    : Use 
    @since X dynamic
    format (e.g., 
    @since 26 dynamic
    )
  • All APIs: Add 
    @stagemodelonly
    tag to indicate stage model only
typescript
/**
 * 简要描述。
 * @param paramName 描述，包括undefined/null处理和约束条件。
 * @unit vp | fp | px（针对长度值）
 * @throws {ErrorType} 描述（可能抛出错误的场景）
 * @since version static（静态API - 在版本后使用"static"）
 * @since version dynamic（动态API - 在版本后使用"dynamic"）
 * @syscap SystemCapability.ArkUI.ArkUI.Full（系统能力）
 * @stagemodelonly（表示此API仅适用于Stage模型）
 * @deprecated 请使用alternativeMethod()替代（针对已废弃API）
 * @obsoleted version（API被移除的版本）
 */
重要标签规则：
  • 静态API（
    .static.d.ets
    ）    ：使用
    @since X static
    格式（例如：
    @since 26 static
    ）
  • 动态API（
    *Modifier.d.ts
    ）    ：使用
    @since X dynamic
    格式（例如：
    @since 26 dynamic
    ）
  • 所有API：添加
    @stagemodelonly
    标签以表示仅适用于Stage模型

Type Support Decision Tree

类型支持决策树

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)
参数是否接受长度值？
├─ 是 → 添加Length和Resource类型
└─ 否 → 是否为可主题化属性（颜色、尺寸、字符串）？
    ├─ 是 → 添加Resource类型
    └─ 否 → 使用基础类型（number | string | undefined | null）

Default Value Documentation

默认值文档规范

typescript
// Document defaults in JSDOC:
"If undefined, restores to default [value] ([unit])."
"If null, removes setting and uses inherited value."
typescript
// 在JSDOC中记录默认值：
"若为undefined，恢复为默认值[value]（单位：[unit]）。"
"若为null，移除设置并使用继承值。"

Static vs Dynamic API Quick Reference

静态与动态API快速对比

AspectStatic API (
.static.d.ets
)		Dynamic API (
*.d.ts
)
File Location
arkui/component/
@internal/component/ets/
Usage
Text({ content: 'Hello' })
Text().content('Hello')
TypeClass declarationClass extending CommonMethod
PatternConstructor-basedMethod chaining
Return TypeN/A (properties)Concrete Attribute type
Version Tag
@since X static
@since X dynamic
Both Required✅ Yes✅ Yes
维度静态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
是否必填✅ 是✅ 是

Static/Dynamic Synchronization Checklist

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

Before finalizing any API, verify:
在最终确定任何API前，验证以下内容：

Files Updated

文件已更新

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

Signatures Match

签名匹配

  • Parameter types identical
  • Optional parameters consistent
  • Generic types aligned
  • 参数类型完全一致
  • 可选参数一致
  • 泛型类型对齐

JSDOC Complete

JSDOC完整

  • @param descriptions match
  • @returns descriptions match (dynamic only)
  • Version tags: 
    @since XX static
    vs 
    @since XX dynamic
  • @syscap tags identical
  • @unit tags consistent
  • @param描述匹配
  • @returns描述匹配（仅动态API）
  • 版本标签：
    @since XX static
    vs 
    @since XX dynamic
  • @syscap标签完全一致
  • @unit标签一致

Return Type Convention

返回类型符合规范

  • Static: Properties (no return type for properties)
  • Dynamic: Concrete type (e.g., 
    ButtonAttribute
    )
  • 静态API：属性（属性无返回类型）
  • 动态API：具体类型（例如：
    ButtonAttribute
    ）

Version Tags

版本标签正确

  • Static: 
    @since 26 static
  • Dynamic: 
    @since 26 dynamic
  • 静态API：
    @since 26 static
  • 动态API：
    @since 26 dynamic

Compilation Verified

编译已验证

  • Static file compiles
  • Dynamic file compiles
  • No type errors
  • No JSDOC warnings
  • 静态文件可编译
  • 动态文件可编译
  • 无类型错误
  • 无JSDOC警告

Common Mistakes to Avoid

需避免的常见错误

1. Only Updating One File

1. 仅更新一个文件

❌ Bad: Only static file updated
typescript
// Static: richEditor.static.d.ets
default lineSpacing(value: LengthMetrics | undefined): this;

// Dynamic: rich_editor.d.ts
// Method is missing! ✗
✅ Good: Both files updated
typescript
// 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;
❌ 错误：仅更新了静态文件
typescript
// 静态API: richEditor.static.d.ets
default lineSpacing(value: LengthMetrics | undefined): this;

// 动态API: rich_editor.d.ts
// 方法缺失！ ✗
✅ 正确：两个文件均已更新
typescript
// 静态API: richEditor.static.d.ets
default lineSpacing(value: LengthMetrics | undefined, options?: LineSpacingOptions): this;

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

2. Inconsistent Parameter Types

2. 参数类型不一致

❌ Bad: Different parameter types
typescript
// Static:
default lineSpacing(value: LengthMetrics): this;

// Dynamic:
lineSpacing(value: LengthMetrics | undefined): RichEditorAttribute;
// ✗ Parameter types don't match!
✅ Good: Identical parameter types
typescript
// Static:
default lineSpacing(value: LengthMetrics | undefined, options?: LineSpacingOptions): this;

// Dynamic:
lineSpacing(value: LengthMetrics | undefined, options?: LineSpacingOptions): RichEditorAttribute;
// ✓ Parameters match perfectly
❌ 错误：参数类型不同
typescript
// 静态API:
default lineSpacing(value: LengthMetrics): this;

// 动态API:
lineSpacing(value: LengthMetrics | undefined): RichEditorAttribute;
// ✗ 参数类型不匹配！
✅ 正确：参数类型完全一致
typescript
// 静态API:
default lineSpacing(value: LengthMetrics | undefined, options?: LineSpacingOptions): this;

// 动态API:
lineSpacing(value: LengthMetrics | undefined, options?: LineSpacingOptions): RichEditorAttribute;
// ✓ 参数完全匹配

3. Missing Version Tags

3. 缺少版本标签

❌ Bad: Generic version tags
typescript
// Static: @since 26
// Dynamic: @since 26
// ✗ Missing static/dynamic specification
✅ Good: Proper version tags
typescript
// Static: @since 26 static
// Dynamic: @since 26 dynamic
// ✓ Clear distinction
❌ 错误：通用版本标签
typescript
// 静态API: @since 26
// 动态API: @since 26
// ✗ 缺少static/dynamic标识
✅ 正确：正确的版本标签
typescript
// 静态API: @since 26 static
// 动态API: @since 26 dynamic
// ✓ 区分明确

4. Wrong File Location

4. 文件路径错误

❌ Bad: Looking for dynamic API in wrong location
typescript
// Looking in: arkui/ButtonModifier.d.ts
// This file only defines Modifier class, not Attribute interface!
✅ Good: Correct file location
typescript
// Dynamic API is in: @internal/component/ets/button.d.ts
// This file defines ButtonAttribute class with all methods
❌ 错误：在错误路径中查找动态API
typescript
// 查找路径: arkui/ButtonModifier.d.ts
// 此文件仅定义Modifier类，而非属性接口！
✅ 正确：正确的文件路径
typescript
// 动态API位于: @internal/component/ets/button.d.ts
// 此文件定义了包含所有方法的ButtonAttribute类