arkui-api-design

ArkUI API 設計スキル

このスキルでは、OpenHarmony のアプリケーション向け TypeScript/JavaScript コーディングガイドラインに準拠した ArkUI コンポーネント API の設計、レビュー、保守に関する包括的なガイダンスを提供します。

設計の基本原則

1. OpenHarmony のコーディング標準に従う

すべての API 定義とコード例は、OpenHarmony Application TypeScript/JavaScript Coding Guide に準拠する必要があります。主な標準は次のとおりです。

• 命名規則：プロパティとメソッドには 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 属性インターフェース）

• 場所：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 以降） にのみ使用してください。既存 API（API 12 以前）の変更に ResourceStr を使用しないでください。

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 のみ）：

• リソースファイルを通じた一元的なテーマ管理が可能になります
• ロケール固有のリソースによる国際化をサポートします
• コードを変更せずに動的なテーマ設定が可能になります
• 型の簡略化：string | Resource の代わりに ResourceStr を使用します
• 後方互換性：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 の種類	適切な表現	例
プロパティセッター	「[property] を設定します。」／「[property] を指定します。」	Sets the font size.、Specifies the text color.
構成メソッド	「[feature] を構成します。」／「[feature] を有効／無効にします。」	Enables the state effect.、Configures the scroll behavior.
イベントコールバック	「[event] 時に呼び出されます。」／「[event] 時に呼び出されるコールバックです。」	Called when clicked.、Called when the scroll position changes.
ライフサイクルメソッド	「[lifecycle event] 時に呼び出されます。」	Called when the component appears.、Called when the component is about to disappear.

避けるべきよくある誤り

1. 「Called when the [property] is set」 - 最もよくある誤ったパターンです

   • ❌ Called when the font weight is set.
   • ✅ Sets the font weight of the text.

2. コールバックではないメソッドに「Called when [action]」を使う - プロパティセッターとコールバックを混同させます

   • ❌ Called when drawing a polygon.（プロパティセッターの場合）
   • ✅ Sets the drawing options for the polygon.

3. 能動的な構成に受動態を使う - セッターメソッドには能動態の動詞を使用します

   • ❌ When the border color is set...
   • ✅ Sets the border color of the component.

修正後の 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. Static API を作成する（component/*.static.d.ets）
   • プロパティを含むコンポーネントクラスを定義します
   • コンストラクターとメソッドを追加します
   • 完全な JSDOC コメントを記述します
3. Dynamic API を作成する（@internal/component/ets/*.d.ts）
   • Attribute クラスのメソッドを定義します
   • すべてのプロパティメソッドを追加します
   • Static API のシグネチャと同期させます
4. 次の内容を含む JSDOC コメントを追加します。
   • パラメーターの説明
   • undefined/null の処理
   • 値の制約と範囲
   • デフォルト値
   • @since バージョン
   • @syscap 機能
   • @throws の説明（該当する場合）
5. テーマ設定可能なプロパティでは Resource 型をサポートします
6. 単位を指定します（長さの単位はデフォルトで vp）
7. 共通プロパティを追加する場合は、コンポーネント間への影響を確認します
8. SDK をビルドして、コンパイルを検証します

API レビューの場合

次のチェックリストを使用して検証します。

• Static API（.static.d.ets）が存在し、完全である
• Dynamic API（@internal/component/ets/*.d.ts）が存在し、同期されている
• Static API と Dynamic API のパラメーター型が一致している
• バージョンタグが正しい（@since X static と @since X dynamic）
• 戻り値の型の規約が正しい（static では this、dynamic では具体的な型）
• コーディング標準に準拠している
• 適切な場合に Resource 型をサポートしている
• JSDOC ドキュメントが完全である
• 制約の仕様が記載されている
• コンポーネント間で一貫性がある
• @since タグと @syscap タグが記載されている

API の非推奨化の場合

重要：API を非推奨にする場合、Static API のプロパティ／メソッドと対応する Dynamic API のメソッドの両方に @deprecated を付ける必要があります。

1. Static API と Dynamic API の両方を @deprecated にします
2. JSDOC に移行手順を記載します
3. 削除バージョン（@obsoleted）を指定します
4. ドキュメントとサンプルを更新します

同期要件：

• Static API のプロパティを非推奨にする場合 → Dynamic API でも非推奨にする必要があります
• Static API のメソッドを非推奨にする場合 → Dynamic 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. Static 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. Dynamic 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. 検証チェックリスト

• ビルドがエラーなく完了する
• Static API ファイル（.static.d.ets）に新規／変更されたプロパティが含まれている
• Dynamic API ファイル（@internal/component/ets/*.d.ts）に対応するメソッドが含まれている
• JSDOC コメントが記載され、完全である
• Static API と Dynamic API の型シグネチャが一致している
• バージョンタグが正しい（@since X static と @since X dynamic）
• インターフェースファイルにコンパイルの警告やエラーがない

4. よくあるビルドの問題

問題	症状	解決策
型の不一致	型エラーでビルドが失敗する	Static API と Dynamic API のシグネチャが一致しているか確認します
インポートの不足	型が見つからない	適切なインポート文を追加します
JSDOC エラー	ドキュメントの警告	JSDOC の構文を修正し、すべてのタグが有効であることを確認します
同期エラー	API が一方のファイルにしか存在しない	Static API と Dynamic API の両方のファイルに追加します

---

コード例

例 1：Static API と Dynamic API の完全な例

Static 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);
}

Dynamic 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 の追加

Static 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;
}

Dynamic 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 と動的 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 - Modifier メソッド実装の例
• examples/deprecation-pattern.ts - API の廃止と移行の例
• examples/static-dynamic-sync.ts - 静的 API と動的 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 タグを追加します

型サポートの判断フロー

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 の同期チェックリスト

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 タグが統一されている

戻り値の型の規則

• 静的：プロパティ（プロパティに戻り値の型は指定しない）
• 動的：具体的な型（例：ButtonAttribute）

バージョンタグ

• 静的：@since 26 static
• 動的：@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