{"id":30804058,"url":"https://github.com/huolalatech/hll-wp-therouter-harmony","last_synced_at":"2025-09-05T23:10:44.910Z","repository":{"id":293575857,"uuid":"984001838","full_name":"HuolalaTech/hll-wp-therouter-harmony","owner":"HuolalaTech","description":"A framework for assisting in the renovation of HarmonyOS componentization(帮助 App 进行组件化改造的动态路由框架)","archived":false,"fork":false,"pushed_at":"2025-09-05T08:12:51.000Z","size":31175,"stargazers_count":72,"open_issues_count":0,"forks_count":4,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-09-05T09:25:43.132Z","etag":null,"topics":["harmony","harmonyos","harmonyos-next","navigation","router","therouter"],"latest_commit_sha":null,"homepage":"https://therouter.cn","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HuolalaTech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-15T08:41:29.000Z","updated_at":"2025-09-05T08:09:07.000Z","dependencies_parsed_at":null,"dependency_job_id":"878aac1f-c08f-4eeb-afa0-f2dfe08fa686","html_url":"https://github.com/HuolalaTech/hll-wp-therouter-harmony","commit_stats":null,"previous_names":["huolalatech/hll-wp-therouter-harmony"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/HuolalaTech/hll-wp-therouter-harmony","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HuolalaTech%2Fhll-wp-therouter-harmony","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HuolalaTech%2Fhll-wp-therouter-harmony/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HuolalaTech%2Fhll-wp-therouter-harmony/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HuolalaTech%2Fhll-wp-therouter-harmony/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HuolalaTech","download_url":"https://codeload.github.com/HuolalaTech/hll-wp-therouter-harmony/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HuolalaTech%2Fhll-wp-therouter-harmony/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273833395,"owners_count":25176291,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["harmony","harmonyos","harmonyos-next","navigation","router","therouter"],"created_at":"2025-09-05T23:10:42.689Z","updated_at":"2025-09-05T23:10:44.902Z","avatar_url":"https://github.com/HuolalaTech.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Harmony Dynamic Routing Framework: TheRouter\n\n[![Hex.pm](https://img.shields.io/hexpm/l/plug.svg)](https://www.apache.org/licenses/LICENSE-2.0)\n[![Language](https://img.shields.io/badge/Language-ArkTS-green)](https://kotlinlang.org/)\n[![Wiki](https://img.shields.io/badge/Wiki-open-green)](https://therouter.cn/harmony)\n\nHarmony | [Android](https://github.com/HuolalaTech/hll-wp-therouter-android) | [iOS](https://github.com/HuolalaTech/hll-wp-therouter-ios) | [Official Site](https://therouter.cn)\n\n---\n\n### 1. Feature Overview\n\nTheRouter for Harmony offers the following core capabilities:\n\n#### **Navigator**\n- Supports **one-to-many** or **one-to-one** mapping between `Path` and pages, resolving multi-platform path unification issues.\n- Page `Path` supports regex declarations.\n- Exports routing tables in **JSON** format.\n- Allows adding comments/descriptions to routing entries.\n- Supports dynamic JSON routing table updates (e.g., downgrading any page to H5).\n- Provides page redirection interception.\n- Enables routing to pages within third-party SDKs.\n\n#### **ServiceProvider**\n- Cross-module dependency injection.\n- Customizable injection rules with parameter support.\n- Cached injection objects (singleton-like behavior).\n\n#### **ActionManager**\n- Global callback configuration.\n- Chain-triggered multi-response handling.\n- Priority-based response control.\n- Supports method return values and parameters.\n- Call path tracing for debugging observer patterns (solves `Observable` tracking issues).\n\n---\n\n### 2. Usage Guide\n\n**For detailed documentation, visit [therouter.cn](https://therouter.cn/harmony).**\n\n#### 2.1 Prerequisites\nFor new projects: **Ensure the versions of `plugin` and `router` dependencies match exactly**.\n\nTheRouter offers **stable** and **RC** releases. Stable versions are recommended for production. Check the latest versions at:  \n[https://therouter.cn/docs/2022/09/06/01](https://therouter.cn/docs/2022/09/06/01)\n\n#### 2.2 Add Dependencies\nRun in the project root:\n\n```shell  \n# Core library  \nohpm i @therouter/library  \n\n# Plugin  \nnpm i @therouter/plugin  \n```  \n\n#### 2.3 Configure the Plugin\n1. Open `hvigor/hvigor-config.json5` and verify `dependencies` includes `\"@therouter/plugin\": \"x.x.x\"`.\n2. Update **all** module (`hsp`/`hap`/`har`) `hvigorfile.ts` files:\n\n```typescript  \n// For hap:  \nimport { hapPlugin } from \"@therouter/plugin\";  \nexport default { plugins: [hapPlugin()] }  \n\n// For har:  \nimport { harPlugin } from \"@therouter/plugin\";  \nexport default { plugins: [harPlugin()] }  \n\n// For hsp:  \nimport { hspPlugin } from \"@therouter/plugin\";  \nexport default { plugins: [hspPlugin()] }  \n```  \n\n#### 2.4 Initialization\nIn `UIAbility.onCreate()`:\n\n```typescript  \nonCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {  \n    TheRouter.init(this.context);  \n}  \n```  \n\n#### 2.5 Define Page Container\nTheRouter follows Huawei’s recommended `Navigation` implementation. Add a `TheRouterPage` container:\n\n```typescript  \nimport { TheRouterPage } from '@therouter/library';  \n\n@Entry  \n@Component  \nstruct Index {  \n  build() {  \n    RelativeContainer() {  \n      TheRouterPage({  \n        stackId: 'XXXX',  // [Required] Unique stack identifier  \n        root: 'path'      // [Required] Homepage path (format recommended)  \n        // Optional params (see docs)  \n      });  \n    }  \n    .height('100%')  \n    .width('100%')  \n  }  \n}  \n```  \n\n#### 2.6 Page Declaration \u0026 Navigation\nAnnotate target pages:\n\n```typescript  \n@Route({ path: \"http://therouter.com/home\" })  \nexport struct HomePage { ... }  \n```  \n\nNavigate with parameters:\n\n```typescript  \nTheRouter  \n  .build(\"http://therouter.com/home\")  \n  .withString('k', 'v')  // Pass params (optional)  \n  .with({ hello: 'world' })  // Alternative param syntax  \n  .navigation();  \n```  \n\nRetrieve params on the target page:  \nThere are two forms of parameter reception:  \n\n1. **Automatic reception via annotations**: By default, it supports `String`, the eight primitive data types, and custom object parsing.\n2. **Manual retrieval from the route via code**.\n\nWhen using annotations to receive objects, **`TheRouter.inject(this)` must be called**.\n\n```typescript  \n// Method 1: Auto-populate using annotations  \n  // Supports parsing into the eight primitive data types or their wrapper classes  \n  @Autowired()  \n  key1: string = '';  \n\n  // Allows custom parameter keys; if not specified, the variable name is used as the key  \n  @Autowired('hello')  \n  key2: string = '';  \n\n  // When using annotations to receive objects, this must be called.  \n  // Recommended to place it in `aboutToAppear()`.  \n  TheRouter.inject(this);  \n\n// Method 2: Retrieve parameters from the route via code  \n  // Can be called in any method; `getCurrentParam()` returns an `ESObject`  \n  const v = TheRouter.getCurrentParam()['k'];  \n```\n\n---\n\n### 3. Migrating from Other Routers\n\n#### 3.1 Migration Tool\nThe latest **DevEco-Studio plugin** includes a one-click migration tool (no standalone download needed).  \nAccess via: **Top Menu → Tools → TheRouter**.\n\nGuide: [https://therouter.cn/docs/2022/09/29/01](https://therouter.cn/docs/2022/09/29/01)\n\n\u003cimg src=\"https://cdn.kymjs.com:8843/therouter_assets/img/image/TheRouterIdeaPlugin11.png\" width=\"40%\" /\u003e  \n\n#### 3.2 Navigation Shortcuts\nWith the plugin installed:\n- Click the **green arrow** next to `TheRouter.build(path)` or `@Route` annotations to jump to definitions/usages.\n- For multi-path targets, a selection dialog will appear.\n\n**Latest version shows class names and line numbers for clarity.**\n\n\u003cimg src=\"https://cdn.kymjs.com:8843/therouter_assets/img/image/TheRouterIdeaPlugin1.jpg\" class=\"blog-img\"\u003e  \n\n#### 3.3 Feature Comparison\n\n| Feature | TheRouter | HMRouter | Navigation |  \n|---------|-----------|----------|------------|  \n| Cross-platform consistency (Android/iOS/Harmony) | ✔️ | ✖️ | ✖️ |  \n| Annotation-based routing | ✔️ | ✔️ | ✖️ |  \n| Regex path support | ✔️ | ✔️ | ✖️ |  \n| Interceptors | ✔️ (4 types) | ✔️ | ✖️ |  \n| Exportable routing tables (with comments) | ✔️ | ✔️ | ✖️ |  \n| Cross-module calls | ✔️ | ✔️ | ✖️ |  \n| Dynamic route modification | ✔️ | ✖️ | ✔️ (limited) |  \n| Remote routing table updates | ✔️ | ✖️ | ✖️ |  \n| Multi-path → single page | ✔️ | ✖️ | ✖️ |  \n| Open third-party SDK pages | ✔️ | ✖️ | ✖️ |  \n\n---\n\n### 4. Build \u0026 Debug\n\n#### 4.1 Project Structure\n\n```  \nTheRouter  \n  ├─entry          // Demo  \n  ├─business_a     // Modular demo module  \n  ├─business_b  \n  ├─base           // Base module demo  \n  ├─plugin         // Hvigor plugin source  \n  └─therouter      // Core library  \n```  \n\n---\n\n### 5. Changelog\n\nSee [Releases](https://github.com/HuolalaTech/hll-wp-therouter-harmony/releases).\n\n---\n\n### 6. Author\n\n\u003cimg src=\"https://github.com/HuolalaTech/hll-wp-therouter-android/wiki/uploads/image/hll.png\" width=\"40%\" alt=\"HUOLALA Tech\" /\u003e  \n\nJoin the **TheRouter WeChat Group**:  \n*If the QR code expires, add WeChat: `kymjs123`*\n\n\u003cimg src=\"https://cdn.kymjs.com:8843/therouter_assets/img/therouter_wx_group.png\" width=\"40%\" alt=\"TheRouter WeChat Group\" /\u003e  \n\n---\n\n### 7. License\n\nTheRouter is licensed under **Apache 2.0**: [LICENSE](https://github.com/HuolalaTech/hll-wp-therouter-android/blob/master/LICENSE).\n\n--- \n\nLet me know if you'd like any refinements!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuolalatech%2Fhll-wp-therouter-harmony","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhuolalatech%2Fhll-wp-therouter-harmony","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuolalatech%2Fhll-wp-therouter-harmony/lists"}