1 Star 0 Fork 0

votzone / ARouter

Create your Gitee Account
Explore and code with more than 12 million developers,Free private repositories !:)
Sign up
Clone or Download
contribute
Sync branch
Cancel
Notice: Creating folder will generate an empty file .keep, because not support in Git
Loading...
README
Apache-2.0
    A framework for assisting in the renovation of Android app componentization

中文文档

Join the chat at https://gitter.im/alibaba/ARouter Hex.pm

Lastest version

module arouter-api arouter-compiler arouter-register arouter-idea-plugin
version Download Download Download as plugin

Demo

Demo apkDemo Gif

I. Feature

  1. Supports direct parsing of standard URLs for jumps and automatic injection of parameters into target pages
  2. Support for multi-module
  3. Support for interceptor
  4. Support for dependency injection
  5. InstantRun support
  6. MultiDex support
  7. Mappings are grouped by group, multi-level management, on-demand initialization
  8. Supports users to specify global demotion and local demotion strategies
  9. Activity, interceptor and service can be automatically registered to the framework
  10. Support multiple ways to configure transition animation
  11. Support for fragment
  12. Full kotlin support (Look at Other#2)
  13. Generate route doc support
  14. Provide IDE plugin for quick navigation to target class
  15. Support Incremental annotation processing
  16. Support register route meta dynamic.

II. Classic Case

  1. Forward from external URLs to internal pages, and parsing parameters
  2. Jump and decoupling between multi-module
  3. Intercept jump process, handle login, statistics and other logic
  4. Cross-module communication, decouple components by IoC

III. Configuration

  1. Adding dependencies and configurations

    android {
        defaultConfig {
            ...
            javaCompileOptions {
                annotationProcessorOptions {
                    arguments = [AROUTER_MODULE_NAME: project.getName()]
                }
            }
        }
    }
    
    dependencies {
        // Replace with the latest version
        compile 'com.alibaba:arouter-api:?'
        annotationProcessor 'com.alibaba:arouter-compiler:?'
        ...
    }
    // Old version of gradle plugin (< 2.2), You can use apt plugin, look at 'Other#1'
    // Kotlin configuration reference 'Other#2'
  2. Add annotations

    // Add annotations on pages that support routing (required)
    // The path here needs to pay attention to need at least two levels : /xx/xx
    @Route(path = "/test/activity")
    public class YourActivity extend Activity {
        ...
    }
  3. Initialize the SDK

    if (isDebug()) {           // These two lines must be written before init, otherwise these configurations will be invalid in the init process
        ARouter.openLog();     // Print log
        ARouter.openDebug();   // Turn on debugging mode (If you are running in InstantRun mode, you must turn on debug mode! Online version needs to be closed, otherwise there is a security risk)
    }
    ARouter.init(mApplication); // As early as possible, it is recommended to initialize in the Application
  4. Initiate the routing

    // 1. Simple jump within application (Jump via URL in 'Advanced usage')
    ARouter.getInstance().build("/test/activity").navigation();
    
    // 2. Jump with parameters
    ARouter.getInstance().build("/test/1")
                .withLong("key1", 666L)
                .withString("key3", "888")
                .withObject("key4", new Test("Jack", "Rose"))
                .navigation();
  5. Add confusing rules (If Proguard is turn on)

    -keep public class com.alibaba.android.arouter.routes.**{*;}
    -keep public class com.alibaba.android.arouter.facade.**{*;}
    -keep class * implements com.alibaba.android.arouter.facade.template.ISyringe{*;}
    
    # If you use the byType method to obtain Service, add the following rules to protect the interface:
    -keep interface * implements com.alibaba.android.arouter.facade.template.IProvider
    
    # If single-type injection is used, that is, no interface is defined to implement IProvider, the following rules need to be added to protect the implementation
    # -keep class * implements com.alibaba.android.arouter.facade.template.IProvider
  6. Using the custom gradle plugin to autoload the routing table

    apply plugin: 'com.alibaba.arouter'
    
    buildscript {
        repositories {
            mavenCentral()
        }
    
        dependencies {
            // Replace with the latest version
            classpath "com.alibaba:arouter-register:?"
        }
    }

    Optional, use the registration plugin provided by the ARouter to automatically load the routing table(power by AutoRegister). By default, the ARouter will scanned the dex files . Performing an auto-registration via the gradle plugin can shorten the initialization time , it should be noted that the plugin must be used with api above 1.3.0!

  7. use ide plugin for quick navigation to target class (Optional)

    Search for ARouter Helper in the Android Studio plugin market, or directly download the arouter-idea-plugin zip installation package listed in the Latest version above the documentation, after installation plugin without any settings, U can find an icon at the beginning of the jump code. (navigation) click the icon to jump to the target class that identifies the path in the code.

IV. Advanced usage

  1. Jump via URL

    // Create a new Activity for monitoring Scheme events, and then directly pass url to ARouter
    public class SchemeFilterActivity extends Activity {
        @Override
        protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
    
            Uri uri = getIntent().getData();
            ARouter.getInstance().build(uri).navigation();
            finish();
        }
    }

    AndroidManifest.xml

    <activity android:name=".activity.SchemeFilterActivity">
        <!-- Scheme -->
        <intent-filter>
            <data
                android:host="m.aliyun.com"
                android:scheme="arouter"/>
    
            <action android:name="android.intent.action.VIEW"/>
    
            <category android:name="android.intent.category.DEFAULT"/>
            <category android:name="android.intent.category.BROWSABLE"/>
        </intent-filter>
    </activity>
  2. Parse the parameters in the URL

    // Declare a field for each parameter and annotate it with @Autowired
    @Route(path = "/test/activity")
    public class Test1Activity extends Activity {
        @Autowired
        public String name;
        @Autowired
        int age;
        @Autowired(name = "girl") // Map different parameters in the URL by name
        boolean boy;
        @Autowired
        TestObj obj;    // Support for parsing custom objects, using json pass in URL
    
        @Override
        protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            ARouter.getInstance().inject(this);
    
            // ARouter will automatically set value of fields
            Log.d("param", name + age + boy);
        }
    }
    
    // If you need to pass a custom object, Create a new class(Not the custom object class),implement the SerializationService, And use the @Route annotation annotation, E.g:
    @Route(path = "/yourservicegroupname/json")
    public class JsonServiceImpl implements SerializationService {
        @Override
        public void init(Context context) {
    
        }
    
        @Override
        public <T> T json2Object(String text, Class<T> clazz) {
            return JSON.parseObject(text, clazz);
        }
    
        @Override
        public String object2Json(Object instance) {
            return JSON.toJSONString(instance);
        }
    }
  3. Declaration Interceptor (Intercept jump process, AOP)

    // A more classic application is to handle login events during a jump so that there is no need to repeat the login check on the target page.
    // Interceptors will be executed between jumps, multiple interceptors will be executed in order of priority
    @Interceptor(priority = 8, name = "test interceptor")
    public class TestInterceptor implements IInterceptor {
        @Override
        public void process(Postcard postcard, InterceptorCallback callback) {
            ...
            // No problem! hand over control to the framework
            callback.onContinue(postcard);  
            
            // Interrupt routing process
            // callback.onInterrupt(new RuntimeException("Something exception"));      
    
            // The above two types need to call at least one of them, otherwise it will not continue routing
        }
    
        @Override
        public void init(Context context) {
            // Interceptor initialization, this method will be called when sdk is initialized, it will only be called once
        }
    }
  4. Processing jump results

    // U can get the result of a single jump
    ARouter.getInstance().build("/test/1").navigation(this, new NavigationCallback() {
        @Override
        public void onFound(Postcard postcard) {
        ...
        }
    
        @Override
        public void onLost(Postcard postcard) {
        ...
        }
    });
  5. Custom global demotion strategy

    // Implement the DegradeService interface
    @Route(path = "/xxx/xxx")
    public class DegradeServiceImpl implements DegradeService {
        @Override
        public void onLost(Context context, Postcard postcard) {
            // do something.
        }
    
        @Override
        public void init(Context context) {
    
        }
    }
  6. Decoupled by dependency injection : Service management -- Exposure services

    // Declaration interface, other components get the service instance through the interface
    public interface HelloService extends IProvider {
        String sayHello(String name);
    }
    
    @Route(path = "/yourservicegroupname/hello", name = "test service")
    public class HelloServiceImpl implements HelloService {
    
        @Override
        public String sayHello(String name) {
            return "hello, " + name;
        }
    
        @Override
        public void init(Context context) {
    
        }
    }
  7. Decoupled by dependency injection : Service management -- Discovery service

    public class Test {
        @Autowired
        HelloService helloService;
    
        @Autowired(name = "/yourservicegroupname/hello")
        HelloService helloService2;
    
        HelloService helloService3;
    
        HelloService helloService4;
    
        public Test() {
            ARouter.getInstance().inject(this);
        }
    
        public void testService() {
            // 1. Use Dependency Injection to discover services, annotate fields with annotations
            helloService.sayHello("Vergil");
            helloService2.sayHello("Vergil");
    
            // 2. Discovering services using dependency lookup, the following two methods are byName and byType
            helloService3 = ARouter.getInstance().navigation(HelloService.class);
            helloService4 = (HelloService) ARouter.getInstance().build("/yourservicegroupname/hello").navigation();
            helloService3.sayHello("Vergil");
            helloService4.sayHello("Vergil");
        }
    }
  8. Pretreatment Service

    @Route(path = "/xxx/xxx")
    public class PretreatmentServiceImpl implements PretreatmentService {
        @Override
        public boolean onPretreatment(Context context, Postcard postcard) {
            // Do something before the navigation, if you need to handle the navigation yourself, the method returns false
        }
    
        @Override
        public void init(Context context) {
    
        }
    }
  9. Dynamic register route meta Applicable to apps with plug-in architectures or some scenarios where routing information needs to be dynamically registered,Dynamic registration can be achieved through the interface provided by ARouter, The target page and service need not be marked with @Route annotation,Only the routing information of the same group can be registered in the same batch

        ARouter.getInstance().addRouteGroup(new IRouteGroup() {
            @Override
            public void loadInto(Map<String, RouteMeta> atlas) {
                atlas.put("/dynamic/activity",      // path
                    RouteMeta.build(
                        RouteType.ACTIVITY,         // Route type
                        TestDynamicActivity.class,  // Target class
                        "/dynamic/activity",        // Path
                        "dynamic",                  // Group
                        0,                          // not need
                        0                           // Extra tag, Used to mark page feature
                    )
                );
            }
        });

V. More features

  1. Other settings in initialization

    ARouter.openLog(); // Open log
    ARouter.openDebug(); // When using InstantRun, you need to open this switch and turn it off after going online. Otherwise, there is a security risk.
    ARouter.printStackTrace(); // Print thread stack when printing logs
  2. API description

    // Build a standard route request
    ARouter.getInstance().build("/home/main").navigation();
    
    // Build a standard route request, via URI
    Uri uri;
    ARouter.getInstance().build(uri).navigation();
    
    // Build a standard route request, startActivityForResult
    // The first parameter must be Activity and the second parameter is RequestCode
    ARouter.getInstance().build("/home/main", "ap").navigation(this, 5);
    
    // Pass Bundle directly
    Bundle params = new Bundle();
    ARouter.getInstance()
        .build("/home/main")
        .with(params)
        .navigation();
    
    // Set Flag
    ARouter.getInstance()
        .build("/home/main")
        .withFlags();
        .navigation();
    
    // For fragment
    Fragment fragment = (Fragment) ARouter.getInstance().build("/test/fragment").navigation();
                        
    // transfer the object 
    ARouter.getInstance()
        .withObject("key", new TestObj("Jack", "Rose"))
        .navigation();
    
    // Think the interface is not enough, you can directly set parameter into Bundle
    ARouter.getInstance()
            .build("/home/main")
            .getExtra();
    
    // Transition animation (regular mode)
    ARouter.getInstance()
        .build("/test/activity2")
        .withTransition(R.anim.slide_in_bottom, R.anim.slide_out_bottom)
        .navigation(this);
    
    // Transition animation (API16+)
    ActivityOptionsCompat compat = ActivityOptionsCompat.
        makeScaleUpAnimation(v, v.getWidth() / 2, v.getHeight() / 2, 0, 0);
    
    // ps. makeSceneTransitionAnimation, When using shared elements, you need to pass in the current Activity in the navigation method
    
    ARouter.getInstance()
        .build("/test/activity2")
        .withOptionsCompat(compat)
        .navigation();
            
    // Use green channel (skip all interceptors)
    ARouter.getInstance().build("/home/main").greenChannel().navigation();
    
    // Use your own log tool to print logs
    ARouter.setLogger();
    
    // Use your custom thread pool
    ARouter.setExecutor();
  3. Get the original URI

    String uriStr = getIntent().getStringExtra(ARouter.RAW_URI);
  4. Rewrite URL

    // Implement the PathReplaceService interface
    @Route(path = "/xxx/xxx")
    public class PathReplaceServiceImpl implements PathReplaceService {
        /**
        * For normal path.
        *
        * @param path raw path
        */
        String forString(String path) {
            // Custom logic
            return path;
        }
    
    /**
        * For uri type.
        *
        * @param uri raw uri
        */
        Uri forUri(Uri uri) {
            // Custom logic
            return url;
        }
    }
  5. Generate router doc

    // Edit build.gradle, add option 'AROUTER_GENERATE_DOC = enable'
    // Doc file : build/generated/source/apt/(debug or release)/com/alibaba/android/arouter/docs/arouter-map-of-${moduleName}.json
    android {
        defaultConfig {
            ...
            javaCompileOptions {
                annotationProcessorOptions {
                    arguments = [AROUTER_MODULE_NAME: project.getName(), AROUTER_GENERATE_DOC: "enable"]
                }
            }
        }
    }

VI. Other

  1. Old version of gradle plugin configuration

    apply plugin: 'com.neenbedankt.android-apt'
    
    buildscript {
        repositories {
            mavenCentral()
        }
    
        dependencies {
            classpath 'com.neenbedankt.gradle.plugins:android-apt:1.4'
        }
    }
    
    apt {
        arguments {
            AROUTER_MODULE_NAME project.getName();
        }
    }
    
    dependencies {
        compile 'com.alibaba:arouter-api:x.x.x'
        apt 'com.alibaba:arouter-compiler:x.x.x'
        ...
    }
  2. Kotlin project configuration

    // You can refer to the wording in the "module-kotlin" module
    apply plugin: 'kotlin-kapt'
    
    kapt {
        arguments {
            arg("AROUTER_MODULE_NAME", project.getName())
        }
    }
    
    dependencies {
        compile 'com.alibaba:arouter-api:x.x.x'
        kapt 'com.alibaba:arouter-compiler:x.x.x'
        ...
    }

VII. Communication

  1. Communication

    1. DingDing group1

      dingding

    2. QQ group1

      qq

    3. QQ group2

      qq

Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "{}" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright {yyyy} {name of copyright owner} Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

About

No description expand collapse
Java and 5 more languages
Apache-2.0
Cancel

Releases

No release

Contributors

All

Activities

Load More
can not load any more
1
https://gitee.com/votzone/ARouter.git
git@gitee.com:votzone/ARouter.git
votzone
ARouter
ARouter
master

Search

14c37bed 8189591 565d56ea 8189591