{"id":13989450,"url":"https://github.com/baoyongzhang/Treasure","last_synced_at":"2025-07-22T10:32:40.822Z","repository":{"id":75738043,"uuid":"46168911","full_name":"baoyongzhang/Treasure","owner":"baoyongzhang","description":"Very easy to use wrapper library for Android SharePreferences","archived":false,"fork":false,"pushed_at":"2018-08-07T02:42:55.000Z","size":258,"stargazers_count":508,"open_issues_count":5,"forks_count":56,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-05-26T05:09:38.514Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/baoyongzhang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-11-14T09:27:00.000Z","updated_at":"2025-05-02T16:26:27.000Z","dependencies_parsed_at":"2023-03-24T23:03:55.056Z","dependency_job_id":null,"html_url":"https://github.com/baoyongzhang/Treasure","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/baoyongzhang/Treasure","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baoyongzhang%2FTreasure","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baoyongzhang%2FTreasure/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baoyongzhang%2FTreasure/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baoyongzhang%2FTreasure/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/baoyongzhang","download_url":"https://codeload.github.com/baoyongzhang/Treasure/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baoyongzhang%2FTreasure/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266475472,"owners_count":23934967,"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-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"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":[],"created_at":"2024-08-09T13:01:39.747Z","updated_at":"2025-07-22T10:32:40.497Z","avatar_url":"https://github.com/baoyongzhang.png","language":"Java","funding_links":[],"categories":["Java","Libs","SharedPreference"],"sub_categories":["\u003cA NAME=\"Utility\"\u003e\u003c/A\u003eUtility"],"readme":"# Treasure\n\n[![Travis CI](https://travis-ci.org/baoyongzhang/Treasure.svg?branch=master) ](https://travis-ci.org/baoyongzhang/Treasure)[![Download](https://api.bintray.com/packages/baoyongzhang/maven/Treasure/images/download.svg) ](https://bintray.com/baoyongzhang/maven/Treasure/_latestVersion)[![Android Arsenal](https://img.shields.io/badge/Android%20Arsenal-Treasure-green.svg?style=true)](https://android-arsenal.com/details/1/2787)\n\n[English document](./README_EN.md)\n\n`Treasure`是一个Android平台上基于`SharePreferences`的偏好存储库，只需要定义接口，无需编写实现，默认支持`Serializable`和`Parcelable`。运行时0反射，不仅使用方便而且性能和原生写法几乎无差别。\n\n## 使用方法\n\n##### 1、添加依赖\n\n#### Gradle\n\n``` groovy\ncompile 'com.baoyz.treasure:treasure:0.7.4'\nannotationProcessor 'com.baoyz.treasure:treasure-compiler:0.7.4'\n```\n\n#### Gradle Plugin\n\n如果在多 Module 中同时使用 Treasure，会出现 `Multiple dex files define Lcom/baoyz/treasure/PreferencesFinder` 错误，使用 Treasure Gradle Plugin 可以解决这个错误。\n\n在 `buildscript` 中添加依赖\n\n``` groovy\ndependencies {\n    classpath 'com.baoyz.treasure:treasure-gradle:0.7.4'\n}\n```\n\n然后只在你的 Application Module 中 apply 插件，Library Module 不需要。\n\n``` groovy\napply plugin: 'com.baoyz.treasure'\n```\n\n如果没有多 Module 同时使用 Treasure 的情况，不需要使用这个插件。\n\n##### 2、定义接口\n\n``` java\n@Preferences\npublic interface SimplePreferences {\n\n    String getUsername();\n\n    void setUsername(String username);\n\n}\n\n```\n\n我们定义了一个`interface`，需要使用`@Preferences`注解进行声明。然后可以定义一系列的`get`、`set`方法，用于获取和设置值。方法名会作为存储的`key`，例如`getUsername()`和`setUsername()`的`key`就是`username`，也就是通过`setUsername()`设置的`value`可以通过`getUsername()`获取到，因为他们的`key`是一样的。\n\n##### 3、实例化\n\n``` java\nSimplePreferences preferences = Treasure.get(context, SimplePreferences.class);\npreferences.setUsername(\"Hello Treasure!\");\npreferences.getUsername(); // return \"Hello Treasure!\"\n```\n\n通过`Treasure.get()`方法可以获取指定的`Preferences`对象，之后可以调用`set`方法设置值，通过对应的`get`方法获取值。\n\n## 高级用法\n\n#### 多文件\n\n可以为一个`Preferences`生成多个文件，例如多账号管理，不同账号有不同`Preferences`。\n\n``` java\nTreasure.get(context, SimplePreferences.class, \"id_one\");\nTreasure.get(context, SimplePreferences.class, \"id_two\");\n```\n\n`Treasure`提供了一个重载的`get`方法，可以传入一个`String`类型的ID，不同ID返回的`Preferences`对象不同，保存的文件也不同。（感谢好基友[zzz40500](https://github.com/zzz40500)提出的建议）\n\n#### 默认值\n\n`@Default`注解可以指定`get`方法的默认值。\n\n``` java\n@Default(\"Hello Treasure!\")\nString getUsername();\n\n@Default(\"false\")\nboolean isLogin();\n\n// default is 1 hour\n@Default(\"1000 * 60 * 60\")\nlong getTimeout();\n\n@Default({\"hello\", \"world\", \"!\"})\nSet\u003cString\u003e getStringSet();\n```\n\n如果没有指定`@Default`那么默认值见下表。\n\n| 返回值类型        | 默认值   |\n| ------------ | ----- |\n| int          | 0     |\n| float        | 0f    |\n| long         | 0l    |\n| boolean      | false |\n| String       | null  |\n| Set\\\u003cString\u003e | null  |\n\n#### 提交类型\n\n设置值的默认提交类型是`edit().apply()`，如果想使用`edit().commit()`有三种方式。\n\n##### 1、全局\n\n``` java\n@Preferences(edit = Preferences.Edit.COMMIT)\npublic interface SimplePreferences\n```\n\n全局指定提交方式之后，所有的`set`方法都会以`commit()`方法提交数据。\n\n##### 2、注解指定方法\n\n``` java\n@Commit\nvoid setUsername(String username);\n```\n\n使用`@Commit`注解只对当前方法有效。\n\n##### 3、指定方法返回`boolean`\n\n``` java\nboolean setUsername(String username);\n```\n\n无论上面两种方式有没有设置，只要`set`方法的返回值是`boolean`，那么这个方法就会以`commit()`方法提交，并且返回`commit()`的结果。\n\n#### 移除数据\n\n``` java\n@Remove\nvoid removeUsername();\n\n@Remove\nvoid deleteTimeout();\n```\n\n使用`@Remove`注解修饰方法，调用方法移除对应`key`的数据。\n\n#### 清空数据\n\n``` java\n@Clear\nvoid clear();\n```\n\n可以声明一个方法，使用`@Clear`注解修饰，那么调用这个方法就会清空整个`Preferences`的数据。\n\n#### 有效期\n\n可以使用`@Expired`指定某个配置的有效期。开始时间是最后一次`set`的时间。`@Expired`可以修饰在`getter`和`setter`方法 ，效果相同。\n\n``` java\n// 10秒钟后过期\n@Expired(value = 10, unit = Expired.UNIT_SECONDS)\nString getTestExpired();\n```\n\n`@Expired`还可以修饰在方法参数上，用于动态指定有效时间，只能在`setter`方法的参数上修饰。\n\n``` java\n// second参数的值是有效时间，单位是UNIT_MINUTES（分钟）\nvoid setTestExpired(String value, @Expired(unit = Expired.UNIT_MINUTES) int second);\n```\n\n`@Expired`的`unit`不指定默认是`UNIT_MILLISECONDS`毫秒。\n\n#### 对象序列化\n\n如果`interface`中声明的数据类型不是`SharePreferences`支持的，需要用到转换器，`Treasure`默认提供`Serializable`和`Parcelable`的支持。\n\n``` java\n// Serializable or Parcelable\nclass User implements Serializable {...}\n\n// Preferences Interface\nvoid setUser(User user);\nUser getUser();\n```\n\n可以自定义转换规则，例如用`Gson`将对象以`JSON`的形式保存。\n\n``` java\npublic class GsonConverterFactory implements Converter.Factory {\n\n    @Override\n    public \u003cF\u003e Converter\u003cF, String\u003e fromType(Type fromType) {\n        return new Converter\u003cF, String\u003e() {\n            @Override\n            public String convert(F value) {\n                return new Gson().toJson(value);\n            }\n        };\n    }\n\n    @Override\n    public \u003cT\u003e Converter\u003cString, T\u003e toType(final Type toType) {\n        return new Converter\u003cString, T\u003e() {\n            @Override\n            public T convert(String value) {\n                return new Gson().fromJson(value, toType);\n            }\n        };\n    }\n}\n```\n\n自定义之后，需要调用`Treasure.setConverterFactory()`方法设置自定义的转换规则。\n\n``` java\nTreasure.setConverterFactory(new GsonConverterFactory());\n```\n\n#### 获取 SharedPreferences 对象\n\n``` java\n@Prototype\nSharedPreferences getSharedPreferences();\n```\n\n使用 `@Prototype` 修饰，返回值是 `SharedPreferences` 类型，调用此方法可以获取原始的 `SharedPreferences` 对象。\n\n#### 自定义 Key\n``` java\n@Key(\"custom_key\")\nString getValue();\n@Key(\"custom_key\")\nvoid setValue(String value);\n```\n\n#### 关于方法名\n\n如果方法名以`get`、`set`、`put`、`is`、`remove`、`delete`开头，那么会忽略这些前缀并且全部小写作为`key`，如果不包含这些前缀，那么方法名全部小写会作为`key`。\n\n#### Proguard\n\n`Treasure`运行时0反射，不需要添加`Proguard`配置。\n\n\n\n# 致谢\n\n[Favor](https://github.com/soarcn/Favor)（灵感来源）\n\n[javapoet](https://github.com/square/javapoet)\n\n\n\n# License\n\n``` \nThe MIT License (MIT)\n\nCopyright (c) 2015 baoyongzhang \u003cbaoyz94@gmail.com\u003e\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaoyongzhang%2FTreasure","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbaoyongzhang%2FTreasure","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaoyongzhang%2FTreasure/lists"}