Skip to content

Commit

Permalink
Update doc for chinese.
Browse files Browse the repository at this point in the history
  • Loading branch information
@zhi1ong
zhi1ong committed Dec 14, 2016
1 parent 790909e commit dc043fc
Show file tree
Hide file tree
Showing 2 changed files with 421 additions and 58 deletions.
118 changes: 60 additions & 58 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@
ARouter is a middleware that help app navigating from external environment into internal activity on Android.
```

### [中文版 README.md](https://github.com/alibaba/ARouter/blob/master/README_CN.md)

#### Ⅰ. Feature
1. Support routing by URL patterns directly, resolve the params and do the assignment automatically. (*)
2. Support routing between internal activitys, Android original-style API.
Expand All @@ -26,7 +28,7 @@
1. Add dependencies

apply plugin: 'com.neenbedankt.android-apt'

buildscript {
repositories {
jcenter()
Expand All @@ -35,7 +37,7 @@
classpath 'com.neenbedankt.gradle.plugins:android-apt:1.4'
}
}

dependencies {
apt 'com.alibaba.android:arouter-compiler:x.x.x'
compile 'com.alibaba.android:arouter-api:x.x.x'
Expand All @@ -52,24 +54,24 @@
}

3. Initialization

ARouter.init(mApplication); // 尽可能早，推荐在Application中初始化

4. Navigating

// 1. 应用内简单的跳转(通过URL跳转在'中阶使用'中)
ARouter.getInstance().build("/test/1").navigation();

// 2. 跳转并携带参数
ARouter.getInstance().build("/test/1")
.withLong("key1", 666L)
.withString("key3", "888")
.navigation();

5. Add proguard rule(If proguard tools was used)

-keep public class com.alibaba.android.arouter.routes.**{*;}

#### Ⅳ. Further Usage
1. Route by URL

Expand All @@ -81,36 +83,36 @@
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);

// 外面用户点击的URL
Uri uri = getIntent().getData();
// 直接传递给ARouter即可
ARouter.getInstance().build(uri).navigation();
finish();
}
}

// AndroidManifest.xml 中 的参考配置
<activity android:name=".activity.SchameFilterActivity">
<!-- Schame -->
<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>

<!-- App Links -->
<intent-filter android:autoVerify="true">
<action android:name="android.intent.action.VIEW"/>

<category android:name="android.intent.category.DEFAULT"/>
<category android:name="android.intent.category.BROWSABLE"/>

<data
android:host="m.aliyun.com"
android:scheme="http"/>
Expand All @@ -133,36 +135,36 @@
private int age;
@Param(name = "girl") // 可以通过name来映射URL中的不同参数
private boolean boy;

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);

name = getIntent().getStringExtra("name");
age = getIntent().getIntExtra("age", -1);
boy = getIntent().getBooleanExtra("girl", false); // 注意：使用映射之后，要从Girl中获取，而不是boy
}
}
}

3. 开启ARouter参数自动注入(实验性功能，不建议使用，正在开发保护策略)

// 首先在Application中重写 attachBaseContext方法，并加入ARouter.attachBaseContext();
@Override
protected void attachBaseContext(Context base) {
super.attachBaseContext(base);

ARouter.attachBaseContext();
}

// 设置ARouter的时候，开启自动注入
ARouter.enableAutoInject();

// 至此，Activity中的属性，将会由ARouter自动注入，无需 getIntent().getStringExtra("xxx")等等

4. Define interceptor(intercept the navigating process, do stuff you want)

// 比较经典的应用就是在跳转过程中处理登陆事件，这样就不需要在目标页重复做登陆检查

// 拦截器会在跳转之间执行，多个拦截器会按优先级顺序依次执行
@Interceptor(priority = 666, name = "测试用拦截器")
public class TestInterceptor implements IInterceptor {
Expand All @@ -175,26 +177,26 @@
@Override
public void process(Postcard postcard, InterceptorCallback callback) {
...

callback.onContinue(postcard); // 处理完成，交还控制权
// callback.onInterrupt(new RuntimeException("我觉得有点异常")); // 觉得有问题，中断路由流程

// 以上两种至少需要调用其中一种，否则会超时跳过
}

/**
* Do your init work in this method, it well be call when processor has been load.
*
* @param context ctx
*/
@Override
public void init(Context context) {

}
}

5. Handle result returned after navigation

// 通过两个参数的navigation方法，可以获取单次跳转的结果
ARouter.getInstance().build("/test/1").navigation(this, new NavigationCallback() {
@Override
Expand All @@ -207,9 +209,9 @@
...
}
});

6. Custom global fallback strategy

// 实现DegradeService接口，并加上一个Path内容任意的注解即可
@Route(path = "/xxx/xxx") // 必须标明注解
public class DegradeServiceImpl implements DegradeService {
Expand All @@ -222,18 +224,18 @@
public void onLost(Context context, Postcard postcard) {
// do something.
}

/**
* Do your init work in this method, it well be call when processor has been load.
*
* @param context ctx
*/
@Override
public void init(Context context) {

}
}

7. Declare more information about targeted activity

// 我们经常需要在目标页面中配置一些属性，比方说"是否需要登陆"之类的
Expand All @@ -249,40 +251,40 @@
public interface IService extends IProvider {
String hello(String name);
}

/**
* Implemention
*/
@Route(path = "/service/1", name = "Test service")
public class ServiceImpl implements IService {

@Override
public String hello(String name) {
return "hello, " + name;
}

/**
* Do your init work in this method, it well be call when processor has been load.
*
* @param context ctx
*/
@Override
public void init(Context context) {

}
}

9. Service management - discover services

1. 可以通过两种API来获取Service，分别是ByName、ByType
IService service = ARouter.getInstance().navigation(IService.class); // ByType
IService service = (IService) ARouter.getInstance().build("/service/1").navigation(); // ByName

service.hello("zz");

2. 注意：推荐使用ByName方式获取Service，ByType这种方式写起来比较方便，但如果存在多实现的情况时，SDK不保证能获取到你想要的实现


#### Ⅴ. More function

1. More setting for initialization
Expand All @@ -294,14 +296,14 @@

// Build normally route request
ARouter.getInstance().build("/home/main").navigation();

// 构建标准的路由请求，并指定分组
ARouter.getInstance().build("/home/main", "ap").navigation();

// 构建标准的路由请求，通过Uri直接解析
Uri uri;
ARouter.getInstance().build(uri).navigation();

// 构建标准的路由请求，startActivityForResult
// navigation的第一个参数必须是Activity，第二个参数则是RequestCode
ARouter.getInstance().build("/home/main", "ap").navigation(this, 5);
Expand All @@ -312,45 +314,45 @@
.build("/home/main")
.with(params)
.navigation();

// Set flag
ARouter.getInstance()
.build("/home/main")
.withFlags();
.navigation();

// 觉得接口不够多，可以直接拿出Bundle赋值
ARouter.getInstance()
.build("/home/main")
.getExtra();

// 使用绿色通道(跳过所有的拦截器)
ARouter.getInstance().build("/home/main").greenChannal().navigation();

3. Fetch raw uri

String uriStr = getIntent().getStringExtra(ARouter.RAW_URI);

#### Ⅵ. Others

1. Concept of routing group

- ARouter classify all paths to different groups. A group will do the initialization when any path in the group is accessed first time.
- You can specify a group for certain path, or ARouter will extract the first segment in the path and take it as a group
- Notice: Once you manually specify a group for certain path, you should do the navigation by `ARouter.getInstance().build(path, group)` to designate the group explicitly

@Route(path = "/test/1", group = "app")

2. The similarities and differences between interceptor and service

- They need to implement different interface
- Interceptors will take effect in every navigation. Interceptors will initialize asynchronously at initialization of ARouter. If the initialization is not finished yet when first navigation execute, the navigation will block and wait.
- Services will do the initialization only when they are invoked. If a service has never been invoked in whole lifecycle, it won’t initialize.

3. Support Jack-Complier tool chain

- ARouter hide the messy params handling dependent on some javac APIs. As a result, when you use Jack to compile your project, some special work is needed.

// 在使用了Jack的模块的build.gradle中加入如下参数即可，moduleName保证和其他模块不重复，使用标准字符，不要使用各种特殊字符
apt {
arguments {
Expand Down
Loading

0 comments on commit dc043fc

Please sign in to comment.