【Journey of HarmonyOS Next】DevEco Studio User Guide (19) -> PreviewChecker Detection Rules

1 -> @previewer/mandatory-default-value-for-local-initialization

For all components that will be previewed, if the properties of the component support local initialization, a valid runtime-independent default should be set to ensure that when the exception is called to the component, it will render normally, even if the input parameters are incomplete.

counterexample

@Entry
@Component
struct Index {
  message?: string;
  @BuilderParam myBuilder: () => void;

  build() {
    Row() {
      Column() {
        Text(this.message)
        this.myBuilder()
      }
    }
  }
}

Positive example

@Builder function MyBuilderFunction(): void {}

@Entry
@Component
struct Index {
  message?: string = 'message';
  @Provide messageA: string = 'messageA';
  @StorageLink('varA') varA: number = 2;
  @StorageProp('languageCode') lang: string = 'en';
  @LocalStorageLink('PropA') storageLink1: number = 1;
  @LocalStorageProp('PropB') storageLink2: number = 2;
  @BuilderParam myBuilder: () => void = MyBuilderFunction;

  build() {
    Row() {
      Column() {
        Text(this.message)
        this.myBuilder()
      }
    }
  }
}

2 -> @previewer/no-unallowed-decorator-on-root-component

For @Entry components, @Consume, @link, @ObjectLink, @prop annotations are not allowed; For @Preview component, it is recommended to use a parent component that defines a complete, legitimate, and runtime-independent default as a container for previewing that component.

counterexample

@Preview
@Component
struct LinkSample {
  @Link message: string;

  build() {
    Row() {
      Text(this.message)
    }
  }
}

Positive example

@Entry
@Component
struct LinkSampleContainer {
  @State message: string = 'Hello World';

  build() {
    Row() {
      LinkSample({message: this.message})
    }
  }
}

@Component
struct LinkSample {
  @Link message: string;

  build() {
    Row() {
      Text(this.message)
    }
  }
}

3 -> @previewer/paired-use-of-consume-and-provide

If a @Provide definition is missing, the @Consume component will not be able to get a valid value when previewing, and @Consume will not support local initialization. It is recommended that the @Consume decorated component should have a corresponding @Provide property on the ancestor component, and that the property should have a legitimate runtime-independent default value.

counterexample

@Entry
@Component
struct Parent {
  build() {
    Column() {
      Child()
    }
  }
}

@Component
struct Child {
  @Consume message: string;

  build() {
    Text(this.message)
  }
}

Positive example

@Entry
@Component
struct Parent {
  @Provide message: string = 'hello world';

  build() {
    Column() {
      Child()
    }
  }
}

@Component
struct Child {
  @Consume message: string;

  build() {
    Text(this.message)
  }
}

4 -> @previewer/no-page-method-on-preview-component

@Preview are usually decorated on components rather than @Entry page entry. onPageShow, onPageHide, and onBackPress take effect only on @Entry components. Therefore, it is forbidden to instantiate page-level methods such as onPageShow on non-routed components.

counterexample

@Preview
@Component
struct Index {
  @State message: string = 'Hello World';

  onPageShow(): void {}
  onPageHide(): void {}
  onBackPress(): void {}

  build() {
    Column() {
      Text(this.message)
    }
  }
}

Positive example

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  onPageShow(): void {}
  onPageHide(): void {}
  onBackPress(): void {}

  build() {
    Column() {
      Text(this.message)
    }
  }
}

5 -> @previewer/no-page-import-unmocked-hsp

Due to the lack of capabilities, the previewer cannot ensure that the HSP is working properly. UI code calls HSP may fail to execute as expected when the preview is run, and API calls that are not initialized correctly may cause exceptions, which may affect the UI rendering results. We recommend that you avoid referencing HSPs or set mock implementations for the HSPs that you want to preview and the components that depend on them.

counterexample

import { add } from 'library'; // 该模块未配置自定义mock。

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    Row() {
      Text(this.message)
        .onClick(() => add(1, 2))
    }
  }
}

Positive example

import { add } from 'library'; // 该模块已配置自定义mock，配置方法见下文。

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    Row() {
      Text(this.message)
        .onClick(() => add(1, 2))
    }
  }
}

Custom mock configuration:

// src/mock/mock-config.json5
{
  "library": {
    "source": "src/mock/myhsp.mock.ets"
  },
}

// src/mock/myhsp.mock.ets
export function add(a: number, b: number): number {
  return a + b;
}