README_zh.md

Fragivity : Use Fragment like Activity

English | 中文文档

Fragivity可以帮助开发者基于Fragment打造单Activty架构的APP

• 更合理的Lifecycle： 页面跳转、返回等Lifecycle表现与Activity一致
• 多种启动模式： 支持Standard、SingleTop、SingleTask等多种LaunchMode
• 转场动画： 支持Transition、SharedElement等动画方式实现页面切换
• 更高效的通信： 可以基于Callback通信，简单直接
• 更友好的回退处理： 支持OnBackPressed事件拦截、支持滑动返回
• Deep Links： 通过URI跳转到指定Fragment
• Dialog： 支持DialogFragment显示

参考文档:

• Fragivity：像使用Activity一样使用Fragment
• Fragivity：对Fragment生命周期的优化处理
• Fragivity：如何处理BackStack的销毁重建

Installation

由于JCenter停服，0.2.1之后的依赖方式改为JitPack.

!注意: Group Name 有变化：com.github.fragivity -> com.github.vitaviva.fragivity

after 0.2.1

// add in your root build.gradle at the end of repositories
allprojects {
    repositories { 
        ...
        maven { url 'https://jitpack.io' }
    }
}

implementation 'com.github.vitaviva.fragivity:core:$latest_version'

before 0.2.0

implementation 'com.github.fragivity:core:$latest_version'

Quick start

1. declare NavHostFragment in layout

Like Navigation, Fragivity needs a NavHostFragment as the host of ChildFragments

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/container"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:fitsSystemWindows="true">

    <androidx.fragment.app.FragmentContainerView
        android:id="@+id/nav_host"
        android:name="androidx.navigation.fragment.NavHostFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:defaultNavHost="true" />
</FrameLayout>

2. load HomeFragment in Activity

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        proxyFragmentFactory()
        // with java
        // Fragivity.proxyFragmentFactory(this)

        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        val navHostFragment = supportFragmentManager
            .findFragmentById(R.id.nav_host) as NavHostFragment

        navHostFragment.loadRoot(HomeFragment::class)
        
        //or loadRoot with factory
        //navHostFragment.loadRoot{ HomeFragment() }

    }
}

!Note: 添加proxyFragmentFactory()确保fragments正常走到onStart/onStop，放在super.onCreate()之前

3. navigate to destination Fragment

//in HomeFragment
navigator.push(DestinationFragment::class) {
    arguments = bundleOf(KEY_ARGUMENT1 to "arg1", KEY_ARGUMENT2 to "arg2")
    //or applyArguments(KEY_ARGUMENT1 to "arg1", KEY_ARGUMENT2 to "arg2")

}

Launch Mode

Support multiple launch modes

navigator.push(DestinationFragment::class) {
    launchMode = LaunchMode.STANDARD //default
    //or LaunchMode.SINGLE_TOP, LaunchMode.SINGLE_TASK
}

Transition Animation

navigator.push(DestinationFragment::class) {
    //animator
    enterAnim = R.anim.slide_in
    exitAnim = R.anim.slide_out
    popEnterAnim = R.anim.slide_in_pop
    popExitAnim = R.anim.slide_out_pop
    
    //sharedElements
    sharedElements = sharedElementsOf(imageView to "id")
}

Communication

You can simply setup communication between two fragments

1. start destination Fragment with a callback

class HomeFragment : Fragment() {
    private val cb: (Int) -> Unit = { checked ->
        //...
    }

    //...

    fun startDestination() {
        navigator.push {
            DestinationFragment(cb)
        }
    }
  
    //...
}

2. callback to source Fragment

class DestinationFragment(val cb: (Int) -> Unit) : Fragment() {
    //...
    cb.invoke(xxx)
    //...
}

Show Dialog

1. declare a DialogFragment

class DialogFragment : DialogFragment() {

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View? {
        val root = inflater.inflate(R.layout.fragment_dialog, container, false)
        return root
    }
}

2. show it

navigator.showDialog(DialogFragment::class)

Deep links

1. add kapt dependencies

kapt 'com.github.fragivity:processor:$latest_version'

2. declare URI with @Deeplink annotation

@DeepLink(uri = "myapp://fragitiy.github.com/")
class DeepLinkFragment : Fragment() {
    //...
}

3. handle intent in MainActivity

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        
        //...
        
        navHostFragment.handleDeepLink(intent)

    }
}

4. start Activity with URI

val intent = Intent(Intent.ACTION_VIEW, Uri.parse("myapp://fragitiy.github.com/"))
startActivity(intent)

路由

1.在Activity中绑定Fragment

with(navHostFragment) {
    composable("feed") { FeedFragment.newInstance() }
    composable("search?keyword={keyword}", stringArgument("keyword")) {
        SearchFragment.newInstance()
    }
}

2.导航到目标Fragment

navigator.push("search?keyword=$value")
// or
navigator.push("search") {
    arguments = bundleOf("keyword" to value.toString())
}

navigator.popTo("search")

使用Java进行开发

Fragivity支持使用Java进行开发。参考:APIs For Java

FAQ

常见问题解答

License

Fragivity is licensed under the MIT License.